basemind

What it does

basemind is a Rust program that indexes a repository once and then answers coding agents from that index, so they get paths and line numbers back instead of reading whole files. It parses source with tree-sitter grammars for several hundred languages and pulls text out of documents such as PDFs and email, with OCR for images. The index sits in a machine-wide cache outside the repo. One background daemon per machine holds it and keeps it current as files change. `basemind serve` is only a stdio relay to that daemon and starts it when needed.

Over MCP you get nine tools, and each one picks its operation with a `mode` argument. `code` covers outlines, symbol lookup, grep, definitions and callers. `graph` walks the call graph and exports it. `git` reads history and blame, while `memory` is a per-repo note store plus search over indexed documents. Then there are `web` for scraping and crawling into the document index, `agents` for message threads between agents on one machine, `shell` for background terminal sessions, `admin` for index upkeep, and `workspace` for advisory claims on worktrees and branches. It also serves four resources and four prompts.

Two things the README leaves out. Setting `BASEMIND_MCP_LEAN` swaps the nine tools for three wrappers named `list_tools`, `get_tool_schema` and `invoke_tool`, so a client loads one tool's schema only when it calls it (src/mcp/lean.rs). And the stdio relay gives up on a request the daemon has not answered within 180 seconds by default, which `BASEMIND_RELAY_REQUEST_TIMEOUT_SECS` changes and `0` turns off (src/stdio_relay.rs).

The repo also ships a plugin with ten skills and six commands for eleven agent runtimes. It is optional, and plain MCP clients only need the `basemind serve` command. Gemini CLI installs the plugin from a local clone of the repo, and Hermes from a wheel you build yourself from that clone.

What it needs

Install the program with `pnpm add -g basemind`, `pip install basemind`, `brew install Goldziher/tap/basemind`, a release binary, or `cargo install basemind --features full --locked`. A plain `cargo install basemind --locked` builds only the code and git CLI, and `basemind serve` needs the `comms` feature that `--features full` brings. Run `basemind init` from the repo root: the workspace root must be a git repository or hold a `basemind.toml`. Optional LLM features need a provider API key.

Limits

• Not covered Scope- and import-aware `definition` covers JavaScript/TypeScript, Python and Java. `references` matches by name only, so `Foo::bar()` and `bar()` both count
• Not covered `implementations` does not detect Go's structural interface satisfaction
• Size cap `symbols`, `grep`, `references`, `callers` and `implementations` return 100 results by default, up to 1000 with `limit`
• Size cap `files` and `find` return 200 by default, up to 5000. `semantic` returns 10 by default, up to 100
• Limit `semantic` and `chunk` modes of `code` need the `code-search` build feature
• Platform `agents`, `workspace` and `shell` are compiled only for Unix and Windows builds with the `comms` and `shells` features. `web` needs `crawl`
• Limit The relay drops a request the daemon has not answered in 180 seconds unless BASEMIND_RELAY_REQUEST_TIMEOUT_SECS says otherwise
• Limit A workspace root that is neither a git repo nor holds a basemind config is refused, and a filesystem root always is
• Limit Parameters that belong to a different mode are rejected, not ignored

The README's Hermes steps install a wheel by a fixed file name, `basemind_hermes_plugin-0.29.3-py3-none-any.whl`, from the `dist/hermes` folder the build writes. If the locally built wheel carries a newer version, install the file that `uv build` actually produced in that folder.

Who it suits

Suits developers who run one or more coding agents on a large repo and want them to look up structure, history and docs from a local index instead of grepping and reading files, especially when several agents share a machine and need to coordinate. Everything runs locally and needs no account. It is a heavy install for a small project: a daemon, a machine-wide cache and downloaded models. If you only want file reads and writes, or only git operations, a smaller single-purpose server is simpler. Teams wary of agents running commands should note the `shell` tool in the prebuilt downloads.