Provides a comprehensive context and communication layer for coding agents using code mapping, document RAG, shared memory, and multi-agent coordination.
Also known as Goldziher/basemind, basemind-opencode
- Stars
- 120
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is basemind MCP?
basemind provides a comprehensive context and communication layer for coding agents using code mapping, document RAG, shared memory, and multi-agent coordination.
Summary generated from the project's README
About basemind MCP server
basemind serves as a specialized context and communication layer designed for coding agents. It transforms entire repositories into live maps containing code structure, documentation, and history. Instead of forcing agents to read entire files and consume large amounts of tokens, this server provides precise information like file outlines, symbol definitions, and reference locations. This approach allows agents to reason about code structure and meaning rather than relying on expensive grep operations.
Developers can integrate this server with various clients including Claude Code, Cursor, and Gemini CLI. It supports over 300 programming languages and 90 document formats, including PDFs and Office files. Beyond code intelligence, it offers a shared memory system for agents to coordinate and a communication layer for multi-agent teamwork. The system also includes git intelligence to track changes and a web crawl capability to ingest external documentation into the local index.
What you can do with it
- 1Reduce token consumptionAn agent can query a file's structure and signatures instead of reading the full source code.
- 2Analyze code architectureA developer can ask an agent to map out the dependencies and modules within a large repository.
- 3Coordinate multi-agent workflowsMultiple agents can use a shared channel to communicate and manage tasks together.
- 4Perform semantic documentation searchAn agent can search through various document formats like PDFs or HTML using semantic meaning.
Written from the project's README. Every use case is checked against a quote from it.
How to install basemind MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall basemind MCP in Claude Code
$ claude mcp add basemind -- npx -y basemind-opencodeInstall basemind MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"basemind": {
"command": "npx",
"args": [
"-y",
"basemind-opencode"
]
}
}
}Install basemind MCP in VS Code
.vscode/mcp.json
{
"servers": {
"basemind": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"basemind-opencode"
]
}
}
}Install basemind MCP in VS Code CLI
$ code --add-mcp '{"name":"basemind","type":"stdio","command":"npx","args":["-y","basemind-opencode"]}'Install basemind MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"basemind": {
"command": "npx",
"args": [
"-y",
"basemind-opencode"
]
}
}
}Install basemind MCP in Codex
$ codex mcp add basemind -- npx -y basemind-opencodeInstall basemind MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.basemind] command = "npx" args = ["-y", "basemind-opencode"]
Install basemind MCP in Gemini CLI
$ gemini mcp add -s user basemind npx -- -y basemind-opencodeInstall basemind MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"basemind": {
"command": "npx",
"args": [
"-y",
"basemind-opencode"
]
}
}
}Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubThe 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
Docs · 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.
| Capability | What it does | Key tools |
|---|---|---|
| Code intelligence | Read the code map instead of opening files: a file's structure (outline), find a definition by name (symbols), regex content search (grep), enumerate or fuzzy-find files (files · find, documents included), resolve a reference position to the definition it binds to (definition — scope- and import-aware, JS/TS via oxc, Python & Java via in-tree stack-graphs), every call site of a name (references, name-only) or of one specific definition (callers), implementors of a trait / interface / base class (implementations), the reverse import lookup (dependents), one symbol's raw body (expand), and search by meaning over indexed chunks (semantic → chunk, needs --features code-search). Layered over 300+ languages. |
code (outline · symbols · grep · files · find · definition · references · callers · implementations · dependents · expand · semantic · chunk) |
| Code graph | Walk the typed code-graph: who calls what and what a function reaches (calls), a symbol's n-hop blast radius (neighbors), the confidence-weighted shortest route between two symbols (path), a readable centrality-cut neighborhood (subgraph), the repo's de-facto modules (communities), and the whole-repo architecture ranked by PageRank + git churn with its dependency cycles (map). Render it as node-link JSON / DOT / Mermaid / GraphML / Cypher / offline interactive HTML / static SVG (export), show it to a human in their desktop viewer (display), or open the interactive UI at a live http://…/ui URL (open, which needs the daemon's opt-in HTTP front-end and otherwise falls back to a file:// export) — both take open: false to return the path or URL without launching anything. Every edge carries provenance + confidence; every result is deterministic and bounded. |
graph (calls · neighbors · path · subgraph · communities · map · export · display · open) |
| Git intelligence | Ask what changed recently, who last touched a function or a line, where the churn is, when a symbol's body actually changed, how a file's structure differs across commits, and full-text search commit authors + messages at full branch depth. | git (status · recent · touching · by_path · churn · diff · diff_outline · blame · blame_symbol · symbol_history · search · show) |
| Memory & documents | A per-repo memory agents write to and search by meaning — clones of the same repo share it, unrelated repos stay separate — plus semantic search over PDFs, Office files, HTML, email, and images (OCR included, no extra setup), and a review queue of notes mined from files that change together, which you approve before anything is kept. | memory (put · get · list · search · delete · audit · documents · mine · proposals · accept · reject) |
| Web crawl | Fetch a page or follow links from a starting URL; results join the document search above. | web (scrape · crawl · map) |
| Agent comms | Threads addressed by subject, path-glob, and members; scope discovery; inbox delivery; lifecycle status; and dry-run/apply retention cleanup. | agents (register · list · thread_start · thread_list · join · leave · members · add_member · remove_member · archive · post · history · message · inbox · ack · wait · cleanup · status) |
| Agent shells | Run headless terminal sessions in the background, capture recent retained output after commands exit, and explicitly stop sessions when their work is done. Visual terminal attachment is opt-in through [shells].visual. |
shell (spawn · send · capture · kill · list · broadcast) |
| Admin | Refresh the index after edits, check index health and repo identity, see what's been queried and how many tokens were saved, inspect or clean the on-disk cache, and shrink what an agent carries: a file's outline instead of its text, a diff instead of a re-read, a checkpoint instead of a transcript, plus a wasteful-tool-use report. | admin (status · repo · rescan · cache_stats · gc · cache_clear · telemetry · compress · delta · checkpoint · waste) |
| Machine registry | Machine-wide repo/worktree/branch coordination, backed by the daemon's always-on registry. Advisory claims let agent sessions avoid colliding on the same worktree. | workspace (workspaces · worktrees · branches · claim · release) |
Installation
Three ways to run basemind, easiest first. All three share the same local index and are safe to run side by side.
The MCP plugin downloads the basemind program for you on first use. Pi, the MCP-server, and CLI paths need it installed yourself — see Install the program.
1. As a plugin (recommended)
The curated plugin under plugin/ contains ten public skills and six commands for eleven runtime
profiles. See the plugin installation guide for local installation and release
prerequisites. The repository root also retains the existing OpenCode terminal adapter and Pi
extension; those integrations have separate package entry points.
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 matching published 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 generated plugin uses the matching published GitHub release, or a local BASEMIND_BIN override.
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.
git clone https://github.com/Goldziher/basemind
cd basemind
gemini extensions install ./plugin --skip-settings
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.
Load the plugin/ directory as an Agent Plugins 1.0.0 package. It contains
plugin.json, mcp.json, and ten public skills. Copilot shares this portable layout. The MCP
launcher downloads the matching published basemind binary, or uses BASEMIND_BIN for a local build.
Install the program first. Install the locally generated wheel into the same Python environment Hermes runs in, then enable the plugin:
git clone https://github.com/Goldziher/basemind
cd basemind
uv build --wheel --out-dir dist/hermes plugin/.hermes/package
python -m pip install --force-reinstall dist/hermes/basemind_hermes_plugin-0.29.3-py3-none-any.whl
hermes plugins enable basemind
Restart Hermes. The plugin registers ten skills, six slash commands, scoped comms notifications,
and basemind_call, which bridges the local MCP server's nine domains and returns JSON text.
The binary must be on PATH. Comms notifications are
best-effort. You can also configure mcp_servers.basemind with command: basemind and
args: [serve] for direct domain tools.
PyPI version 0.29.3 predates the skill-registration fix and MCP bridge. Use the source wheel above until a newer release includes these changes; reinstalling that published version will not add them.
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.
Install the basemind program first, then install the Pi package:
pi install git:github.com/Goldziher/basemind
The package includes ten skills and a native extension that loads basemind context at session start
and after compaction. Pi runs basemind through its shell tool using the CLI.
No MCP bridge or binary is included. Add -l to save the package in the current project's configuration.
The next release adds these resources to the existing basemind-opencode npm package.
After that release, use pi install npm:basemind-opencode for registry installation and
Pi package-catalog discovery. Both installation paths carry the same extension and skills.
Public skills only. Install the ten public skills independently:
npx skills add Goldziher/basemind
Discovery uses the root skills/ mirror. Maintainer governance and private agents are not included.
For the curated Pi package's ten skills and six prompts, run pi install ./plugin from this checkout;
it carries no automatic context extension. The root Git package above retains the custom extension.
Local or development builds with the plugin. The launcher runs the release that matches the
plugin manifest. Set BASEMIND_BIN=/path/to/basemind to run your own build instead: it is honoured
whatever version it reports (the launcher logs a notice when that differs from the manifest's), and it
wins over BASEMIND_FORCE_VERSION. A build on a different release minor resets the cache on first open
(wipe and rebuild). BASEMIND_FORCE_VERSION=<x.y.z> pins the launcher to one published release
instead of the manifest's.
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 has a title and says whether it only reads or can change things, so your client can
auto-approve the safe ones and ask before the rest. The server also exposes four on-demand MCP
resources whose bodies equal the matching tool result: basemind://status, basemind://repo/map,
basemind://outline/{path} and basemind://memory/{key}. If basemind isn't found, use the full path
from which basemind.
- Claude Code —
claude mcp add basemind -- basemind serve(add--scope userfor all projects; the--is required). Or commit a.mcp.jsonat 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 addin-session, or~/.copilot/mcp-config.jsonwith"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.yamlwithcommand: basemind,args: [serve]. - OpenCode (without the plugin) —
opencode.jsonunder keymcp, withcommandas an array["basemind", "serve"]. - Hermes —
mcp_servers.basemindin~/.hermes/config.yaml(YAML:command: basemind,args: [serve]). For helper skills and notifications, install the source wheel and enable the plugin as described in the Hermes installation section. - Any other tool — point it at the command
basemindwith the argumentserve.
3. As a CLI
The standalone program, for scripts, headless runs, and CI. Install it, then:
basemind scan # index the project once
basemind code symbols "parseQuery" # find a definition by name
basemind code references "processFile" # find everywhere it's called
basemind git blame 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.)
| Channel | Command | Includes |
|---|---|---|
| Homebrew | brew install Goldziher/tap/basemind |
everything |
| npm | pnpm add -g basemind |
everything |
| pip | pip install basemind |
everything |
| cargo | cargo install basemind --locked |
code + git only (the CLI; basemind serve needs --features comms) |
| 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: the one-shot CLI works, but
basemind serve relays to the daemon and so needs the comms feature (--features full has it).
Get started
After installing, run basemind init (CLI) — or /bm-init if your tool supports slash
commands — from the repo root. It's re-runnable and safe to call again later:
- Writes a commented
basemind.tomlscaffold at the repo root, if one doesn't already exist. - Lets you pick which capabilities to advertise (interactive prompt in a TTY, or non-interactive
with
--yes,--with <capability>,--without <capability>). Capability slugs:code-search-navigation,code-mapping-architecture,git-history,file-finding,agent-comms,worktree-coordination,documents-rag,semantic-search. - Injects a "prefer basemind over grep/read/git" rules block. By default it never writes a committed
file unasked: with
.ai-rulez/config.tomlpresent it writes the gitignored.ai-rulez/local/rules/basemind-usage.md; otherwise a terminal run asks, defaulting to the personal, gitignoredCLAUDE.local.md, and a scripted run writesCLAUDE.local.md(orAGENTS.local.mdin a repo that has anAGENTS.mdand noCLAUDE.md). It adds the file to.gitignore. The block is delimited (<!-- BEGIN basemind ... -->/<!-- END basemind -->) so re-running replaces it in place instead of duplicating it.
Preview changes without writing with --print; skip the rules step with --no-rules; steer the
target explicitly with --rules-target <auto|claude|claude-local|agents|agents-local|ai-rulez|ai-rulez-local|none>
(the committed CLAUDE.md, AGENTS.md and .ai-rulez/rules/basemind-usage.md are explicit opt-ins).
--settings-target <local|shared|none> adds basemind's tools to Claude Code's auto-approved
permissions; a non-interactive run skips that unless you pass the flag.
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
basemind MCP questions
How do I add basemind MCP to Claude Code?
Run claude mcp add basemind -- npx -y basemind-opencode in your terminal. Add --scope user to make it available in every project.
How do I add basemind MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does basemind save context window tokens?
It provides file paths, line numbers, and signatures instead of returning whole files, allowing agents to reason from structure rather than reading entire source files.
What programming languages does the code map support?
The system supports code mapping across more than 300 different languages.
Does it support document search?
Yes, it provides semantic search over various formats including PDFs, Office files, HTML, email, and images via OCR.