Basemind

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

[](https://crates.io/crates/basemind) [](https://www.npmjs.com/package/basemind) [](https://pypi.org/project/basemind/) [](https://github.com/Goldziher/basemind/actions/workflows/ci.yaml) [](LICENSE)

[Install](#installation) · [Features](#what-you-get) · [How it works](#how-it-works) · [Performance](#performance) · [CLI](#cli-reference)

---

An agent reasoning from structure — outline + find_references in a live session, statusline tracking tokens saved.

More demos ↓

---

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.

| Capability | What it does | Key tools | |---|---|---| | Code intelligence | Find where things are defined, what calls what, who implements what, and how calls chain — across [300+ languages](#how-it-works). | outline · search_symbols · find_references · find_callers · call_graph · find_implementations · workspace_grep | | Git intelligence | Ask what changed recently, who last touched a function, where the churn is, and how a file's structure differs across commits. | blame_symbol · symbol_history · recent_changes · hot_files · diff_outline · commits_touching | | Document search | Search PDFs, Office files, HTML, email, and images by meaning — with built-in text extraction and OCR, no extra setup. | search_documents | | Shared memory | A per-repo memory agents can write to and search; clones of the same repo share it, unrelated repos stay separate. | memory_put · memory_search · memory_audit | | Suggestions | Spots files that change together and suggests notes worth saving — you approve before anything is kept. | proposals_mine · proposal_accept | | Web crawl | Fetch a page or follow links from a starting URL; results join the document search above. | web_scrape · web_crawl · web_map | | Agent comms | A shared chat for agents on the same repo: per-repo rooms they auto-join, direct messages, and a recency-filtered inbox. One orchestrator can drive many named subagents (as_agent). | room_post · dm_send · inbox_read · agent_list | | Agent shells | Let agents open, type into, and watch terminal sessions in the background. | shell_spawn · shell_send · shell_capture · shell_list | | Token saving | Hand an agent a file's outline instead of its full text, then pull back only the one function it needs. | compress · expand | | Admin | Refresh the index, see what's been queried, and check or clean up the on-disk cache. | rescan · telemetry_summary · cache_stats |

---

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](#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.

Claude Code

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](#install-the-program)).

Codex

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.

Cursor

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 CLI

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

Update later with gemini extensions update basemind.

Factory Droid

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

GitHub Copilot CLI

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

OpenCode

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

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

Kimi Code

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

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

Antigravity & pi

Antigravity uses a shared MCP config — [install the program](#install-the-program), then add the [generic MCP block](#2-as-an-mcp-server). 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](#3-as-a-cli) here.

2. As an MCP server

If your tool speaks MCP but you're not using the plugin, [install the program](#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.

Per-tool specifics (Claude Code · Cursor · Windsurf · Codex · Gemini · Copilot · Droid · Cline · Continue · OpenCode)

• 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](#install-the-program), 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](#cli-reference).

Install the program

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

| Channel | Command | Includes | |---|---|---| | Homebrew | brew install Goldziher/tap/basemind | everything | | npm | npm install -g basemind | everything | | pip | pip install basemind | everything | | cargo | cargo install basemind --locked | code + git only | | cargo (full) | cargo install basemind --features full --locked | everything | | GitHub releases | Download a binary | everything |

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.

Statusline (Claude Code)

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

The same engine from the CLI — scan, then symbol / reference / call-graph / blame queries.

Searching documents by meaning, not keywords, across 90+ formats.

Multi-agent code-review panel: named reviewers coordinate in a repo-scoped comms room (post, direct-message, synthesize) — entirely over basemind comms.

---

How it works

From one scan to instant answers

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 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 projectcode · documents · git"]
  S["basemind scanmap code & read documents"]
  D[(".basemind/local index")]
  V["basemind serveanswers 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]).

How agents coordinate

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 AClaude Code · repo X"]
  B["Agent BCursor · repo Y"]
  BR["Shared comms servicerooms · inboxes"]
  A |post · read| BR
  B |post · read| BR
  classDef accent fill:#2563eb,stroke:#1e40af,color:#fff
  class BR accent

Agent shells

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

Good habits the plugin sets up for you

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.

Compression that understands code

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

Scan speed

Measured on an Apple M4 (10 cores — 4 performance + 6 efficiency, 16 GB, macOS 26) with the hardening harness (scripts/harden.sh), which clones each upstream repo fresh and scans its code map. Warm, steady-state numbers; the first scan of a cold project is slower.

| Project | Files | Languages | Scan time | |---|---|---|---| | gin | 130 | Go | 0.1 s | | requests | 128 | Python | 0.1 s | | ripgrep | 221 | Rust | 0.6 s | | tokio | 861 | Rust | 0.4 s | | react | 7 242 | TS / JSX | 2.0 s | | django | 7 065 | Python | 2.4 s | | TypeScript compiler | 81 324 | TS / JS / JSON | 18 s |

The TypeScript compiler is the worst case — 81k files in about 18 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.

Git history queries

basemind precomputes a per-repo git-history index (path → commit posting lists, stored newest-first) so the history tools — commits_touching, recent_changes, hot_files, find_commits_by_path, and symbol_history's commit walk — are posting-list lookups. Warm in-process query latency on the same M4:

| Repo | Commits | commits_touching | recent_changes | index build | index size | |---|---|---|---|---|---| | django | 2 000 | 39 µs | 15 µs | 0.5 s | 1.7 MB (6 % of .git) | | tokio | 3 984 | 37 µs | 13 µs | 0.9 s | 2.1 MB (12 %) | | requests | 6 480 | 38 µs | 15 µs | 1.0 s | 1.9 MB (14 %) | | TypeScript | 2 000 | 37 µs | 13 µs | 3.2 s | 30 MB (12 %) |

History queries answer in tens of microseconds, flat across history depth, because the newest-first posting lists decode only the commits a query returns. The index builds in well under a second to a few seconds and costs 6–22 % of .git on disk.

It is a pure accelerator: the tools use it only when it is fresh (last_indexed_head == HEAD) and otherwise walk history directly, so it can never serve stale results — and it rebuilds automatically when history is rewritten (filter-repo / rebase / force-push). Reproduce with cargo bench --bench git_history or the git-ops block in scripts/harden.sh.

---

Configuration

Config file & overrides

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 = tru

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Goldziher](https://github.com/Goldziher)
- **Source:** [Goldziher/basemind](https://github.com/Goldziher/basemind)
- **License:** MIT
- **Homepage:** https://docs.rs/basemind

Install and usage instructions live in the source repository linked above.