basemind 0.10.0

The context and communication layer for coding agents.

basemind turns any repo into an always-current map of its code, documents, history, and memory — so agents answer from structure and search instead of burning their context window on grep and file reads — and gives a team of agents a shared channel to coordinate while they work. One server does both.

Code map across 300+ languages · documents in 90+ formats · semantic + full-text search · git history & blame · shared memory · web crawl · agent-to-agent comms

Install · Features · How it works · Performance · CLI

What you get

basemind answers with file paths, line numbers, and signatures — not whole files — so a question about your code costs a small fraction of the tokens it takes to read the source.

Installation

Three ways to run basemind, easiest first. All three share the same local index and are safe to run side by side.

The plugin downloads the basemind program for you on first use. The MCP-server and CLI paths need it installed yourself — see Install the program.

1. As a plugin (recommended)

The plugin sets up everything for you — the server, the helper skills, the agent-comms features, and the slash commands. Pick your coding tool.

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).

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.

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.

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.

2. As an MCP server

If your tool speaks MCP but you're not using the plugin, install the program, then register it:

{
  "mcpServers": {
    "basemind": { "command": "basemind", "args": ["serve"] }
  }
}

Each tool says whether it only reads or can change things, so your client can auto-approve the safe ones and ask before the rest. If basemind isn't found, use the full path from which basemind.

• 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"].
• Any other tool — point it at the command basemind with the argument serve.

3. As a CLI

The standalone program, for scripts, headless runs, and CI. Install it, then:

basemind scan                          # index the project once
basemind query symbol "parseQuery"     # find a symbol by name
basemind query references "processFile" # find everywhere it's called
basemind git blame-file src/main.rs    # who last changed each line
basemind watch                         # keep the index fresh as files change

Full command list in the CLI reference.

Install the program

The MCP and CLI paths need basemind available on your system. (The plugin does this for you.)

The Homebrew / npm / pip / GitHub downloads include the full feature set — documents, OCR, search, web crawl, shared memory, agent comms, and agent shells — so the first run downloads the models it needs. The plain cargo install builds the code-map and git tools only.

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.

Demos

How it works

basemind scan reads your project once, in parallel. It maps your code with tree-sitter (across 300+ languages) and pulls text out of your documents with kreuzberg, then saves the result to a local cache in .basemind/. 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.

flowchart LR
  A(["Coding agent"])
  R["Your project<br/>code · documents · git"]
  S["basemind scan<br/>map code & read documents"]
  D[(".basemind/<br/>local index")]
  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).

A single shared service in the background lets agents talk to each other — even across different tools and different repos on the same machine. Agents join rooms automatically based on what they're working on, and each has a personal inbox. Messages come in two parts: a short headline (subject and sender) that's cheap to skim, and the full body, fetched only when an agent wants to read it. An agent never sees its own posts in its inbox.

The plugin makes sure agents notice messages without being asked — through the built-in instructions, a notice at session start and each turn, and a quiet background check every few seconds.

flowchart LR
  A["Agent A<br/>Claude Code · repo X"]
  B["Agent B<br/>Cursor · repo Y"]
  BR["Shared comms service<br/>rooms · inboxes"]
  A <-->|post · read| BR
  B <-->|post · read| BR
  classDef accent fill:#2563eb,stroke:#1e40af,color:#fff
  class BR accent

Included in every prebuilt download (and in cargo install --features shells / full): agents can open terminal sessions in the background, type into them, and read what's on screen — no extra tools to install. Sessions can be fully headless, or opened in a real terminal tab or window so you can watch along. A spawned session and the agent that started it can message each other over comms.

Token saving

The plugin nudges agents toward the cheap path by default:

• Get a file's outline before opening it — then read only the part you need.
• Search for a definition instead of grepping for it.
• Look up who calls a function instead of grepping for call sites.
• Refresh the index after edits instead of restarting the server.
• Don't re-read a file basemind already mapped.

Optional guardrails enforce this at the moment a tool is used:

• Guard — gently redirects grep-style searches to the matching basemind tool. On by default; set BASEMIND_GUARD=off to disable, or redirect to block instead of nudge.
• Output compressor — BASEMIND_COMPRESS_OUTPUT=1 shrinks long command output. It never touches anything that looks like a credential and leaves output alone if it can't help.
• Re-read shortcut — BASEMIND_DELTA_READS=1 shows just what changed when an agent re-reads a file it already read this session.

basemind shrinks code by keeping the shape and dropping the bodies — function signatures and imports stay, the implementations go — because a signature is useless without its shape. For prose it does a light cleanup (extra whitespace, filler, repeated paragraphs). It reports honest before/after token counts, and the code version is exact — nothing is lost, just set aside. expand brings any one function's full body back when an agent actually needs it: compress to an outline, expand only what you need.

Performance

Measured on Apple Silicon with the full feature set. The first scan of a cold project is slower; these are warm, steady-state numbers.

The TypeScript compiler is the worst case — 81k files in about 22 seconds. Re-scans only look at what changed, so keeping a project up to date is far faster than the first scan.

Once running, most code questions answer in under a millisecond, symbol and call-graph searches in a few milliseconds, and document search in around 200 ms — because the map is held in memory rather than read from disk each time.

Configuration

A minimal config — the full schema is at schema/basemind-config-v1.schema.json:

# .basemind/basemind.toml
file_watch_glob = "**/*.{rs,ts,tsx,py,go}"
eager_l2 = true

[documents]
enabled = true

Any tool call can override these settings for that one request, and settings map to environment variables in the obvious way: --llm-api-key becomes BASEMIND_LLM_API_KEY.

CLI reference

CLI commands mirror the MCP tools. Add --json for machine-readable output.

Query (basemind query)

Git (basemind git)

Memory (basemind memory)

Suggestions (basemind governance)

Cache (basemind cache)

Web (basemind web)

Comms (basemind comms)

Other commands (scan, serve, watch, …)

License

MIT — see LICENSE.