Installation
Three ways to run basemind, easiest first. All three share the same local index and are safe to run side by side.
1. As a plugin (recommended)
Section titled “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@basemindRestart, then run /bm-statusline once to turn on the live statusline (a
one-time step — see Statusline). Recommended:
turn on auto-update for the basemind marketplace in Claude Code’s plugin
manager, so you always get the current index format and tool set — or
update it regularly by hand if you’d rather control timing.
codex plugin marketplace add Goldziher/basemindcodex plugin add basemind@basemindIn 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/basemindUpdate later with gemini extensions update basemind.
droid plugin marketplace add https://github.com/Goldziher/baseminddroid plugin install basemind@basemindcopilot plugin marketplace add Goldziher/basemindcopilot plugin install basemind@basemindAdd to opencode.json (project) or ~/.config/opencode/opencode.json
(global):
{ "plugin": ["basemind-opencode@latest"] }/plugins install https://github.com/Goldziher/basemindKimi doesn’t support the comms auto-notifications, but the chat tools still work.
pip install basemindThat ships a native Hermes plugin (the helper skills, slash commands, and
comms notifications), auto-discovered via the hermes_agent.plugins entry
point. Hermes wires tools through config, so add basemind’s tools with the
MCP block (mcp_servers.basemind in
~/.hermes/config.yaml), then enable the plugin:
hermes plugins enable basemindComms 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.
Install the basemind program first, then install the package:
pi install git:github.com/Goldziher/basemindThe package includes ten skills and a native extension that loads basemind context at
session start and after compaction. Pi runs the CLI through its shell tool;
no MCP bridge or binary is included. Add -l for a project-scoped installation.
The next release adds these resources to the existing basemind-opencode npm package.
After that release, pi install npm:basemind-opencode provides registry installation
and Pi package-catalog discovery. Both installation paths include the same resources.
2. As an MCP server
Section titled “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.
Per-tool specifics
Section titled “Per-tool specifics”claude mcp add basemind -- basemind serveAdd --scope user for all projects; the -- is required. Or commit a
.mcp.json at the repo root with the block above.
Put the block above in .cursor/mcp.json (project) or ~/.cursor/mcp.json
(global).
~/.codeium/windsurf/mcp_config.json (or Cascade → MCP servers → manage),
then Refresh.
codex mcp add basemind -- basemind serveShared by the CLI and IDE.
gemini mcp add basemind basemind serveOr the block above in ~/.gemini/settings.json.
/mcp add in-session, or ~/.copilot/mcp-config.json with
"type": "local" and "tools": ["*"].
droid mcp add basemind "basemind serve"Or ~/.factory/mcp.json.
MCP Servers icon → Configure → add the block above.
.continue/mcpServers/basemind.yaml with command: basemind, args: [serve].
mcp_servers.basemind in ~/.hermes/config.yaml (YAML, not JSON):
mcp_servers: basemind: command: basemind args: [serve]Then hermes plugins enable basemind. pip install basemind also ships a
native Hermes plugin with the helper skills and comms notifications.
opencode.json under key mcp, with command as an array
["basemind", "serve"].
Point it at the command basemind with the argument serve.
3. As a CLI
Section titled “3. As a CLI”The standalone program, for scripts, headless runs, and CI. Install it, then:
basemind scan # index the project oncebasemind code symbols "parseQuery" # find a symbol by namebasemind code refs "processFile" # find everywhere it's calledbasemind git blame src/main.rs # who last changed each linebasemind watch # keep the index fresh as files changeFull command list in the CLI reference.
Install the program
Section titled “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 |
| cargo (full) | cargo install basemind --features full --locked |
everything |
| GitHub releases | Download a binary | everything |
The Homebrew / npm / pip / GitHub downloads are built with full —
documents, OCR, named-entity recognition, search, shared memory, and agent comms
— so the first run downloads the models it needs. The plain cargo install
builds the code-map and git tools only.
In a source build, --features documents covers document search without OCR or named-entity
recognition. Add documents-ocr (raster images and scanned PDFs) and documents-ner (the
entity_category filter), or build with full, which has both. See
Cargo Features.
Using a local build with the plugin
Section titled “Using a local build with the plugin”The plugin launcher (scripts/mcp-launch.sh) normally downloads the release binary that matches the
plugin manifest into ~/.cache/basemind/versions/<version>/ and verifies its checksum. To run a binary you
built yourself, point BASEMIND_BIN at it in the environment your client starts the server from:
cargo build --release --features fullexport BASEMIND_BIN="$PWD/target/release/basemind"BASEMIND_BIN is an explicit pin: it is honoured whatever version the binary reports. When that
version differs from the plugin manifest the launcher logs BASEMIND_BIN pins basemind X while the plugin manifest pins Y; using the pin and carries on, so you do not need to set anything else. A
build on a different schema minor than your existing cache rebuilds the cache on its first scan.
BASEMIND_FORCE_VERSION is internal to the launcher’s release-window fallback and is not needed here.
The daemon is spawned from the same executable; BASEMIND_DAEMON_BINARY overrides which binary it
spawns when the running one is not basemind itself.
Get started
Section titled “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,agent-comms,documents-rag,semantic-search. - Injects a “prefer basemind over grep/read/git” rules block into an agent-instructions
file. By default it never touches a committed file: with
.ai-rulez/config.tomlpresent it writes the gitignored.ai-rulez/local/rules/basemind-usage.md, otherwise the personal, gitignoredCLAUDE.local.md(orAGENTS.local.mdin a repo that has onlyAGENTS.md). The block is delimited (<!-- BEGIN basemind ... -->/<!-- END basemind -->) so re-running replaces it in place instead of duplicating it. - Offers to add the
.localfile to.gitignorewhen no existing rule covers it. - Optionally adds basemind’s MCP tools to Claude Code’s auto-approved permissions
(
--settings-target local|shared|none). A non-interactive run skips this unless the flag is passed.
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 non-local values write a committed file, so they are opt-in only). Leave out the
routing table with --no-usage-rules or the setup notes with --no-setup-notes.
To keep the config under the .config/ convention, pass --config-dir .config or
--config-dir .config/basemind.
Statusline (Claude Code)
Section titled “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 @reviewerThe 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.