GoCode

A native Go AI coding agent for your terminal.

Quick Start •
Features •
Security •
Configuration •
Contributing

GoCode helps you explore, write, refactor, and debug code from your command line. Connect your preferred AI provider, use a local model, and keep control over file changes and shell commands through explicit approval.

• Native Go CLI: a self-contained executable with no separate Python or Node.js runtime required.
• Your choice of models: 20 built-in provider gateways, any OpenAI-compatible endpoint, or a local backend such as Ollama or llama.cpp.
• Controlled execution: review diffs and approve commands before they run.
• Persistent sessions: SQLite-backed history that resumes where you left off.
• Extensible: add external tools through the Model Context Protocol (MCP).

Quick Start

1. Install

npm install -g gocode-cli

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

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

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

Pre-built binaries are available on the Releases page.

Building from source requires Go 1.26.8 or newer (see go.mod).

2. Connect a provider

Cloud provider (example: Gemini):

export GEMINI_API_KEY="your-key"
gocode --provider gemini

Local model (example: Ollama):

ollama serve                 # in another terminal, with a model already pulled
gocode --provider ollama

3. Start working

gocode

Then ask for something concrete, such as "Find where config is loaded and explain the precedence order." GoCode asks for confirmation before it writes files or runs commands.

Common commands

TUI keys: Ctrl+L opens the model picker, Esc stops a running turn or clears input, and Ctrl+C stops a turn (press again to quit).

Features

File and shell tools

Change which tools need approval with the [permissions] section of config.toml. See Security before auto-approving anything.

Providers

Switch providers and models at any time with /provider and /model. GoCode ships with gateways for:

Ollama, OpenAI, Anthropic Claude, Google Gemini, GitHub Copilot, xAI, Mistral, MiniMax, DeepSeek, Groq, OpenRouter, Together, Fireworks, Cerebras, Zhipu, NVIDIA NIM, Qwen, Kimi, Hermes Agent, and OmniRoute.

Model catalogs change often. Use /providers to list the models a provider currently exposes and /model <id> to select one. Availability still depends on your account, region, and plan.

Add any OpenAI-compatible endpoint (company gateways, llama.cpp, OpenCode Zen, and others):

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

Only the environment-variable name is stored, never the key. Manage endpoints with gocode provider list and gocode provider remove <name>. Setup guides for Copilot, Hermes, llama.cpp, and OpenCode Zen are in docs/providers.md.

Local models

GoCode supports offline workflows when a local model and its backend (Ollama or a llama.cpp llama-server) are installed, running, and configured. Nothing is sent to a cloud provider unless you select one.

Sessions

Conversations are saved to SQLite and the last session resumes automatically.

/sessions            # list saved sessions
/sessions <id>       # switch to a session (alias: /resume <id>)
/new                 # start fresh

Exporting sessions

Export conversation transcripts from the stored SQLite history to Markdown or JSON:

# Export the latest session to stdout (Markdown)
gocode session export

# Export a specific session to a file
gocode session export <session_id> --output transcript.md

# Export as JSON without tool calls/results
gocode session export --format json --no-tools --output transcript.json

# Explicitly permit overwriting an existing destination
gocode session export --output transcript.md --force

• Formats: Markdown (.md, default) and JSON (.json).
• Privacy: Internal system prompts and model reasoning chains are always excluded from exports.
• File safety: Destination files are created with 0600 permissions on POSIX systems (owner read/write only). Existing files are never overwritten unless --force is provided.
• Tools: Tool invocations and results are included by default; pass --no-tools to omit them.

Sessions live at ~/.local/share/gocode/sessions/sessions.db on Linux and macOS, and %LOCALAPPDATA%\gocode\sessions\sessions.db on Windows. Set persist = false under [session] to keep a conversation in memory only, with nothing written to disk.

Project and global context

GoCode searches the current directory and its parents for AGENTS.md, .gocode/AGENTS.md, or docs/AGENTS.md and injects it into the system prompt as delimited untrusted repository data (## Project Context (untrusted repository data)), after the safety rules; this text cannot override the approval policy.

For rules that apply to every repository, create ~/.config/gocode/CONTEXT.md (%APPDATA%\gocode\CONTEXT.md on Windows).

Ignore rules: .gocodeignore

Keep sensitive files away from GoCode's file tools by adding a .gocodeignore to your repository root:

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

If .gocodeignore is missing, GoCode falls back to .gitignore. On case-insensitive filesystems (Windows and macOS), patterns match regardless of letter case, so .ENV is treated the same as .env. On Linux, matching stays case-sensitive.

MCP servers

Extend GoCode with any MCP server over stdio:

gocode mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /path/to/repo
gocode mcp list
gocode mcp remove filesystem

MCP tools are registered into the agent's tool catalog on startup. Everything after the server name belongs to the server, so put GoCode's own flags first:

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

To pass --config to the server instead, separate the sections with --:

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

Security

GoCode is built around human-in-the-loop approval: the agent cannot write files or run commands without your confirmation unless you explicitly auto-approve a tool.

File tools are confined. file_read, file_write, file_patch, and code_search resolve every path through the workspace root, reject traversal, and re-check after resolving symlinks. Sensitive files (.env*, SSH keys, certificates, cloud credentials) and anything matched by your ignore rules are blocked.

Credentials stay out of files. On POSIX systems config.toml and gocode.log are created owner-only (0600; their directories 0700), and a config or log file with looser permissions is tightened when it is loaded. Prefer api_key_env over inline api_key: an inline key is stored in plaintext, so gocode doctor prints a warning for every provider that uses one. Provider base URLs are validated at load time: HTTPS is required except for localhost/loopback, and URLs containing embedded credentials, a query, or a fragment are rejected.

The shell is not confined. shell_exec uses the workspace as its working directory, which is not a sandbox. A command can read anything your user account can read. Static inspection cannot reliably prevent this, since command substitution, pipes, and interpreters defeat it. GoCode instead provides:

• Secret redaction: tool results, tool-call arguments, and session exports are always redacted before reaching the model or your transcript — this cannot be disabled. The [tools.shell] redact_secrets setting controls only masking of shell_exec command output before it enters the tool result; setting it to false is not recommended.
• Credential-free child env: child processes (shell commands and MCP servers) do not inherit credential-shaped environment variables by default. Names matching patterns such as *_API_KEY, *_TOKEN, *_SECRET, *_KEY, and *_CREDENTIALS — plus every configured provider api_key_env — are removed. Add more names or patterns with [tools.shell] env_scrub. Essential variables (PATH, HOME, SystemRoot, TEMP, …) always survive so commands still run.
• Advisory warnings: commands referencing known-sensitive paths are flagged in the approval prompt.
• The approval gate: your real protection. Read each command before approving it. Answers are y (once), a (allow these exact arguments for the rest of the session; identical calls then run without prompting and are marked (session grant)), r (allow tools that declare themselves read-only for the current turn), e (edit the arguments before deciding; plain terminal only), and n (deny). Grants are in-memory, die with the process, and never widen to different arguments — those prompt again.

Recommendations

• Keep shell_exec out of auto_approve, especially on machines that hold credentials.

• For a hard boundary, deny the shell entirely:

  [permissions]
  deny = ["shell_exec"]
  

• Run GoCode in a container or VM if you need real isolation.

Details and the full threat model: docs/SECURITY.md.

Configuration

Config file location:

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

A minimal example:

[provider]
default = "gemini"

[provider.gemini]
api_key_env = "GEMINI_API_KEY"   # preferred: the key stays in the environment, not in this file
default_model = "gemini-3.8-flash"

[permissions]
auto_approve = ["file_read", "code_search"]  # run without confirmation
deny = []                                    # permanently blocked
sensitive_patterns = ["*.vault"]             # extra patterns hidden from the AI

[session]
persist = true

[tools]
max_tool_iterations = 50      # provider round-trips per turn
max_repeated_tool_calls = 3   # identical tool calls per turn

[tools.shell]
timeout_seconds = 30
max_output_bytes = 1048576
redact_secrets = true         # mask shell_exec output; transcript/export redaction is always on
# Extra env var names or glob patterns to remove from child processes,
# on top of the built-in credential patterns.
env_scrub = ["MY_GATEWAY_KEY", "TEAM_*_CREDENTIALS"]

Only the sections you change need to appear; everything else comes from defaults. The full reference, including MCP servers, custom providers, and Copilot settings, is in docs/configuration.md.

Platform support

Release builds are configured with GoReleaser for Linux, macOS, and Windows on AMD64 and ARM64. See the CI workflow for current build and test status.

Project layout

cmd/gocode/        CLI entry point, flags, subcommands
internal/agent/    agent loop, session memory, slash commands
internal/config/   platform directories, TOML parsing
internal/provider/ provider registry (Ollama, OpenAI-compatible, Anthropic)
internal/tools/    tool registry, shell execution, patch engine, approval gates
internal/session/  SQLite session persistence
internal/mcp/      MCP stdio client
internal/ignore/   .gocodeignore / .gitignore matching
internal/tui/      Bubble Tea interface

A deeper walkthrough is in docs/architecture.md.

FAQ

Can I use GoCode without a cloud provider?
Yes. Configure Ollama or a llama.cpp server and select it with --provider. See Local models.

Is it free?
GoCode is MIT-licensed and free. Cloud providers bill you under their own terms; local models have no API cost.

How do I add tools?
Through MCP: gocode mcp add <name> <command> [args...]. See MCP servers.

Where are my sessions?
See Sessions. Use gocode --new or /new to start fresh.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for the code of conduct and pull request process. Release history is in CHANGES.md.

go build ./...
go vet ./...
go test ./...

License

MIT. See LICENSE.