go-agent

Minimal, multi-provider coding agent for the terminal — written in Go.

---

What is go-agent?

A terminal-based AI coding assistant that connects to Anthropic, OpenAI, Ollama, or any OpenAI-compatible endpoint. It reads your codebase, edits files, runs commands, and manages conversations — all from a single binary with zero dependencies.

Key features:

• Multi-provider — switch between Claude, GPT, Ollama, LM Studio, or any OpenAI-compatible API
• Built-in tools — bash, file read/write, surgical edits, glob, grep
• MCP support — connect external MCP servers for additional tools
• Session persistence — save and resume conversations
• Streaming — tokens appear as they arrive, with syntax highlighting
• Approval mode — review destructive actions before they execute
• Vi-mode REPL — readline with vi keybindings, tab completion, history

Quick start

Install

git clone https://github.com/baniol/go-agent.git
cd go-agent
make build        # → bin/go-agent

Run

Set your API key and start:

# Anthropic (Claude)
export ANTHROPIC_API_KEY=sk-ant-...
./bin/go-agent

# OpenAI
export OPENAI_API_KEY=sk-...
./bin/go-agent

# Local model (Ollama, LM Studio, vLLM, LiteLLM)
./bin/go-agent --provider openai-compatible --base-url http://localhost:1234

Provider is auto-detected from your API key. No --provider flag needed for Anthropic/OpenAI.

One-shot mode

./bin/go-agent -1 "explain this error" < error.log

Usage

Slash commands

Command	Description
/plan	Switch to plan mode (read-only tools, planning model)
/edit	Switch to edit mode (full tools, editing model)
/model [name]	Switch model (interactive picker if no name)
/compact	Summarize older messages to save context
/sessions	List saved sessions
/resume [id]	Resume a previous session
/skill <name> <prompt>	Run a skill with prompt
/mcp	Show MCP server status
/approve	Toggle approval mode
/clear	Clear conversation history
/quit	Exit

Tools

The agent has access to these built-in tools:

Tool	Description
bash	Run shell commands
read_file	Read file contents
write_file	Write or create files
edit	Surgical string replacement
glob	Find files by pattern
grep	Search file contents by regex

Additional tools can be added via MCP servers.

Plan / Edit mode

Use a stronger model for analysis and a faster one for code changes:

• /plan — read-only mode. Only read_file, glob, grep, and bash are available. The system prompt instructs the model to analyze and plan without making changes. Switches to the configured plan_model.
• /edit — full mode (default). All tools available. Switches to the configured edit_model.

Configure per-mode models in config.json:

{
  "default_provider": "ollama",
  "providers": {
    "ollama": {
      "model": "qwen3-coder:7b",
      "plan_model": "qwen3-coder:32b",
      "edit_model": "qwen3-coder:7b"
    }
  }
}

If plan_model or edit_model is not set, the agent stays on the current model when switching modes. The prompt shows [plan] when in plan mode.

Configuration

Settings are layered: config file → env vars → CLI flags (flags win).

Config file

Optional. Create ~/.go-agent/config.json:

{
  "default_provider": "ollama",
  "providers": {
    "anthropic": {
      "api_key": "sk-ant-...",
      "model": "claude-sonnet-4-20250514"
    },
    "openai": {
      "api_key": "sk-...",
      "model": "gpt-4o"
    },
    "openai-compatible": {
      "base_url": "http://localhost:1234",
      "model": "qwen/qwen3.5-9b"
    },
    "ollama": {
      "model": "qwen3-coder:7b",
      "plan_model": "qwen3-coder:32b",
      "edit_model": "qwen3-coder:7b"
    }
  }
}

All fields are optional. If default_provider is omitted, it's auto-detected from available API keys. plan_model and edit_model are optional per-mode model overrides (see Plan / Edit mode).

Skills

Skills are reusable instruction sets that get injected into the conversation before your prompt. They live in ~/.go-agent/skills/<name>/SKILL.md.

/skill                                    # list available skills
/skill drawio create a login flowchart    # run skill with prompt

Example: draw.io diagrams

The draw.io skill teaches the agent to generate native .drawio XML files with optional PNG/SVG/PDF export.

Setup:

mkdir -p ~/.go-agent/skills/drawio/references

# from https://github.com/jgraph/drawio-mcp/tree/main/skill-cli
cp drawio/SKILL.md              ~/.go-agent/skills/drawio/SKILL.md
cp references/xml-reference.md  ~/.go-agent/skills/drawio/references/xml-reference.md

Usage:

/skill drawio architecture diagram with API gateway, auth service, and postgres

Creating your own skill

Create ~/.go-agent/skills/<name>/SKILL.md with instructions for the agent. The entire file content is prepended to your prompt as context.

MCP servers

Add external tool servers in ~/.go-agent/config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}

Compatible with Claude Code/Desktop format. Use "disabled": true to keep config without connecting.

Environment variables

Variable	Description
GO_AGENT_PROVIDER	Provider: anthropic, openai, or openai-compatible
ANTHROPIC_API_KEY	Anthropic API key
OPENAI_API_KEY	OpenAI API key
OPENAI_BASE_URL	Base URL for openai-compatible endpoints
OLLAMA_HOST	Ollama endpoint (default: http://localhost:11434)

CLI flags

Flag	Description
--provider	anthropic, openai, openai-compatible, or ollama
--base-url	Base URL for openai-compatible endpoints
--api-key	API key
--model	Model name
--prompt	Path to custom system prompt template
--resume	Resume session by ID (omit ID for picker)
--one-shot, -1	Send prompt, get response, exit
--no-approve	Disable approval mode
--markdown	Enable glamour-based markdown rendering

Development

make build        # build binary
make run          # build + run
make check-all    # fmt + vet + lint + test
make fmt          # auto-format
make setup-hooks  # enable pre-commit hook

License

MIT