GopherMind

          __                          __
        _/  \________________________/  \_
       /                                   \
      |    .------.            .------.     |
      |   /   __   \          /   __   \    |
      |  |  /(o )\  |________|  /( o)\  |    |
      |  |  \ '' /  |  .--.  |  \ '' /  |    |
      |   \  '--'  / (    )  \  '--'  /     |
      |    '------'   \ __ /   '------'     |
      |             .---. .---.             |
      |             |   | |   |             |
      |             |   | |   |             |
      |             '---' '---'             |
       \                                   /
        \._                             _./
         \ '""--..____________..--"'   /
          '-.._____________________..-'

              G O P H E R M I N D

A tiny, hackable AI coding agent for your terminal — pointed at your LLM.

---

GopherMind is a single Go binary that turns any OpenAI-compatible model into an agentic coding assistant that reads, searches, edits, and runs commands in your repository — all from a clean terminal UI. It's built to run against a model you control (local llama.cpp, Ollama, LM Studio, vLLM, or a hosted endpoint), with safety built in at every layer.

No cloud lock-in. No 200-file framework. Just a small, readable codebase you can actually understand and extend in an afternoon.

Running elsewhere, and skills

• Running sessions on another machine - point the desktop app at a gophermind serve on a server, with approvals that name the machine.
• Skills - capability packs, and why fetched ones are off until you enable them.

Why GopherMind?

• 🧠 Bring your own model. Anything that speaks the OpenAI /v1 API — your local GPU, a private endpoint over VPN, or OpenAI itself. Models are auto-discovered; switch backends with named provider profiles.
• 🔒 Safe by default. Every file path is contained to your repo (symlink-aware), shell commands run through a deny-list, and mutating actions hit an approval gate unless you opt into auto mode.
• ⚡ Fast, focused loop. Read / search / edit / shell tools drive a compact agent loop with streaming output, a live token + cost meter, retries with backoff, and an optional response cache.
• 🖥️ A terminal UI that's actually pleasant. Built on Charm — scrollback, syntax-aware rendering, inline approvals, and a gopher that greets you with a fortune.
• 🪶 Small and hackable. Pure Go, no CGO. Adding a new tool is still one struct and one function — the codebase stays readable even as it grows.
• 🧰 Batteries included (opt-in). A local semantic index & RAG, a read-only SQL/Parquet/CSV data toolkit, multi-agent strategies (--debate, --samples, --reflexion), an MCP server so any MCP client can drive it, a plugin SDK + WASM sandbox, and observability (Prometheus /metrics, tracing, cost dashboard). Every integration is inert until you configure it.

Install

brew install jbrahy/tap/gophermind     # macOS (signed + notarized, no Gatekeeper warnings)
npm install -g gophermind              # macOS / Linux / Windows, x64 / arm64

The Homebrew build is a signed + notarized universal macOS binary; the npm package downloads the prebuilt binary for your platform. Linux users can also grab a .deb/.rpm/.apk (or a .tar.gz) straight from the latest release; Windows users a .zip. Every release ships an SBOM and checksums.txt.

Or build from source (Go 1.25+):

git clone https://github.com/jbrahy/gophermind.com
cd gophermind.com
make build      # -> ./gophermind

Run it for free

gophermind vendors a registry of free LLM API providers, so you can try it with no signup and no key at all:

gophermind --profile free-ovhcloud ask "hello"

That runs against OVHcloud AI Endpoints, served anonymously (2 requests/minute per IP) — no config file, no environment variable, nothing to sign up for. free-kilocode is the other no-key profile. gophermind free list shows every provider gophermind knows about, no-key ones first; gophermind free show <profile> prints a provider's models, rate limits, and free-tier terms; gophermind free usage shows a lifetime odometer of the free tokens and requests you've used.

A provider whose endpoint can't be known statically (for example Cloudflare Workers AI, which embeds your account ID) needs a hand-supplied /v1 base URL. Point gophermind at it with GOPHERMIND_BASE_URL, and if that URL already ends in a version segment like /v1, set GOPHERMIND_CHAT_PATH and GOPHERMIND_MODELS_PATH to /chat/completions and /models so the client doesn't double the segment into /v1/v1/chat/completions.

See docs/free-providers.md for the full table.

Quickstart

gophermind            # first run walks you through a setup wizard, then chats

The wizard asks for your endpoint, an optional API key, a model (picked from a live list), your approval mode, and a max-iteration budget — then saves it so later launches go straight to the prompt. Re-run it anytime with gophermind config.

One-shot, non-interactive use:

gophermind run "add a --json flag to the export command and a test for it"
gophermind ask "how does the retry backoff work?"   # read-only, never edits

TUI Features

Predictive Text & Autocomplete

As you type in the interactive TUI input box, suggestions appear in two forms:

• Inline ghost text — a single obvious continuation appears as faded text at the cursor: accept it with Tab or → (right arrow when the cursor is at the end of the line). Sources include history recall (prompts you've submitted before) and a Markov next-word predictor trained on your history.
• Popup menu — when there are multiple candidates, a popup menu appears above the input: navigate with ↑ and ↓, accept with Tab (or Enter when the menu is open), dismiss with Esc. Sources include slash-command completion (when the line starts with /) and file/path completion for path-shaped tokens.

The suggestion engine is built on bubblecomplete, a reusable library carried in this repo at bubblecomplete/ and wired in through a replace directive in go.mod.

Prompt History

Submitted prompts are saved to ~/.gophermind/history for recall and training (honors GOPHERMIND_CONFIG_DIR; falls back to .gophermind/history if the home directory is unavailable).

Privacy note: Prompts are stored in plain text (one JSON-encoded string per line, JSONL format). Disable history persistence with GOPHERMIND_HISTORY=off. The history is capped at the most recent 500 entries; oldest entries are dropped first.

Multi-line Input

The input box grows from 1 up to 4 rows, then scrolls. Enter submits; Shift+Enter inserts a literal newline. If your terminal does not distinguish Shift+Enter from plain Enter, use Ctrl+J instead.

Alt+Enter is not bound by default. It arrives as ESC+CR, which is byte-identical to what some keyboard remaps and terminal key mappings emit for ordinary keys — so binding it caused stray newlines when an unrelated key was pressed. Set GOPHERMIND_ALT_ENTER_NEWLINE=1 to restore it.

/goal — Session Steering Goal

Use /goal <text> to set a persistent goal that is injected into every subsequent turn, steering the agent's behavior without modifying the prompt each time. Bare /goal displays the current goal; /goal clear removes it. The goal is session-scoped and works with any backend.

Text Selection

The TUI no longer captures the mouse, so you can select and copy text using your terminal's native selection (click-drag). Keyboard navigation of the transcript is unchanged: PgUp and PgDn scroll the message history.

How it works

you ──▶ TUI ──▶ agent loop ──▶ OpenAI-compatible model
                    │  ▲
                    ▼  │ tool calls / results
             tools (read · search · edit · write · shell)
                    │
             safety: path containment · shell deny-list · approval gate

The model requests tools by name; the harness runs them against your repo (inside the sandbox), feeds the results back, and repeats until it produces an answer or hits the iteration budget. That's the whole idea — see gophermind-lib/agent and gophermind-lib/tools.

Plan and build from a brief

gophermind brief plan <brief.md> plans a brief into a tree of nodes under .gophermind/<run-id>/ in your repo, gophermind brief run <run-id> builds it, and /project <brief> in the TUI (or gophermind project <brief>) does both in one run. Everything a run does is a browsable file in that folder: the nodes, their runtime state, the event log, the call log, the saved attempts and the report. With executor.workers above 1 (or gophermind brief run --workers n) independent leaves build in parallel in private copies of the repo, and a leaf that has used its whole model ladder is rewritten by the planner's revise stage instead of failing the run. gophermind serve and the desktop app show a run live (GET /pipeline; the wire format is docs/pipeline-contract.md, and the server and the app must be released together). See docs/build/README.md.

gophermind phase and /phase were removed in 0.10.0. PhaseFlow's roadmap workflow has no replacement; .planning/ folders are not read.

Configuration

Everything is optional and layered: flags > real env > ./.env > ~/.gophermind/config.json > defaults. Copy .env.example to .env for a fully documented list, or just run the wizard. Highlights:

Setting	What it does
GOPHERMIND_BASE_URL	Your OpenAI-compatible endpoint (required)
GOPHERMIND_MODEL	Model name (empty = auto-discover)
GOPHERMIND_APPROVAL	ask (default) or auto
GOPHERMIND_PROFILE	Named backend: local-llama, openai, …
GOPHERMIND_ATTENTION_FLASHES	Screen flashes when the TUI needs you (default 4; 0 off)
GOPHERMIND_CHAT_PATH	Path appended to GOPHERMIND_BASE_URL for chat completions (default /v1/chat/completions)
GOPHERMIND_MODELS_PATH	Path appended to GOPHERMIND_BASE_URL for model listing (default /v1/models)
GOPHERMIND_SESSION_HEADER	Request header that carries one random id per run, so a server with per-session KV state (for example ExecuTorch X-ExecuTorch-Session-ID) reuses the cached prompt prefix (default off)
GOPHERMIND_SESSION_CLOSE	Delete the server-side session when gophermind exits (default off; the session id is stable per directory, so keeping it lets the next run reuse the cache)

The global config file

gophermind config (and /config in the TUI) writes ~/.gophermind/config.json, which is also the directory holding sessions, prompt history, and device tokens. It is a flat JSON object meant to be edited by hand — a lowercase key is the GOPHERMIND_ variable without its prefix, and an ALL-CAPS key is used verbatim:

{
  "base_url": "http://192.168.5.2:8080/v1",
  "model": "qwen2.5-coder-32b",
  "approval": "auto",
  "max_iter": 25,
  "attention_flashes": 4,
  "fallback_models": ["qwen2.5-coder-14b"],
  "GITHUB_TOKEN": "…"
}

Real environment variables always win over the file, and saving merges rather than rewrites, so hand-added keys survive re-running the wizard. Set GOPHERMIND_CONFIG_DIR to put the directory somewhere else. Upgrading from a release that used <os user config dir>/gophermind/.env migrates automatically on first run — the .env becomes config.json and the sibling state files move with it.

Secure options for internal endpoints (mTLS, custom CA), a response cache, sampling controls, and JSONL transcript export are all supported — see .env.example.

Beyond chat/run/ask, the CLI exposes subcommands for sessions, prompts, plugins, config bundles, the MCP server, benchmarks, diagnostics, and more — run gophermind --help for the full list.

Connecting to MCP servers

GopherMind both serves MCP (gophermind mcp) and consumes it. Third-party MCP servers are declared in an mcpServers block in ~/.gophermind/config.json, and their tools join the registry alongside the builtins:

{
  "mcpServers": {
    "pelagosnow": {
      "transport": "http",
      "url": "https://mcp.pelagosnow.com/mcp",
      "headers": { "Authorization": "Bearer ${PELAGOSNOW_TOKEN}" }
    },
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/code"],
      "env": { "LOG_LEVEL": "warn" },
      "disabled": false
    }
  }
}

Project-scoped servers go in .gophermind/<name>.mcp.json — one server per file, the same fields, and an entry there overrides a global one of the same name. This is the form to commit alongside a repo:

{
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
}

A few things worth knowing:

• Tools are namespaced server__tool, so a remote server can never shadow a builtin. The filesystem server above contributes filesystem__read_file.
• Every string supports ${VAR}, expanded from the environment. An unset variable is a startup error rather than a blank value, so tokens stay out of the file and a missing one is reported where it happens. This keeps .gophermind/*.mcp.json safe to commit.
• MCP tools always require approval. They come from servers you do not control, so they fail closed. Relax individual ones in .gophermind/policy: "gated_tools": {"pelagosnow__search": "always"}.
• A server that is down is a warning, not a failure — the session starts without it. A malformed config is fatal, so typos surface immediately.

Shell completion

gophermind autocomplete detects your shell from $SHELL and prints a completion script (pass bash, zsh, or fish to override). Rather than appending it to your rc file — which duplicates the block every time you re-run it — write it to its own file and source that, so regenerating after an upgrade is a single command and your rc file gains exactly one line:

mkdir -p ~/.gophermind
gophermind autocomplete > ~/.gophermind/completion.sh
echo 'source ~/.gophermind/completion.sh' >> ~/.zshrc   # or ~/.bashrc

Appending straight to an rc file works too — the zsh script guards its compdef call so it is safe to source before compinit has run.

Remote control from iOS / mobile

gophermind serve also exposes a session-based, multi-turn HTTP+SSE surface so a phone can drive an agent running on your machine: create a session, stream a turn's tokens/tool calls/usage live, and — with GOPHERMIND_SERVE_APPROVAL=remote — approve or deny gated tool calls on-phone (optionally with a push notification via APNs) instead of at the machine's terminal.

See docs/mobile-serve.md for the full protocol reference (run instructions, env vars, connectivity options, and the typed SSE event schema). The native iOS app that implements this contract will live in ios/ (built next).

Contributing

We'd love your help. GopherMind ships with a large idea backlog across four batches (todo.md → todo-4.md) — the batch-4 set landed in 0.2.0 (MCP server, embeddings, WASM sandbox, packaging, and more), so the remaining tail is a good source of scoped work. Good first areas: adding a tool, improving search, a scoop-bucket/winget publish path, or wiring up an idea from the backlog.

Start with CONTRIBUTING.md. The codebase is test-driven and small enough to hold in your head.

License & credits

GopherMind is MIT licensed. The startup fortunes come from Brian M. Clapper's fortune database under CC BY 4.0 — see CREDITS.md.