basemind turns any repo into an always-current map of its code, documents, history, and memory — so agents answer from instead of burning their context window on grep and file reads — and gives a...
Обзор
basemind turns any repo into an always-current map of its code, documents, history, and memory — so agents answer from instead of burning their context window on grep and file reads — and gives a...
README
An agent reasoning from structure — code modes outline and references in a live session, statusline tracking tokens saved.
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), 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) — 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) |
| 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 for agents working the same repo: each addressed by at least two of subject / path-glob / members, discovered by scope (member, cwd path-match, or subject filter — never global), with a recency-filtered inbox. The creator manages membership and archives; idle threads auto-archive. One orchestrator can drive many named subagents (as_agent). |
agents (register · list · thread_start · thread_list · join · leave · members · add_member · remove_member · archive · post · history · message · inbox · ack · wait) |
| 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 plugin downloads the basemind program for you on first use. The MCP-server and CLI paths need it installed yourself — see 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.
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.
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 | 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.
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,--without). 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 your repo’s agent-instructions
file —
.ai-rulez/rules/basemind-usage.mdif.ai-rulez/config.tomlis present (runai-rulez generateafterward), elseCLAUDE.md, elseAGENTS.md, else a newCLAUDE.md. The block is delimited (/) 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 .
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 thread (post, reply, synthesize) — entirely over basemind agents.
How it works
Token saving
Performance
Configuration
CLI reference
License
MIT — see LICENSE.
Установка
This server does not publish a one-line install command.
Open the repository installation guideКонфигурация
{
"mcpServers": {
"basemind": { "command": "basemind", "args": ["serve"] }
}
}