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
• Multiline REPL — Bubble Tea textarea with multiline editing, tab completion, @-file paths

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.

Usage

Slash commands

Command	Description
/help	Show available commands
/provider [name]	Switch provider (interactive picker if no name)
/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

Typing just / opens an interactive command picker.

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.

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"
    }
  }
}

All fields are optional. If default_provider is omitted, it's auto-detected from available API keys.

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)
--no-approve	Disable approval mode
--markdown	Enable glamour-based markdown rendering
--debug	Enable debug logging to ~/.go-agent/agent.log
--flow	Log agent flow steps to ~/.go-agent/agent.log

Logging

All logs go to ~/.go-agent/agent.log. The file is always created on startup; the log level controls what gets written.

Log levels

Set the level in ~/.go-agent/config.json:

{ "log_level": "debug" }

Level	What is logged
warn (default)	MCP connection errors, session save failures
info	MCP server startup (mcp ready, mcp connecting)
debug	Everything: turn start/done, each tool call with key params, tool errors, token usage

--debug flag overrides the config level to debug for the current run.

Debug log entries

With --debug, each turn produces entries like:

level=DEBUG msg="turn start"   messages=5  query="refactor the auth handler"
level=DEBUG msg="tool call"    name=read_file   path=internal/auth/handler.go
level=DEBUG msg="tool done"    name=read_file   lines=87  preview="package auth"
level=DEBUG msg="tool call"    name=bash        cmd="go build ./..."
level=DEBUG msg="tool error"   name=bash        err="exit status 1: undefined: Foo"
level=DEBUG msg="turn done"    tool_calls=3     in=4821  out=312

Flow tracing

--flow logs each step of the agent loop without the noise of full debug mode:

./bin/go-agent --flow

level=INFO msg="[flow] → request"   provider=ollama  messages=2  tools=8
level=INFO msg="[flow] ← tool_call" name=read_file   id=call_abc123
level=INFO msg="[flow]   input"     json="{\"path\":\"main.go\"}"
level=INFO msg="[flow]   executing" name=read_file
level=INFO msg="[flow]   result"    name=read_file   length=1247
level=INFO msg="[flow] → result"    tool_id=call_abc123  is_error=false
level=INFO msg="[flow] → request"   provider=ollama  messages=4  tools=8
level=INFO msg="[flow] ← response"  chars=312

The second → request shows the agent looping back with the tool result — the core of the agentic loop.

Watching logs live

tail -f ~/.go-agent/agent.log

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

See docs/ for architecture notes and deep dives.

License

MIT