GoCode

Open-Source AI Terminal Coding Agent

A high-performance, Go-native, local-first AI coding agent for your command line.

Overview • Features • Quick Start • Configuration • FAQ

Overview

GoCode is a lightweight, open-source AI terminal coding agent written in Go. It turns your command line into an interactive pair programming environment capable of reading project files, editing code via structured patches, executing shell commands, and debugging errors in real time—all with strict human-in-the-loop approval.

Unlike heavy Python-based or Node.js-based AI CLI tools, GoCode compiles into a single, zero-dependency binary with instant startup latency and minimal memory footprint.

GoCode is provider-agnostic and local-first: run completely offline with local LLMs via Ollama or llama.cpp, or connect seamlessly to leading cloud AI models from Google Gemini, Anthropic Claude, OpenAI, Groq, OpenRouter, Qwen, Kimi, OpenCode Zen, and more.

Features

Core Capabilities

Single Native Go Binary — Fast startup, low resource usage, zero Python or Node.js dependencies
Local-First & Privacy-Focused — Runs 100% offline with local models via Ollama or llama.cpp
20 Built-in Provider Gateways — Ollama, OpenAI, Gemini, Claude, GitHub Copilot, xAI (SpaceXAI), Mistral, MiniMax, DeepSeek, Groq, OpenRouter, Together, Fireworks, Cerebras, Zhipu, NVIDIA NIM, Qwen, Kimi, Hermes Agent, and OmniRoute
Custom API Endpoints — add any OpenAI Chat Completions-compatible service, including local llama.cpp, with its own base URL and API-key environment variable
Human-in-the-Loop Approval Gate — Explicit confirmation before executing commands or modifying files
Enforced Workspace Boundary (file tools) — file_read/file_write/file_patch/code_search are confined to the workspace, traversal- and symlink-proof, and blocked from sensitive files. shell_exec is not confined — see What is actually enforced
On-the-Fly Switching — Switch providers or models dynamically with /provider and /model commands

Changelog

See CHANGES.md for the full per-version history, starting with v0.7.0.

Quick Start

Prerequisites

Go 1.26+ installed (if building from source)
An active AI provider: Ollama for local execution, or an API key for cloud providers

Installation

Option 1: npm / npx / bunx (Recommended)

# One-shot, no install
npx gocode-cli
bunx gocode-cli

# Or install globally
npm install -g gocode-cli
bun install -g gocode-cli

Option 2: Install via `go install`

go install github.com/mevarx/GoCode/cmd/gocode@latest

Option 3: Build from Source

git clone https://github.com/mevarx/GoCode.git
cd GoCode
go build -o gocode ./cmd/gocode/
./gocode

Option 4: Download Binary

Download pre-built binaries from the Releases page.

Basic Usage

# Auto-resume last session (default behavior)
gocode

# Start a fresh session
gocode --new

# Resume a specific session
gocode --session sess_20260815190405_a1b2c3d4

# Use a specific provider and current model
gocode --provider openai --model gpt-6-astra

# Plain terminal mode (no TUI)
gocode --tui=false

# Enable debug logging
gocode -v

Session Management

GoCode persists conversations to SQLite and auto-resumes the last session by default. Set persist = false under [session] to keep a conversation entirely in memory — nothing is written to disk and nothing is resumed on the next run.

# List saved sessions
/sessions

# Resume a specific session
/sessions <id>
/resume <id>

# Start a fresh session
/new

Sessions are stored in ~/.local/share/gocode/sessions/sessions.db (Linux/macOS) or %LOCALAPPDATA%\gocode\sessions\sessions.db (Windows).

Model Context Protocol (MCP)

Extend GoCode with any external MCP server over stdio JSON-RPC 2.0:

# Add an MCP server
gocode mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /path/to/repo

# List configured MCP servers
gocode mcp list

# Remove an MCP server
gocode mcp remove filesystem

MCP tools are automatically registered into the agent's tool catalog upon startup.

Server commands routinely take their own flags, so everything from the first non-flag token onward belongs to the server. Put GoCode's own flags before the server name:

gocode --config /path/to/config.toml mcp add filesystem npx -y @scope/server .

If you need --config after the command, separate the sections with --:

gocode mcp add filesystem npx -y @scope/server . -- --config /path/to/config.toml

A --config that appears after the server command without a -- separator is treated as the server's own flag.

Project & Global Context

Project Context (`AGENTS.md`)

When launching in any workspace, GoCode automatically traverses the current directory and all parent folders searching for:

AGENTS.md
.gocode/AGENTS.md
docs/AGENTS.md

If found, its instructions are injected under ## Project Context in the system prompt.

Global Context (`CONTEXT.md`)

Create ~/.config/gocode/CONTEXT.md (or %APPDATA%\gocode\CONTEXT.md on Windows) for global rules across all repositories (e.g., coding preferences, language versions).

`.gocodeignore` File Filtering

Create a .gocodeignore file in your repository root to prevent GoCode tools from reading, writing, or listing sensitive files:

# .gocodeignore
.env*
secrets/
*.pem
*.key
credentials.json

If .gocodeignore is absent, GoCode automatically falls back to .gitignore.

Supported AI Providers

Provider	`--provider`	Environment Variable	Current model example	Base URL
Google Gemini	`gemini`	`GEMINI_API_KEY`	`gemini-3.8-flash`	`https://generativelanguage.googleapis.com/v1beta/openai`
Anthropic Claude	`anthropic`	`ANTHROPIC_API_KEY`	`claude-opus-5-5`	`https://api.anthropic.com/v1`
OpenAI	`openai`	`OPENAI_API_KEY`	`gpt-6-astra`	`https://api.openai.com/v1`
GitHub Copilot	`copilot`	`GITHUB_COPILOT_TOKEN`	`gpt-4.1`	dynamic, see below
xAI (SpaceXAI)	`xai`	`XAI_API_KEY`	`grok-code-fast-1`	`https://api.x.ai/v1`
Mistral	`mistral`	`MISTRAL_API_KEY`	`mistral-large-latest`	`https://api.mistral.ai/v1`
MiniMax	`minimax`	`MINIMAX_API_KEY`	`MiniMax-M2.5`	`https://api.minimax.io/v1`
DeepSeek	`deepseek`	`DEEPSEEK_API_KEY`	`deepseek-chat`	`https://api.deepseek.com/v1`
Groq	`groq`	`GROQ_API_KEY`	List with `/models`	`https://api.groq.com/openai/v1`
OpenRouter	`openrouter`	`OPENROUTER_API_KEY`	List with `/models`	`https://openrouter.ai/api/v1`
Together	`together`	`TOGETHER_API_KEY`	`Qwen/Qwen3-Coder-480B-A35B-Instruct`	`https://api.together.xyz/v1`
Fireworks	`fireworks`	`FIREWORKS_API_KEY`	List with `/models`	`https://api.fireworks.ai/inference/v1`
Cerebras	`cerebras`	`CEREBRAS_API_KEY`	`qwen-3-coder-480b`	`https://api.cerebras.ai/v1`
Zhipu (GLM)	`zhipu`	`ZHIPU_API_KEY`	`glm-4.6`	`https://open.bigmodel.cn/api/paas/v4`
NVIDIA NIM	`nvidia`	`NVIDIA_API_KEY`	`qwen/qwen3-coder-480b-a35b-instruct`	`https://integrate.api.nvidia.com/v1`
Qwen (DashScope)	`qwen`	`DASHSCOPE_API_KEY`	List with `/models`	`https://dashscope.aliyuncs.com/compatible-mode/v1`
Kimi (Moonshot)	`kimi`	`MOONSHOT_API_KEY`	List with `/models`	`https://api.moonshot.cn/v1`
Hermes Agent	`hermes`	`HERMES_API_SERVER_KEY`	`hermes-agent`	`http://127.0.0.1:8642/v1`
OmniRoute Proxy	`omniroute`	`OMNIROUTE_API_KEY`	`auto`	`http://localhost:20128/v1`
Ollama (Local)	`ollama`	None	Auto-detected	`http://localhost:11434`

Model catalogs change frequently. Use /providers to list the models currently exposed by a provider and /model <id> to select one. The examples above are current recommended identifiers, not guarantees of account access; provider quotas, regions, and plan availability still apply.

GitHub Copilot

Copilot is not a plain bearer-token API, so it has its own provider. It uses two layers: a long-lived GitHub OAuth token is exchanged for a short-lived Copilot JWT, and that exchange also returns the API address to use. The JWT is cached and refreshed shortly before it expires.

Log in once with GitHub's device flow, using a client id from an OAuth App you register at github.com/settings/developers:

gocode auth copilot --client-id <your-oauth-app-client-id>
gocode --provider copilot

The token is written to <config-dir>/copilot_token with owner-only permissions and read automatically; GITHUB_COPILOT_TOKEN takes precedence when set. A device flow is required because Copilot has no copy-paste API key — you cannot use a plain PAT here. An active Copilot subscription is required; the exchange returns a clear error when the account has none.

The token exchange endpoint and the Editor-Version headers are reverse-engineered from GitHub's own VS Code extension and are not documented by GitHub. They can change or be removed without notice, so treat Copilot support as best-effort.

Connect to a Hermes Agent instance

If you run Hermes Agent, its API server speaks the OpenAI Chat Completions API on 127.0.0.1:8642, so it can serve as GoCode's backend — and GoCode as Hermes'. Enable it in Hermes first:

# in ~/.hermes/.env
API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev

Then point GoCode at it:

export HERMES_API_SERVER_KEY="change-me-local-dev"
gocode --provider hermes

The model is hermes-agent by default (a Hermes profile advertises its profile name instead). Use --model to override.

Add another API endpoint

Use a named custom provider for a company gateway or any other service that implements the OpenAI Chat Completions API but is not built in:

gocode provider add my-gateway \
  --base-url https://gateway.internal/v1 \
  --api-key-env MY_GATEWAY_KEY \
  --model my-model

export MY_GATEWAY_KEY="your-key"
gocode --provider my-gateway
gocode provider list

Provider configuration stores the environment-variable name, not the key. Custom endpoints can also be managed with gocode provider remove <name> and live in [provider.custom.<name>] in config.toml. To make one the default, set default = "my-gateway" in [provider]; otherwise select it with gocode --provider my-gateway. The endpoint must support OpenAI Chat Completions; use the built-in anthropic provider for Anthropic's native API.

A custom provider you added earlier keeps working even if its name has since become a built-in — your saved endpoint wins over the built-in default rather than being silently replaced.

Connect a llama.cpp server

llama-server exposes an OpenAI-compatible API, so connect it as a custom provider. Start the server with the model you want to use:

llama-server -m /path/to/model.gguf --host 127.0.0.1 --port 8080

Register the endpoint with GoCode (no API key is required for a local server):

gocode provider add llama-cpp \
  --base-url http://127.0.0.1:8080/v1 \
  --model <model-id-from-v1-models>

gocode --provider llama-cpp

The model ID must match the identifier returned by GET http://127.0.0.1:8080/v1/models; use that endpoint to discover the exact ID. For a server exposed on another machine, use HTTPS or a trusted reverse proxy rather than exposing an unauthenticated HTTP port to the internet.

Connect OpenCode Zen free models directly

GoCode can call the OpenCode Zen gateway directly as an OpenAI-compatible provider. This avoids an unofficial third-party proxy. Create an API key in the OpenCode console, then configure the official Zen endpoint:

gocode provider add opencode-zen \
  --base-url https://opencode.ai/zen/v1 \
  --api-key-env OPENCODE_API_KEY \
  --model deepseek-v4-flash-free

export OPENCODE_API_KEY="your-opencode-api-key"
gocode --provider opencode-zen
gocode --provider opencode-zen --model mimo-v2.5-free

Zen currently lists free models including deepseek-v4-flash-free, mimo-v2.5-free, nemotron-3-ultra-free, north-mini-code-free, and big-pickle. Free-model availability, limits, and IDs can change, so inspect the live catalog before selecting a model:

curl https://opencode.ai/zen/v1/models \
  -H "Authorization: Bearer $OPENCODE_API_KEY"

Use /providers in GoCode to list what the configured gateway currently returns. OpenCode Zen is a hosted service, not a local or guaranteed unlimited free tier; use the current Zen model catalog for pricing and availability.

In-Session Slash Commands

Command	Description
`/sessions`	List saved sessions with timestamps and message counts
`/sessions <id>`	Switch to and resume an existing session
`/new`	Start a fresh session and clear current context
`/commit [message]`	Stage and commit modified files with `Assisted-by:` trailer
`/providers`	View active provider and list all available models
`/provider <name>`	Switch active provider
`/model`	Show current active model
`/model <name>`	Change model on the fly (validated against the active provider's model list)
`/clear`	Clear conversation history while retaining system instructions
`/help`	Display help and available commands
`Ctrl+L` (TUI)	Open interactive fuzzy model search picker
`Ctrl+C` (TUI)	Stop a running turn; press again (or when idle) to quit
`Esc` (TUI)	Stop a running turn, or clear the current input
(TUI status bar)	Shows the active provider, model, and workspace
`exit`, `quit`, `/exit`, `/quit`	Exit the agent session

Configuration

Configuration is stored at:

Linux / macOS: ~/.config/gocode/config.toml
Windows: %APPDATA%\gocode\config.toml

Comprehensive `config.toml` Example

[provider]
default = "gemini"

[provider.ollama]
host = "http://localhost:11434"
default_model = ""

[provider.gemini]
base_url = "https://generativelanguage.googleapis.com/v1beta/openai"
api_key_env = "GEMINI_API_KEY"
default_model = "gemini-3.8-flash"

[provider.anthropic]
base_url = "https://api.anthropic.com/v1"
api_key_env = "ANTHROPIC_API_KEY"
default_model = "claude-opus-5-5"

[provider.openai]
base_url = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"
default_model = "gpt-6-astra"

# GitHub Copilot uses two-layer auth: the OAuth token below is exchanged for a
# short-lived JWT at request time. Set it with `gocode auth copilot`, which
# writes to <config-dir>/copilot_token, or export it yourself.
[provider.copilot]
oauth_token_env = "GITHUB_COPILOT_TOKEN"
default_model = "gpt-4.1"
editor_version = "vscode/1.111.0"
editor_plugin_version = "copilot-chat/0.40.0"

# Every other built-in gateway is configured the same way. Only the section you
# want to change needs to appear in your file; the rest come from defaults.
# [provider.xai]
# base_url = "https://api.x.ai/v1"
# api_key_env = "XAI_API_KEY"
# default_model = "grok-code-fast-1"

# [provider.hermes]
# base_url = "http://127.0.0.1:8642/v1"
# api_key_env = "HERMES_API_SERVER_KEY"
# default_model = "hermes-agent"

[permissions]
auto_approve = ["file_read", "code_search"]  # Tools that execute without confirmation
deny = []                                    # Tools that are permanently blocked
sensitive_patterns = ["*.vault", "custom.env"] # Additional patterns to block from AI access

[session]
persist = true                # Set false to keep the conversation out of the SQLite store

[tools]
max_tool_iterations = 50      # Cap provider round-trips per turn
max_repeated_tool_calls = 3   # Cap identical tool calls (same name + arguments) per turn

[tools.shell]
timeout_seconds = 30      # Maximum seconds a shell command may run
max_output_bytes = 1048576 # Cap captured stdout+stderr per command
redact_secrets = true      # Mask credential-shaped values in command output

[mcp.servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]

Logs & Diagnostics

# Diagnostic health check of all configured providers
gocode doctor

# View the last 50 log lines
gocode logs --tail 50

# Continuously follow live log output
gocode logs --follow

Tools & Security Architecture

GoCode operates under a strict Human-in-the-Loop Security Architecture. The agent cannot mutate your workspace or run commands without explicit terminal authorization.

Tool Name	Purpose	Approval Gate
`file_read`	Inspect file contents and workspace context (with line offset/limit)	Automatic
`code_search`	Search files via regex/plain text with context lines & glob filtering	Automatic
`file_write`	Create new files or overwrite existing files (with unified diff preview)	Requires Confirmation
`file_patch`	Perform target string replacements & targeted code edits (with unified diff preview)	Requires Confirmation
`shell_exec`	Run terminal commands in the workspace working directory (not confined — see below)	Requires Confirmation

Tools can be auto-approved or denied via the [permissions] section in config.toml.

What is actually enforced

Being precise about the boundary matters more than claiming the widest one, so here is exactly where each control applies.

The file tools are confined. file_read, file_write, file_patch and code_search resolve every path through the workspace root, reject traversal, and re-verify after resolving symlinks. Protected patterns (.env*, SSH keys, certificates, cloud credentials) are unconditionally blocked from inspection by these tools.

The shell is not confined. shell_exec runs a command string through your shell with the workspace as its working directory. A working directory is not a sandbox: a command can read any file your user account can read, anywhere on the machine. GoCode cannot reliably prevent this — command substitution, pipes and interpreters defeat any static inspection of a shell string.

What GoCode does instead, for shell_exec:

Secret redaction — credential-shaped values in command output (API keys, tokens, private key blocks, AWS keys, JWTs, KEY=value secrets) are masked before the output reaches the model or is written to your session transcript. Disable with redact_secrets = false.
Advisory warnings — a command that references a known-sensitive path is flagged in the approval prompt so you can decline it.
The approval gate — the real protection. Keep shell_exec out of auto_approve and read the command before approving.

If you need a hard boundary, either deny shell_exec outright:

[permissions]
deny = ["shell_exec"]

…or treat the approval prompt as the trust boundary it actually is. Do not put shell_exec in auto_approve on a machine holding credentials.

Architecture

gocode/
├── cmd/gocode/           # CLI entry point, flag parsing & subcommands
├── internal/
│   ├── agent/            # Core agent loop, session memory & slash commands
│   ├── config/           # Platform directory management & TOML parser
│   ├── provider/         # Unified provider registry (Ollama, OpenAI-compatible, Anthropic)
│   ├── tools/            # Tool registry, shell execution, patch engine & approval gates
│   ├── session/          # SQLite-backed session persistence
│   ├── mcp/              # Model Context Protocol stdio client
│   ├── ignore/           # .gocodeignore/.gitignore pattern matching
│   └── tui/              # Interactive TUI (Bubble Tea model, styles & approval prompts)
├── .github/workflows/    # GitHub Actions CI/CD
├── .goreleaser.yaml      # GoReleaser release configuration
├── Makefile              # Build, test, and release targets
└── go.mod                # Module definition

GoCode vs. Other AI Coding Agents

Feature	GoCode	Cursor	Aider	GitHub Copilot CLI
Open Source	MIT	Proprietary	Apache-2.0	Proprietary
Language & Runtime	Native Go Binary	Electron / TS	Python Runtime	Node.js / CLI
Local LLM Support	Built-in	Limited	Yes	Cloud-only
Cloud Providers	20 Gateways	Proprietary	Various APIs	GitHub / OpenAI
Human Approval Control	Explicit Gate	Semi-auto	Auto/Prompt	Auto
Session Persistence	SQLite	Yes	No	No
MCP Support	stdio	Yes	Yes	No
Memory Footprint	Extremely Low (<20MB)	High	Moderate	Moderate

FAQ

What is GoCode used for?

GoCode is an open-source terminal AI coding assistant used for automated code generation, code refactoring, bug fixing, test writing, project directory inspection, and command-line automation.

Can GoCode run completely offline?

Yes. GoCode connects natively to Ollama (http://localhost:11434) or a llama.cpp server (http://localhost:8080/v1). You can run open-weights models such as llama3.3, deepseek-coder, or qwen-coder with zero internet access and complete data privacy.

How does GoCode compare to Cursor or Aider?

Unlike Cursor (which is an Electron IDE extension) or Aider (which runs on Python), GoCode is a compiled Go binary that runs directly in any terminal (Linux, macOS, Windows). It offers sub-millisecond startup, minimal memory consumption, and a human-in-the-loop approval gate for safe command execution.

Which LLM API providers does GoCode support?

GoCode supports 20 built-in provider gateways plus custom OpenAI-compatible endpoints: Ollama, OpenAI, Anthropic Claude, Google Gemini, Groq, OpenRouter, Together, Fireworks, Cerebras, Zhipu, NVIDIA NIM, Qwen (Aliyun DashScope), Kimi (Moonshot AI), Mistral, MiniMax, DeepSeek, xAI, OmniRoute, Hermes Agent, and GitHub Copilot.

Is GoCode free to use?

Yes, GoCode is 100% free and open-source software licensed under the MIT License. When paired with local Ollama models, it is completely free to operate with no subscription or API costs.

How do I extend GoCode with new tools?

GoCode supports the Model Context Protocol (MCP). You can add any MCP server via gocode mcp add <name> <command> [args...] and its tools will be automatically available to the agent.

Where are sessions stored?

Sessions are stored in a SQLite database at ~/.local/share/gocode/sessions.db (Linux/macOS) or %LOCALAPPDATA%\gocode\sessions.db (Windows). Use gocode --new to start fresh or /sessions to list and resume past sessions.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

GoCode is licensed under the MIT License — see the LICENSE file for details.

Built with Bubble Tea v2 • Powered by Go

Made with ❤️ by mevarx

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.hoplite		.hoplite
cmd/gocode		cmd/gocode
internal		internal
npm		npm
.gitattributes		.gitattributes
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
CHANGES.md		CHANGES.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Latest commit

History

Folders and files

Repository files navigation

GoCode

Open-Source AI Terminal Coding Agent

Overview

Features

Core Capabilities

Changelog

Quick Start

Prerequisites

Installation

Option 1: npm / npx / bunx (Recommended)

Option 2: Install via go install

Option 3: Build from Source

Option 4: Download Binary

Basic Usage

Session Management

Model Context Protocol (MCP)

Project & Global Context

Project Context (AGENTS.md)

Global Context (CONTEXT.md)

.gocodeignore File Filtering

Supported AI Providers

GitHub Copilot

Connect to a Hermes Agent instance

Add another API endpoint

Connect a llama.cpp server

Connect OpenCode Zen free models directly

In-Session Slash Commands

Configuration

Comprehensive config.toml Example

Logs & Diagnostics

Tools & Security Architecture

What is actually enforced

Architecture

GoCode vs. Other AI Coding Agents

FAQ

What is GoCode used for?

Can GoCode run completely offline?

How does GoCode compare to Cursor or Aider?

Which LLM API providers does GoCode support?

Is GoCode free to use?

How do I extend GoCode with new tools?

Where are sessions stored?

Contributing

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Option 2: Install via `go install`

Project Context (`AGENTS.md`)

Global Context (`CONTEXT.md`)

`.gocodeignore` File Filtering

Comprehensive `config.toml` Example