Skip to content

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

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.

Terminal window
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.

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

Terminal window
basemind scan # index the project once
basemind code symbols "parseQuery" # find a symbol by name
basemind code refs "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.

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.

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:

Terminal window
cargo build --release --features full
export 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.

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.toml scaffold 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.toml present it writes the gitignored .ai-rulez/local/rules/basemind-usage.md, otherwise the personal, gitignored CLAUDE.local.md (or AGENTS.local.md in a repo that has only AGENTS.md). The block is delimited (<!-- BEGIN basemind ... --> / <!-- END basemind -->) so re-running replaces it in place instead of duplicating it.
  • Offers to add the .local file to .gitignore when 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.

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.