MCP server for code, docs, git, and memory

In the session (not your shell), run in order:

/plugin marketplace add Goldziher/basemind
/plugin install basemind@basemind

Restart, then run /bm-statusline once to turn on the live statusline (a one-time step — see Statusline). Turn on auto-update for the basemind marketplace (Claude Code's plugin manager): the plugin then tracks each new release automatically, and the launcher resolves the latest published release, so you always get the current index format and tool set and startup stays reliable even during a release. Prefer to control timing? Update the marketplace regularly by hand instead.

codex plugin marketplace add Goldziher/basemind
codex plugin add basemind@basemind

In the app: open the Plugins sidebar and add basemind. The CLI and IDE share one config file. The plugin starts the latest published GitHub release from the project workspace; it never runs from the installed plugin cache or races a shared npx install.

In Agent chat: /add-plugin basemind (once listed), or go to Dashboard → Settings → Plugins → Team Marketplaces → Import from Repo and point it at https://github.com/Goldziher/basemind.

gemini extensions install https://github.com/Goldziher/basemind

Update later with gemini extensions update basemind.

droid plugin marketplace add https://github.com/Goldziher/basemind
droid plugin install basemind@basemind

copilot plugin marketplace add Goldziher/basemind
copilot plugin install basemind@basemind

Add to opencode.json (project) or ~/.config/opencode/opencode.json (global):

{ "plugin": ["basemind-opencode@latest"] }

/plugins install https://github.com/Goldziher/basemind

Kimi doesn't support the comms auto-notifications, but the chat tools still work.

Hermes exposes MCP servers through config, so basemind's tools are wired there. Two steps — the binary + MCP wiring gives you the tools; a small standalone plugin package adds the helper skills, slash commands, and comms notifications.

First install the program (Homebrew / npm / cargo / release — not pip), then add the server to ~/.hermes/config.yaml (this is what gives you the nine domain tools):

mcp_servers:
  basemind:
    command: basemind
    args: [serve]

For the helper skills, slash commands, and agent-comms notifications, install the standalone plugin into the same Python environment Hermes runs in, then enable it (general plugins are opt-in):

pip install basemind-hermes-plugin
hermes plugins enable basemind

The plugin is pure-Python and ships no binary — it shells out to the basemind you installed above. Comms auto-notifications are best-effort; the chat tools work regardless.

Antigravity uses a shared MCP config — install the program, then add the generic MCP block. If you already use the Gemini extension, agy plugin import gemini brings it across.

pi: pi install git:github.com/Goldziher/basemind. pi has no MCP support, so basemind runs through its CLI here.

• Claude Code — claude mcp add basemind -- basemind serve (add --scope user for all projects; the -- is required). Or commit a .mcp.json at the repo root with the block above.
• Cursor — put the block above in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).
• Windsurf — ~/.codeium/windsurf/mcp_config.json (or Cascade → MCP servers → manage), then Refresh.
• Codex — codex mcp add basemind -- basemind serve, shared by the CLI and IDE.
• Gemini CLI — gemini mcp add basemind basemind serve, or the block above in ~/.gemini/settings.json.
• GitHub Copilot CLI — /mcp add in-session, or ~/.copilot/mcp-config.json with "type": "local" and "tools": ["*"].
• Factory Droid — droid mcp add basemind "basemind serve", or ~/.factory/mcp.json.
• Cline — MCP Servers icon → Configure → add the block above.
• Continue — .continue/mcpServers/basemind.yaml with command: basemind, args: [serve].
• OpenCode (without the plugin) — opencode.json under key mcp, with command as an array ["basemind", "serve"].
• Hermes — mcp_servers.basemind in ~/.hermes/config.yaml (YAML: command: basemind, args: [serve]). For helper skills + comms notifications, pip install basemind-hermes-plugin (a standalone pure-Python plugin, no binary), then hermes plugins enable basemind — see the Hermes plugin section above.
• Any other tool — point it at the command basemind with the argument serve.

Run /bm-statusline once. This is a one-time step because Claude Code doesn't let plugins set the main statusline themselves — so basemind asks the assistant to make the one-line settings change on your behalf, and it sticks from then on.

It shows two lines:

Opus · basemind · ⎇ main · 12% ctx
◆ basemind  ●  1,247 files · 23m ago  │  312 calls · 180 srch · 44 git · 12 docs  │  1.4M saved  │  ✉ 3 @reviewer

The dot is green when basemind is live and fresh, amber when idle, red when stale. The middle shows activity by type, then tokens saved, then unread messages. Adjust with BASEMIND_STATUSLINE=full|compact|minimal, or hide the top line with BASEMIND_STATUSLINE_CONTEXT=0.

basemind scan reads your project once, in parallel. It maps your code with [tree-sitter] (across [300+ languages][tslp]) and pulls text out of your documents with [xberg], then saves the result to a global cache under the XDG data directory, keyed by workspace — nothing is written into your repo. After that, basemind serve keeps the map in memory and answers questions instantly — no re-reading the project for each one. When files change, it updates only what changed. A single background daemon on the machine is the sole writer to that cache, so multiple serve sessions on the same repo (or on different worktrees of it) all read and write concurrently instead of one falling back read-only. See Global cache & the daemon below.

Navigation is scope- and import-aware for JavaScript/TypeScript, Python, and Java: basemind resolves each use to the definition it actually binds to, so a shadowed local isn't confused with an import and code mode definition lands on the right target (including across files for imports). Every other language still gets fast tree-sitter scope binding. Precise Python/Java resolution runs GitHub stack-graphs-style .tsg name-binding rules via an in-tree engine (crates/), with no per-language LSP server.

Resolution refines, but never shrinks, a result set. code mode callers reports every call site whose callee matches the name — the same sound floor mode references uses — and marks each hit resolved when resolution proved it binds to that definition (resolved_total counts them). It deliberately does not return only the resolved subset: resolution cannot see through a module-object import (from pkg import mod then mod.f()) or an unresolvable path alias, so filtering to it would drop real callers and report the remainder as complete. Filter on resolved when you want precision; trust total when you need completeness.

Markdown and Obsidian vaults are first-class: headings become navigable symbols (so code modes outline and symbols work over a notes vault); [[wikilinks]], ![[embeds]], and standard [text](Note.md) links all become references — so mode references on "Note" returns that note's backlinks regardless of link style; and #tags (inline or in YAML frontmatter) become references too, so mode references on "#project" lists every note carrying that tag.

flowchart LR
  A(["Coding agent"])
  R["Your project<br/>code · documents · git"]
  S["basemind scan<br/>map code & read documents"]
  D[("Global cache<br/>per-OS data dir")]
  V["basemind serve<br/>answers questions"]
  R --> S --> D --> V
  A <-->|asks questions| V
  classDef accent fill:#2563eb,stroke:#1e40af,color:#fff
  class S,V accent

Search and memory are powered by a vector store ([LanceDB]).

basemind serve answers the MCP handshake immediately and warms the code map into memory in the background, so a client never blocks waiting for a large repo to load. The status tool reports warming (still loading) and, once done, warm_ms; a first-time index build similarly reports indexing / index_build_ms.

While the server isn't fully ready, status and every code-map read tool may carry a notice object — { state, message, retry } — instead of (or alongside) their normal result:

Treat an empty or partial result carrying a notice as "retry shortly," not "no matches" — poll status (or just retry the call) until the notice clears.

Index state lives under a single global cache — ~/.local/share/basemind/ on Linux, ~/Library/Application Support/basemind/ on macOS (override with BASEMIND_DATA_HOME) — keyed by workspace, never inside your repo. The content-addressed blob store is machine-wide too: identical file content scanned from different repos or worktrees is extracted and stored once.

A workspace root must be a project: a git repository, or a directory containing basemind.toml. Anything else is refused, because basemind opens a root read-write and indexes every file beneath it — so an accidentally inherited root (/, your home directory, or wherever an MCP host happened to start) would become a whole-filesystem scan. Run basemind init to mark a directory you do want indexed, or set BASEMIND_ALLOW_ANY_ROOT=1 to skip the check. A filesystem or volume root is refused unconditionally and cannot be overridden.

A single background daemon per machine is the sole writer to that cache. basemind serve opens its store read-only and forwards writes (scan / rescan) to the daemon over a local socket, so N serve sessions on the same repo — or on different worktrees of it — all read and write concurrently instead of a second session silently falling back to a stale, read-only view. The daemon also keeps a cheap, always-on registry of repos, worktrees, and branches (workspaces / worktrees / branches), and worktree_claim / worktree_release give agent sessions an advisory way to avoid colliding on the same worktree.

basemind statusline queries the daemon for the workspaces currently active and prints a compact line for your shell prompt; it prints nothing when no daemon is running.

The daemon is started on demand, detached with setsid(2). That changes the session and the process group but not the cgroup, so on Linux an auto-spawned daemon lives in the cgroup of whatever shell or editor happened to start it — outside any MemoryMax you configured for basemind. No code in basemind can change th