GoCode

README

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 connect seamlessly to leading cloud AI models from Google Gemini, Anthropic Claude, OpenAI, Groq, OpenRouter, Qwen, Kimi, 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
• 9 Multi-Provider Gateways — Ollama, OpenAI, Gemini, Claude, Groq, OpenRouter, Qwen, Kimi, OmniRoute
• Human-in-the-Loop Approval Gate — Explicit confirmation before executing commands or modifying files
• On-the-Fly Switching — Switch providers or models dynamically with /provider and /model commands

v0.3.0 Additions

• Interruptible Generation — Cancel turns in progress with Ctrl+C or Esc without terminating the session
• Safer Key Handling — Esc clears textarea when idle; double Ctrl+C cleanly exits; /exit and /quit aliases
• Model Validation — /model <name> validates model availability against the active provider before switching
• Command Guardrails — Unrecognized slash commands provide helpful /help suggestions instead of querying the model
• Smart Viewport Scrolling — Avoids auto-scroll jumping when reading previous conversation history during streaming

v0.2.0 Additions

• SQLite Session Persistence — Automatically saves and resumes sessions across terminal restarts
• Model Context Protocol (MCP) — Extend with any MCP server (stdio transport) via gocode mcp add
• Project Context (AGENTS.md) — Auto-loads project-specific instructions from CWD hierarchy
• Global Context (CONTEXT.md) — User-wide conventions from ~/.config/gocode/CONTEXT.md
• .gocodeignore Filtering — Protect sensitive files with gitignore-style patterns
• Granular Tool Permissions — Configure auto_approve and deny lists in config.toml
• Interactive Model Picker — Fuzzy-search models with Ctrl+L in TUI mode
• Git Attribution — Auto-format commit trailers (Assisted-by: GoCode:<model>)
• Structured Logging — gocode logs --tail N --follow for debugging
• Diagnostics — gocode doctor to check provider health

---

Quick Start

Prerequisites

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

Installation

Option 1: Install via go install (Recommended)

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

Option 2: Build from Source

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

Option 3: 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 model
gocode --provider gemini --model gemini-2.5-flash

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

# Enable debug logging
gocode -v

---

Session Management

GoCode automatically persists all conversations to SQLite. Sessions are auto-resumed by default.

# 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.db (Linux/macOS) or %LOCALAPPDATA%\gocode\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.

---

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	Default Model	Base URL
Google Gemini	gemini	GEMINI_API_KEY	gemini-2.5-flash	https://generativelanguage.googleapis.com/v1beta/openai
Anthropic Claude	anthropic	ANTHROPIC_API_KEY	claude-sonnet-4-20250514	https://api.anthropic.com/v1
OpenAI	openai	OPENAI_API_KEY	gpt-4o	https://api.openai.com/v1
Groq	groq	GROQ_API_KEY	llama-3.3-70b-versatile	https://api.groq.com/openai/v1
OpenRouter	openrouter	OPENROUTER_API_KEY	anthropic/claude-sonnet-4.5	https://openrouter.ai/api/v1
Qwen (DashScope)	qwen	DASHSCOPE_API_KEY	qwen-max	https://dashscope.aliyuncs.com/compatible-mode/v1
Kimi (Moonshot)	kimi	MOONSHOT_API_KEY	moonshot-v1-8k	https://api.moonshot.cn/v1
OmniRoute Proxy	omniroute	OMNIROUTE_API_KEY	auto	http://localhost:20128/v1
Ollama (Local)	ollama	None	Auto-detected	http://localhost:11434

---

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
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-2.5-flash"

[provider.anthropic]
base_url = "https://api.anthropic.com/v1"
api_key_env = "ANTHROPIC_API_KEY"
default_model = "claude-sonnet-4-20250514"

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

[permissions]
auto_approve = ["file_read"]  # Tools that execute without confirmation
deny = []                      # Tools that are permanently blocked

[tools.shell]
timeout_seconds = 30  # Maximum seconds a shell command may run

[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	Automatic
file_write	Create new files or overwrite existing files	Requires Confirmation
file_patch	Perform target string replacements & targeted code edits	Requires Confirmation
shell_exec	Run terminal commands (builds, tests, git operations)	Requires Confirmation

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

---

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	9 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 running locally on your machine (http://localhost:11434). You can run open-weights models like codellama, llama3.3, deepseek-coder, or qwen2.5-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 9 major provider gateways: Google Gemini, Anthropic Claude, OpenAI, Groq, OpenRouter, Qwen (Aliyun DashScope), Kimi (Moonshot AI), local Ollama servers, and OmniRoute proxies.

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 • Powered by Go

Made with ❤️ by mevarx