Skip to content
Back to search

basemind

Basemind code intelligence and context for coding agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 15 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Goldziher/basemind with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Goldziher/basemind'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/goldziher--basemind/badge.svg)](/listings/goldziher--basemind)

HTML

<a href="/listings/goldziher--basemind"><img src="/api/listings/goldziher--basemind/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](#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](plugin/README.md) 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.

<details> <summary><strong>Claude Code</strong></summary>

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](#install-the-program)). **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.

</details>

<details> <summary><strong>Codex</strong></summary>

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.

</details>

<details> <summary><strong>Cursor</strong></summary>

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

</details>

<details> <summary><strong>Gemini CLI</strong></summary>

git clone https://github.com/Goldziher/basemind
cd basemind
gemini extensions install ./plugin --skip-settings

Update later with `gemini extensions update basemind`.

</details>

<details> <summary><strong>Factory Droid</strong></summary>

droid plugin marketplace add https://github.com/Goldziher/basemind
droid plugin install basemind@basemind

</details>

<details> <summary><strong>GitHub Copilot CLI</strong></summary>

copilot plugin marketplace add Goldziher/basemind
copilot plugin install basemind@basemind

</details>

<details> <summary><strong>OpenCode</strong></summary>

Add to `opencode.json` (project) or `~/.config/opencode/opencode.json` (global):

{ "plugin": ["basemind-opencode@latest"] }

</details>

<details> <summary><strong>Kimi Code</strong></summary>

/plugins install https://github.com/Goldziher/basemind

Kimi doesn't support the comms auto-notifications, but the chat tools still work.

</details>

<details> <summary><strong>Agent Plugins (agent-plugins.org)</strong></summary>

Load the `plugin/` directory as an [Agent Plugins](https://agent-plugins.org) 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.

</details>

<details> <summary><strong>Hermes</strong></summary>

[Install the program](#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,

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "name": "basemind",
  3. "description": "Basemind code intelligence and context for coding agents.",
  4. "owner": {
  5. "name": "Na'aman Hirschfeld",
  6. "email": "nhirschfeld@gmail.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "basemind",
  11. "description": "Full AI context layer over MCP — tree-sitter code-map, document RAG (PDF/Office/HTML/email + OCR + reranker), shared agent memory, git history + blame + per-symbol diff. 300+ languages, 10+ coding-agent harnesses, content-addressed Fjall + LanceDB.",
  12. "source": "./plugin"
  13. }
  14. ]
  15. }
README.md · README · 1,245 lines
  1. <!-- markdownlint-disable MD033 MD041 -->
  2. <div align="center">
  3. <img src="docs/media/basemind-banner.svg" alt="basemind — cybernetic core" width="820">
  4. **The context and communication layer for coding agents.**
  5. basemind turns any repo into an always-current map of its code, documents, history, and memory —
  6. so agents answer from **structure and search** instead of burning their context window on `grep` and
  7. file reads — and gives a team of agents a **shared channel to coordinate** while they work. One
  8. server does both.
  9. Code map across **300+ languages** · PDF, Office, HTML, email and image documents · semantic + full-text search ·
  10. git history & blame · shared memory · agent-to-agent comms
  11. [![Docs](https://img.shields.io/badge/docs-basemind.ai-965aff?style=flat-square)](https://basemind.ai)
  12. [![crates.io](https://img.shields.io/crates/v/basemind?style=flat-square)](https://crates.io/crates/basemind)
  13. [![npm](https://img.shields.io/npm/v/basemind?style=flat-square)](https://www.npmjs.com/package/basemind)
  14. [![PyPI](https://img.shields.io/pypi/v/basemind?style=flat-square)](https://pypi.org/project/basemind/)
  15. [![CI](https://img.shields.io/github/actions/workflow/status/Goldziher/basemind/ci.yaml?style=flat-square)](https://github.com/Goldziher/basemind/actions/workflows/ci.yaml)
  16. [![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
  17. [Docs](https://basemind.ai) · [Install](#installation) · [Features](#what-you-get) · [How it works](#how-it-works) · [Performance](#performance) · [CLI](#cli-reference)
  18. </div>
  19. ---
  20. <!-- markdownlint-disable MD013 -->
  21. <p align="center"><img src="docs/media/mcp-demo.gif" alt="An agent answering from a file outline and its call sites in a live Claude Code session" width="820"></p>
  22. <p align="center"><em>An agent reasoning from structure — a file outline and a call-site lookup in a live session, statusline tracking tokens saved.</em></p>
  23. <!-- markdownlint-enable MD013 -->
  24. <div align="center"><sub><a href="#demos">More demos ↓</a></sub></div>
  25. ---
  26. ## What you get
  27. basemind answers with **file paths, line numbers, and signatures — not whole files** — so a question
  28. about your code costs a small fraction of the tokens it takes to read the source.
  29. <!-- markdownlint-disable MD013 -->
  30. | Capability | What it does | Key tools |
  31. |---|---|---|
  32. | **Code intelligence** | Read the code map instead of opening files: what a file contains (`code_outline`), where a name is defined (`code_symbols`), one symbol's body or an exact line span (`code_read`), text search, literal by default (`code_grep`), search by meaning over indexed chunks (`code_search`, needs `--features code-search`), and usages (`code_refs`): call sites of a name, callers of one definition, implementors of a trait / interface / base class, importers of a module, and go-to-definition (**scope- and import-aware**, JS/TS via oxc, Python & Java via in-tree [stack-graphs](#how-it-works)). `find_files` locates or lists files, documents included. Layered over [300+ languages](#how-it-works). | `code_outline` · `code_symbols` · `code_read` · `code_grep` · `code_search` · `code_refs` · `find_files` |
  33. | **Git intelligence** | Ask what changed recently, which commits touched a file, which commit mentions a phrase (full-text over messages and authors at full branch depth), when a symbol's body changed, who last touched a line or a function, and how a file differs between revisions or from the working tree, as text hunks or as symbols added and removed. | `git_log` · `git_blame` · `git_diff` |
  34. | **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 in the published binaries, no extra setup; a source build needs the `documents-ocr` Cargo feature). | `memory_save` · `memory_search` · `docs_search` |
  35. | **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`) |
  36. | **Index** | Check index health and repo identity, and refresh the index after edits. Telemetry and cache maintenance are CLI commands (`basemind admin telemetry`, `basemind cache stats\|gc\|clear`). | `index_status` · `index_rescan` |
  37. | **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`) |
  38. <!-- markdownlint-enable MD013 -->
  39. The code, git, memory, document and index rows are 15 tools, one per job, each with its own exact
  40. schema; there is no `mode` argument. They are always loaded (`_meta["anthropic/alwaysLoad"]`), so a host that defers MCP tools
  41. needs no tool-search round trip: call them directly. Their `tools/list` entry is about 18 KB (about
  42. 4.5k tokens). `agents` and `workspace` (`comms` builds) still take a `mode` and are not always loaded. An unknown argument is
  43. rejected with a did-you-mean suggestion, every line number is 1-based, and a failure the caller can
  44. fix comes back as an `isError` result that names the fix. Arguments, examples and the mapping from
  45. the previous `code` / `git` / `memory` / `admin` tools: the
  46. [MCP tool reference](https://basemind.ai/reference/mcp-tools/) and
  47. [`docs/UPGRADING.md`](docs/UPGRADING.md).
  48. ```text
  49. code_outline {"path":"src/store.rs"}
  50. code_symbols {"name":"parse_config","kind":"function"}
  51. code_read {"path":"src/store.rs","symbol":"open"}
  52. code_grep {"pattern":"cache_root(","path":"src/"}
  53. code_refs {"name":"open_store","path":"src/store.rs"}
  54. git_log {"path":"src/store.rs","limit":5}
  55. git_diff {"path":"src/store.rs","from":"HEAD~1","to":"HEAD"}
  56. docs_search {"query":"how releases are versioned"}
  57. ```
  58. ---
  59. ## Installation
  60. Three ways to run basemind, easiest first. All three share the same local index and are safe to run
  61. side by side.
  62. > **The MCP plugin downloads the basemind program for you** on first use. Pi, the MCP-server,
  63. > and CLI paths need it installed yourself — see [Install the program](#install-the-program).
  64. ### 1. As a plugin (recommended)
  65. The curated plugin under `plugin/` contains ten public skills and six commands for eleven runtime
  66. profiles. See the [plugin installation guide](plugin/README.md) for local installation and release
  67. prerequisites. The repository root also retains the existing OpenCode terminal adapter and Pi
  68. extension; those integrations have separate package entry points.
  69. <details>
  70. <summary><strong>Claude Code</strong></summary>
  71. In the session (not your shell), run in order:
  72. ```text
  73. /plugin marketplace add Goldziher/basemind
  74. /plugin install basemind@basemind
  75. ```
  76. Restart, then run `/bm-statusline` once to turn on the live statusline (a one-time step — see
  77. [Statusline](#install-the-program)). **Turn on auto-update for the `basemind` marketplace**
  78. (Claude Code's plugin manager): the plugin then tracks each new release automatically, and the
  79. launcher resolves the matching published release. Prefer to control timing? Update the
  80. marketplace regularly by hand instead.
  81. </details>
  82. <details>
  83. <summary><strong>Codex</strong></summary>
  84. ```bash
  85. codex plugin marketplace add Goldziher/basemind
  86. codex plugin add basemind@basemind
  87. ```
  88. In the app: open the **Plugins** sidebar and add basemind. The CLI and IDE share one config file.
  89. The generated plugin uses the matching published GitHub release, or a local `BASEMIND_BIN` override.
  90. </details>
  91. <details>
  92. <summary><strong>Cursor</strong></summary>
  93. In Agent chat: `/add-plugin basemind` (once listed), or go to **Dashboard → Settings → Plugins →
  94. Team Marketplaces → Import from Repo** and point it at `https://github.com/Goldziher/basemind`.
  95. </details>
  96. <details>
  97. <summary><strong>Gemini CLI</strong></summary>
  98. ```bash
  99. git clone https://github.com/Goldziher/basemind
  100. cd basemind
  101. gemini extensions install ./plugin --skip-settings
  102. ```
  103. Update later with `gemini extensions update basemind`.
  104. </details>
  105. <details>
  106. <summary><strong>Factory Droid</strong></summary>
  107. ```bash
  108. droid plugin marketplace add https://github.com/Goldziher/basemind
  109. droid plugin install basemind@basemind
  110. ```
  111. </details>
  112. <details>
  113. <summary><strong>GitHub Copilot CLI</strong></summary>
  114. ```bash
  115. copilot plugin marketplace add Goldziher/basemind
  116. copilot plugin install basemind@basemind
  117. ```
  118. </details>
  119. <details>
  120. <summary><strong>OpenCode</strong></summary>
  121. Add to `opencode.json` (project) or `~/.config/opencode/opencode.json` (global):
  122. ```json
  123. { "plugin": ["basemind-opencode@latest"] }
  124. ```
  125. </details>
  126. <details>
  127. <summary><strong>Kimi Code</strong></summary>
  128. ```text
  129. /plugins install https://github.com/Goldziher/basemind
  130. ```
  131. Kimi doesn't support the comms auto-notifications, but the chat tools still work.
  132. </details>
  133. <details>
  134. <summary><strong>Agent Plugins (agent-plugins.org)</strong></summary>
  135. Load the `plugin/` directory as an [Agent Plugins](https://agent-plugins.org) 1.0.0 package. It contains
  136. `plugin.json`, `mcp.json`, and ten public skills. Copilot shares this portable layout. The MCP
  137. launcher downloads the matching published basemind binary, or uses `BASEMIND_BIN` for a local build.
  138. </details>
  139. <details>
  140. <summary><strong>Hermes</strong></summary>
  141. [Install the program](#install-the-program) first. Install the locally generated wheel into the
  142. same Python environment Hermes runs in, then enable the plugin:
  143. ```bash
  144. git clone https://github.com/Goldziher/basemind
  145. cd basemind
  146. uv build --wheel --out-dir dist/hermes plugin/.hermes/package
  147. python -m pip install --force-reinstall dist/hermes/basemind_hermes_plugin-0.29.3-py3-none-any.whl
  148. hermes plugins enable basemind
  149. ```
  150. Restart Hermes. The plugin registers ten skills, six slash commands, scoped comms notifications,
  151. and `basemind_call`, which bridges the local MCP server's tools and returns JSON text.
  152. The binary must be on `PATH`. Comms notifications are
  153. best-effort. You can also configure `mcp_servers.basemind` with `command: basemind` and
  154. `args: [serve]` for direct access to the tools.
  155. PyPI version 0.29.3 predates the skill-registration fix and MCP bridge. Use the source wheel above
  156. until a newer release includes these changes; reinstalling that published version will not add them.
  157. </details>
  158. <details>
  159. <summary><strong>Antigravity</strong></summary>
  160. **Antigravity** uses a shared MCP config — [install the program](#install-the-program), then add the
  161. [generic MCP block](#2-as-an-mcp-server). If you already use the Gemini extension,
  162. `agy plugin import gemini` brings it across.
  163. </details>
  164. <details>
  165. <summary><strong>Pi</strong></summary>
  166. [Install the basemind program](#install-the-program) first, then install the Pi package:
  167. ```sh
  168. pi install git:github.com/Goldziher/basemind
  169. ```
  170. The package includes ten skills and a native extension that loads basemind context at session start
  171. and after compaction. Pi runs basemind through its shell tool using the [CLI](#3-as-a-cli).
  172. No MCP bridge or binary is included. Add `-l` to save the package in the current project's configuration.
  173. The next release adds these resources to the existing `basemind-opencode` npm package.
  174. After that release, use `pi install npm:basemind-opencode` for registry installation and
  175. Pi package-catalog discovery. Both installation paths carry the same extension and skills.
  176. </details>
  177. **Public skills only.** Install the ten public skills independently:
  178. ```sh
  179. npx skills add Goldziher/basemind
  180. ```
  181. Discovery uses the root `skills/` mirror. Maintainer governance and private agents are not included.
  182. For the curated Pi package's ten skills and six prompts, run `pi install ./plugin` from this checkout;
  183. it carries no automatic context extension. The root Git package above retains the custom extension.
  184. **Local or development builds with the plugin.** The launcher runs the release that matches the
  185. plugin manifest. Set `BASEMIND_BIN=/path/to/basemind` to run your own build instead: it is honoured
  186. whatever version it reports (the launcher logs a notice when that differs from the manifest's), and it
  187. wins over `BASEMIND_FORCE_VERSION`. A build on a different release minor resets the cache on first open
  188. (wipe and rebuild). `BASEMIND_FORCE_VERSION=<x.y.z>` pins the launcher to one published release
  189. instead of the manifest's.
  190. ### 2. As an MCP server
  191. If your tool speaks MCP but you're not using the plugin, [install the program](#install-the-program),
  192. then register it:
  193. ```json
  194. {
  195. "mcpServers": {
  196. "basemind": { "command": "basemind", "args": ["serve"] }
  197. }
  198. }
  199. ```
  200. Each tool has a title and says whether it only reads or can change things, so your client can
  201. auto-approve the safe ones and ask before the rest. The server also exposes three on-demand MCP
  202. resources whose bodies equal the matching tool result: `basemind://status`,
  203. `basemind://outline/{path}` and `basemind://memory/{key}`. If `basemind` isn't found, use the full path
  204. from `which basemind`.
  205. <details>
  206. <summary><strong>Per-tool specifics</strong> (Claude Code · Cursor · Windsurf · Codex · Gemini · Copilot · Droid · Cline · Continue · OpenCode · Hermes)</summary>
  207. - **Claude Code** — `claude mcp add basemind -- basemind serve` (add `--scope user` for all
  208. projects; the `--` is required). Or commit a `.mcp.json` at the repo root with the block above.
  209. - **Cursor** — put the block above in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
  210. - **Windsurf** — `~/.codeium/windsurf/mcp_config.json` (or Cascade → MCP servers → manage), then
  211. **Refresh**.
  212. - **Codex** — `codex mcp add basemind -- basemind serve`, shared by the CLI and IDE.
  213. - **Gemini CLI** — `gemini mcp add basemind basemind serve`, or the block above in
  214. `~/.gemini/settings.json`.
  215. - **GitHub Copilot CLI** — `/mcp add` in-session, or `~/.copilot/mcp-config.json` with
  216. `"type": "local"` and `"tools": ["*"]`.
  217. - **Factory Droid** — `droid mcp add basemind "basemind serve"`, or `~/.factory/mcp.json`.
  218. - **Cline** — MCP Servers icon → Configure → add the block above.
  219. - **Continue** — `.continue/mcpServers/basemind.yaml` with `command: basemind`, `args: [serve]`.
  220. - **OpenCode (without the plugin)** — `opencode.json` under key `mcp`, with `command` as an array
  221. `["basemind", "serve"]`.
  222. - **Hermes** — `mcp_servers.basemind` in `~/.hermes/config.yaml` (YAML: `command: basemind`,
  223. `args: [serve]`). For helper skills and notifications, install the source wheel and enable the
  224. plugin as described in the [Hermes installation section](#1-as-a-plugin-recommended).
  225. - **Any other tool** — point it at the command `basemind` with the argument `serve`.
  226. </details>
  227. ### 3. As a CLI
  228. The standalone program, for scripts, headless runs, and CI. [Install it](#install-the-program), then:
  229. ```bash
  230. basemind scan # index the project once
  231. basemind code symbols "parseQuery" # find a definition by name
  232. basemind code refs "processFile" # find everywhere it's called
  233. basemind git blame src/main.rs # who last changed each line
  234. basemind watch # keep the index fresh as files change
  235. ```
  236. Full command list in the [CLI reference](#cli-reference).
  237. ### Install the program
  238. The MCP and CLI paths need `basemind` available on your system. (The plugin does this for you.)
  239. <!-- markdownlint-disable MD013 -->
  240. | Channel | Command | Includes |
  241. |---|---|---|
  242. | Homebrew | `brew install Goldziher/tap/basemind` | everything |
  243. | npm | `pnpm add -g basemind` | everything |
  244. | pip | `pip install basemind` | everything |
  245. | cargo | `cargo install basemind --locked` | code + git only (the CLI; `basemind serve` needs `--features comms`) |
  246. | cargo (full) | `cargo install basemind --features full --locked` | everything |
  247. | GitHub releases | [Download a binary](https://github.com/Goldziher/basemind/releases) | everything |
  248. <!-- markdownlint-enable MD013 -->
  249. The Homebrew / npm / pip / GitHub downloads are built with `full` — documents, OCR, named-entity
  250. recognition, search, shared memory, and agent comms — so the first run downloads the models it
  251. needs. The plain `cargo install` builds the code-map and git tools only: the one-shot CLI works, but
  252. `basemind serve` relays to the daemon and so needs the `comms` feature (`--features full` has it).
  253. A source build picks its document tiers by Cargo feature:
  254. <!-- markdownlint-disable MD013 -->
  255. | Feature | Adds | In `full` |
  256. |---|---|---|
  257. | `documents` | Document search over local files: PDF (text layer), Office formats, spreadsheets, email, HTML, XML (SVG text is read as XML), Markdown/MDX and Jupyter notebooks, with chunking, language detection, quality scoring, keywords, extractive summaries, the cross-encoder reranker and embeddings. No OCR, no NER. | yes |
  258. | `documents-ocr` | `documents` plus Tesseract OCR: raster images and scanned PDFs (no text layer). Runs implicitly, no configuration. | yes |
  259. | `documents-ner` | `documents` plus ONNX named-entity recognition (GLiNER): `[documents.ner]` and the `entity` filter of `docs_search`. | yes |
  260. | `documents-ocr-paddle` | `documents-ocr` plus PaddleOCR as an optional fallback stage. Source builds only. | no |
  261. <!-- markdownlint-enable MD013 -->
  262. `--features documents` alone no longer includes OCR or NER; use
  263. `--features "documents documents-ocr documents-ner"` (or `full`) to keep both. Without
  264. `documents-ocr`, raster images are not indexed as documents and a PDF with no text layer is indexed
  265. with no text, with a warning naming the file and the feature. Without `documents-ner`,
  266. `[documents.ner] enabled = true` has no effect and logs a warning, and `docs_search` with
  267. `entity` returns an error naming the feature.
  268. ### Get started
  269. After installing, run **`basemind init`** (CLI) — or **`/bm-init`** if your tool supports slash
  270. commands — from the repo root. It's re-runnable and safe to call again later:
  271. - Writes a commented `basemind.toml` scaffold at the repo root, if one doesn't already exist.
  272. - Lets you pick which capabilities to advertise (interactive prompt in a TTY, or non-interactive
  273. with `--yes`, `--with <capability>`, `--without <capability>`). Capability slugs:
  274. `code-search-navigation`, `code-mapping-architecture`, `git-history`, `file-finding`, `agent-comms`,
  275. `worktree-coordination`, `documents-rag`, `semantic-search`.
  276. - Injects a "prefer basemind over grep/read/git" rules block. By default it never writes a committed
  277. file unasked: with `.ai-rulez/config.toml` present it writes the gitignored
  278. `.ai-rulez/local/rules/basemind-usage.md`; otherwise a terminal run asks, defaulting to the
  279. personal, gitignored `CLAUDE.local.md`, and a scripted run writes `CLAUDE.local.md` (or
  280. `AGENTS.local.md` in a repo that has an `AGENTS.md` and no `CLAUDE.md`). It adds the file to
  281. `.gitignore`. The block is delimited
  282. (`<!-- BEGIN basemind ... -->` / `<!-- END basemind -->`) so re-running replaces it in place
  283. instead of duplicating it.
  284. Preview changes without writing with `--print`; skip the rules step with `--no-rules`; steer the
  285. target explicitly with `--rules-target <auto|claude|claude-local|agents|agents-local|ai-rulez|ai-rulez-local|none>`
  286. (the committed `CLAUDE.md`, `AGENTS.md` and `.ai-rulez/rules/basemind-usage.md` are explicit opt-ins).
  287. `--settings-target <local|shared|none>` adds basemind's tools to Claude Code's auto-approved
  288. permissions; a non-interactive run skips that unless you pass the flag.
  289. <details>
  290. <summary><strong>Statusline</strong> (Claude Code)</summary>
  291. Run `/bm-statusline` once. This is a one-time step because Claude Code doesn't let plugins set the
  292. main statusline themselves — so basemind asks the assistant to make the one-line settings change on
  293. your behalf, and it sticks from then on.
  294. It shows two lines:
  295. ```text
  296. Opus · basemind · ⎇ main · 12% ctx
  297. ◆ basemind ● 1,247 files · 23m ago │ 312 calls · 180 srch · 44 git · 12 docs │ 1.4M saved │ ✉ 3 @reviewer
  298. ```
  299. The dot is green when basemind is live and fresh, amber when idle, red when stale. The middle shows
  300. activity by type, then tokens saved, then unread messages. Adjust with
  301. `BASEMIND_STATUSLINE=full|compact|minimal`, or hide the top line with `BASEMIND_STATUSLINE_CONTEXT=0`.
  302. </details>
  303. ---
  304. ## Demos
  305. <!-- markdownlint-disable MD013 -->
  306. <p align="center"><img src="docs/media/demo.gif" alt="basemind CLI: scan, then symbol / reference / blame queries" width="760"></p>
  307. <p align="center"><em>The same engine from the CLI — <code>scan</code>, then symbol / reference / blame queries.</em></p>
  308. <p align="center"><img src="docs/media/semantic-demo.gif" alt="Semantic search over the documents store" width="820"></p>
  309. <p align="center"><em>Searching documents by meaning, not keywords, across PDFs, Office files, HTML and email.</em></p>
  310. <p align="center"><img src="docs/demos/code-review-panel.gif" alt="Three named reviewer agents posting findings to a shared repo-scoped thread, replying to each other, and an orchestrator synthesizing a verdict over the comms CLI" width="820"></p>
  311. <p align="center"><em>Multi-agent code-review panel: named reviewers coordinate in a repo-scoped thread (post, reply, synthesize) — entirely over <code>basemind agents</code>.</em></p>
  312. <!-- markdownlint-enable MD013 -->
  313. ---
  314. ## How it works
  315. <details>
  316. <summary><strong>From one scan to instant answers</strong></summary>
  317. `basemind scan` reads your project once, in parallel. It maps your code with
  318. [tree-sitter] (across [300+ languages][tslp]) and pulls text out of your documents with
  319. [xberg], then saves the result to a global cache under the XDG data directory, keyed by workspace —
  320. nothing is written into your repo. After that, the background daemon keeps the map in memory (one
  321. shared copy per workspace) and answers questions instantly — no re-reading the project for each one;
  322. `basemind serve` is a thin stdio relay to it. When files change, it updates only what changed. The
  323. daemon is the sole writer to that cache, so multiple sessions on the same repo (or on different
  324. worktrees of it) all read and write concurrently instead of one falling back read-only. See
  325. [Global cache & the daemon](#how-it-works) below.
  326. Navigation is **scope- and import-aware** for JavaScript/TypeScript, **Python, and Java**: basemind
  327. resolves each use to the definition it actually binds to, so a shadowed local isn't confused with an
  328. import and `code_refs` with `relation: "definition"` lands on the right target (including across files
  329. for imports). Every
  330. other language still gets fast tree-sitter scope binding. Precise Python/Java resolution runs GitHub
  331. stack-graphs-style `.tsg` name-binding rules via an in-tree engine (`crates/`), with no per-language
  332. LSP server.
  333. Resolution **refines, but never shrinks, a result set.** `code_refs` with a `path` (callers of the
  334. definition in that file) reports every call site whose callee is exactly that name — the same sound
  335. floor a `code_refs` call without `path` uses — and marks each hit `resolved` when resolution proved
  336. it binds to that definition (`resolved_total` counts them). Matching is on the whole identifier, so
  337. `open` no longer counts `open_store`; pass `match: "substring"` for the looser match. It deliberately
  338. does *not* return only the resolved subset: resolution cannot see through a module-object import
  339. (`from pkg import mod` then `mod.f()`) or an unresolvable path alias, so filtering to it would drop
  340. real callers and report the remainder as complete. Filter on `resolved` when you want precision; trust
  341. `total` when you need completeness.
  342. The code map is **code only**. Prose, data and config files — Markdown, reStructuredText, AsciiDoc,
  343. vimdoc, CSV, JSON, YAML, TOML, INI, XML, `.properties`, `.env`, diffs, `.gitignore`/`.gitattributes`
  344. and Fluent — go to the document tier instead: they are chunked and searched as text with
  345. `docs_search` (gated by `[documents] include` / `exclude`), and no longer show up in `code_outline`,
  346. `code_symbols` and `code_grep`. `find_files` still covers them, labelled by grammar name or
  347. extension. An existing index migrates on its next scan. A build
  348. without the `documents` feature keeps the old behaviour, where those files are outlined as code.
  349. ```mermaid
  350. flowchart LR
  351. A(["Coding agent"])
  352. R["Your project<br/>code · documents · git"]
  353. S["basemind scan<br/>map code & read documents"]
  354. D[("Global cache<br/>per-OS data dir")]
  355. V["basemind serve<br/>answers questions"]
  356. R --> S --> D --> V
  357. A <-->|asks questions| V
  358. classDef accent fill:#2563eb,stroke:#1e40af,color:#fff
  359. class S,V accent
  360. ```
  361. Search and memory are powered by a vector store ([LanceDB]).
  362. </details>
  363. <details>
  364. <summary><strong>Index lifecycle &amp; freshness</strong></summary>
  365. The daemon answers the MCP handshake immediately and warms the code map into memory in the
  366. background, so a client never blocks waiting for a large repo to load. The `status` tool reports
  367. `warming` (still loading) and, once done, `warm_ms`; a first-time index build similarly reports
  368. `indexing` / `index_build_ms`.
  369. While the server isn't fully ready, `status` and every code-map read tool may carry a `notice`
  370. object — `{ state, message, retry }` — instead of (or alongside) their normal result:
  371. | `state` | Meaning | `retry` |
  372. |---|---|---|
  373. | `warming_up` | Loading an existing index into memory. | `true` |
  374. | `building_index` | Indexing from scratch (no cache entry for this workspace yet). | `true` |
  375. | `rescanning` | Incremental rescan after a file change; current results are usable but may be stale. | `false` |
  376. Treat an empty or partial result carrying a `notice` as "retry shortly," not "no matches" — poll
  377. `status` (or just retry the call) until the notice clears.
  378. </details>
  379. <details>
  380. <summary><strong>Global cache &amp; the daemon</strong></summary>
  381. Index state lives under a single global cache — `~/.local/share/basemind/` on Linux,
  382. `~/Library/Application Support/basemind/` on macOS (override with `BASEMIND_DATA_HOME`) — keyed by
  383. workspace, never inside your repo. The
  384. content-addressed blob store is machine-wide too: identical file content scanned from different repos
  385. or worktrees is extracted and stored once.
  386. A new linked worktree's working view is seeded from a sibling checkout's index with a copy-on-write
  387. clone, so its first scan only touches files that differ. Only the view is cloned: the vector store is
  388. not, so the seeded worktree's first scan rebuilds its vector rows from the cached blobs without
  389. re-embedding. A sibling whose workspace lock is held (a daemon or another scan is writing it) is not a
  390. seed source, and neither is one too large to copy on a filesystem without reflinks; the new worktree
  391. then scans from scratch. Set `BASEMIND_NO_SEED=1` (any non-empty value other than `0`) to opt out.
  392. Linked worktrees share one git-history index per clone. A worktree whose HEAD descends from the
  393. indexed head appends the new commits; one that diverges leaves the index alone and answers history
  394. queries by walking git directly (correct, just slower), rather than wiping and rebuilding it on every
  395. worktree switch. The first build may come from any worktree.
  396. Memory is bounded by design:
  397. - `[resources] max_footprint_mb` (auto by default) is a best-effort ceiling on the process footprint.
  398. The scan processes files in bounded chunks and pauses between them while over the ceiling; if it
  399. is still over after five seconds it halves its chunk size and worker count and carries on, then
  400. widens again once memory clears. A large-file parse is likewise admitted anyway after five seconds.
  401. Document extraction is admitted *exclusively*: over the ceiling exactly one document runs at a time
  402. (an otherwise idle process is admitted immediately), and a document whose header-derived
  403. working-set estimate exceeds the whole ceiling is skipped and counted as too large.
  404. - ONNX Runtime runs on the CPU provider by default (`onnx_provider = "cpu"`): on macOS the platform
  405. default, CoreML, measured 7.6 GB resident after embedding one 2 KB SVG against 0.8 GB on CPU. In
  406. every basemind process ONNX has no memory-pattern planning and no retained CPU arena, which
  407. otherwise grow to the largest batch seen and never shrink. Intra-op threads are the auto
  408. embed-thread count (`max(2, logical CPUs / 4)`), or 2 in the daemon, which also drops its resident
  409. embedding models once the last concurrent embedding pass ends; the next pass reloads them.
  410. - Precise Python/Java resolution abandons a file past 600,000 builder steps, 4,096 stitching phases
  411. (about a million path extensions), 50,000 partial paths or 3 seconds, and runs at most two
  412. stack-graph builds at once. The stitcher checks those budgets every 256 path extensions, not once
  413. per phase, so a pathological file cannot grow between checks.
  414. - On macOS the allocator (mimalloc) heap is tagged as application memory (Mach VM tag 254), so
  415. `footprint`, `vmmap` and Activity Monitor no longer report it as `IOAccelerator` "GPU" memory.
  416. A workspace root must be a project: a git repository, or a directory containing a basemind config
  417. (`basemind.toml` at the root, or under the `.config/` convention). Anything else is refused, because
  418. basemind opens a root read-write and indexes every file beneath
  419. it — so an accidentally inherited root (`/`, your home directory, or wherever an MCP host happened
  420. to start) would become a whole-filesystem scan. Run `basemind init` to mark a directory you do want
  421. indexed, or set `BASEMIND_ALLOW_ANY_ROOT=1` to skip the check. A filesystem or volume root is
  422. refused unconditionally and cannot be overridden.
  423. A single background daemon per machine is the sole writer to that cache and hosts the MCP server:
  424. `basemind serve` is a thin stdio relay that ensures the daemon is up and pumps bytes to it, so N
  425. sessions on the same repo — or on different worktrees of it — share one read stack per workspace
  426. and all read and write concurrently instead of a second session silently falling back to a stale,
  427. read-only view. The daemon holds the single-writer index, so `code_refs` lookups (call sites,
  428. callers, implementations) run inside it and return complete results with no per-session copy. The daemon
  429. also keeps a cheap, always-on registry of repos, worktrees, and branches (`workspace` modes
  430. `workspaces` / `worktrees` / `branches`), and modes `claim` / `release` give agent sessions an
  431. advisory way to avoid colliding on the same worktree.
  432. `basemind statusline` queries the daemon for the workspaces currently active and prints a compact
  433. line for your shell prompt; it prints nothing when no daemon is running.
  434. The daemon is started on demand, detached with `setsid(2)`. That changes the session and the process
  435. group but **not** the cgroup, so on Linux an auto-spawned daemon lives in the cgroup of whatever
  436. shell or editor happened to start it — outside any `MemoryMax` you configured for basemind. No code
  437. in basemind can change that; a process cannot move its own children into a cgroup it does not
  438. control. If you want an enforced memory ceiling, your unit has to be the thing that starts the
  439. daemon: set `BASEMIND_NO_AUTOSPAWN=1` everywhere (basemind then connects to a running daemon but
  440. never starts one; `basemind comms start` deliberately still does) and install the ready-made user
  441. unit at [`docs/systemd/basemind-comms.service`](docs/systemd/basemind-comms.service), which also
  442. lists the two commands that verify the ceiling is real rather than merely configured.
  443. The daemon can additionally serve MCP over streamable HTTP on loopback, but that front-end is
  444. **opt-in**: it binds only when `BASEMIND_ALLOW_HTTP` is truthy in the daemon's environment, and every
  445. request must then present the bearer token published as the second line of `<comms_dir>/http.addr`
  446. (mode `0600`). Plugin manifests and the CLI use the stdio transport and need none of this.
  447. </details>
  448. <details>
  449. <summary><strong>How agents coordinate</strong></summary>
  450. A single shared service in the background lets agents talk to each other — even across different
  451. tools and different repos on the same machine. Agents coordinate in **threads** — each addressed by
  452. at least two of subject / path-glob / members, discovered by scope rather than joined globally — and
  453. each has a personal **inbox**. Messages come in two parts: a short headline (subject and sender)
  454. that's cheap to skim, and the full body, fetched only when an agent wants to read it. An agent never
  455. sees its own posts in its inbox. Idle threads auto-archive. `wait` blocks for 30 seconds by default
  456. (at most 40) and ends early when the client cancels the request.
  457. The client–daemon protocol is version 4: the daemon serves it on an 8-worker async runtime, and
  458. every request carries an id, so replies are matched to
  459. requests and most calls have a deadline (`BASEMIND_COMMS_REQUEST_TIMEOUT_SECS`, 10 s;
  460. `BASEMIND_COMMS_HANDSHAKE_TIMEOUT_SECS`, 30 s). After an upgrade, run `basemind comms stop` so the
  461. old daemon is replaced. A `post` can carry an `idempotency_key`: a retry with the same key returns the
  462. original message id instead of storing a duplicate (keys are remembered for an hour, and generated when
  463. omitted). The stdio relay replays read-only requests and keyed posts once if the daemon restarts
  464. underneath it, instead of failing the call, and fails a request that outlives
  465. `BASEMIND_RELAY_REQUEST_TIMEOUT_SECS` (180 s). Other tool responses carry a short notice when you have
  466. unread messages. A detached daemon logs to a size-rotated `<comms_dir>/daemon.log`, which
  467. `basemind comms doctor` shows.
  468. The plugin makes sure agents notice messages without being asked — through the built-in instructions,
  469. a notice at session start and each turn, and a quiet background check every few seconds.
  470. ```mermaid
  471. flowchart LR
  472. A["Agent A<br/>Claude Code · repo X"]
  473. B["Agent B<br/>Cursor · repo Y"]
  474. BR["Shared comms service<br/>threads · inboxes"]
  475. A <-->|post · read| BR
  476. B <-->|post · read| BR
  477. classDef accent fill:#2563eb,stroke:#1e40af,color:#fff
  478. class BR accent
  479. ```
  480. </details>
  481. ---
  482. ## Token saving
  483. <details>
  484. <summary><strong>Good habits the plugin sets up for you</strong></summary>
  485. The plugin nudges agents toward the cheap path by default:
  486. - Get a file's outline before opening it — then read only the part you need.
  487. - Search for a definition instead of grepping for it.
  488. - Look up who calls a function instead of grepping for call sites.
  489. - Refresh the index after edits instead of restarting the server.
  490. - Don't re-read a file basemind already mapped.
  491. A guard enforces this at the moment a tool is used: it gently redirects `grep`-style searches to the
  492. matching basemind tool. On by default; set `BASEMIND_GUARD=off` to disable, or `redirect` to block
  493. instead of nudge.
  494. </details>
  495. <details>
  496. <summary><strong>Measure it on your own repo</strong></summary>
  497. `basemind admin eval` runs a task file of lookups through the same code the MCP tools use, scores
  498. each answer against gold generated from your repository (precision/recall, hit@k, MRR, nDCG),
  499. records latency and response tokens, and compares the token cost with the grep-and-read baseline
  500. an agent would otherwise pay. Savings only count when basemind's answer was actually correct, and
  501. the report flags any eval mode whose measured ratio deviates from the dashboard's fixed multiplier.
  502. `--baseline <report.json>` turns it into a regression gate. Gold generators and the workflow are in
  503. [`benchmarks/eval/`](benchmarks/eval/README.md); measured savings, including the cases where `grep` is
  504. cheaper for a single narrow hit, are in [`benchmarks/README.md`](benchmarks/README.md#measured-results).
  505. </details>
  506. ---
  507. ## Performance
  508. <details>
  509. <summary><strong>Scan speed</strong></summary>
  510. Measured on an Apple M4 (10 cores — 4 performance + 6 efficiency, 16 GB, macOS 26) with the
  511. hardening harness (`scripts/harden.sh`), which clones each upstream repo fresh and scans its code
  512. map. Warm, steady-state numbers; the first scan of a cold project is slower.
  513. | Project | Files | Languages | Scan time |
  514. |---|---|---|---|
  515. | gin | 130 | Go | 0.1 s |
  516. | requests | 128 | Python | 0.1 s |
  517. | ripgrep | 221 | Rust | 0.6 s |
  518. | tokio | 861 | Rust | 0.4 s |
  519. | react | 7 242 | TS / JSX | 2.0 s |
  520. | django | 7 065 | Python | 2.4 s |
  521. | TypeScript compiler | 81 324 | TS / JS / JSON | 18 s |
  522. The TypeScript compiler is the worst case — 81k files in about 18 seconds. Re-scans only look at
  523. what changed, so keeping a project up to date is far faster than the first scan.
  524. Once running, code questions answer from memory rather than from disk each time — in milliseconds
  525. even on a very large repository (next section).
  526. </details>
  527. <details>
  528. <summary><strong>Query latency and accuracy on a large monorepo</strong></summary>
  529. Measured with the built-in harness (`basemind admin eval --warmup`, see
  530. [Measure it on your own repo](#token-saving)) on a 74k-file, ~350 MB monorepo checkout, 60 tasks per
  531. eval mode, in-process (no transport or process start-up). Gold is generated from the repository
  532. itself; [`benchmarks/eval/README.md`](benchmarks/eval/README.md) states what each mode's gold encodes.
  533. Rows are eval modes, with the tool each one calls. The numbers predate the tool rename; the lookups
  534. behind them are unchanged.
  535. | Eval mode (tool) | p50 | p95 | precision | recall |
  536. |---|---|---|---|---|
  537. | `outline` (`code_outline`) | 1.0 ms | 2.2 ms | 1.00 | 1.00 |
  538. | `references` (`code_refs`) | 1.4 ms | 6.0 ms | 0.81 | 1.00 |
  539. | `symbols` (`code_symbols`) | 3.7 ms | 5.3 ms | 0.97 | 1.00 |
  540. | `dependents` (`code_refs`, `relation: "importers"`) | 4.0 ms | 5.6 ms | 0.84 | 1.00 |
  541. | `callers` (`code_refs` with `path`) | 4.6 ms | 10.4 ms | 0.87 | 1.00 |
  542. | `find` (`find_files`; ranked, hit@1 0.72) | 6.6 ms | 9.0 ms | 0.29 | 0.75 |
  543. | `git_search` (`git_log` with `query`; ranked, hit@1 1.00) | 55 ms | 96 ms | 1.00 | 0.91 |
  544. | `docs` (`docs_search`; hit@1 0.48, hit@5 0.63) | 106 ms | 260 ms | 0.18 | 0.63 |
  545. | `grep` (`code_grep` with `regex: true`; 15 tasks, trigram prefilter) | ~130 ms | 190–270 ms | 0.91 | 1.00 |
  546. `code_symbols` and the importer lookup answer from a resident term index, and call-site, caller and
  547. implementation lookups from a resident dictionary of distinct callee and trait names, which is why
  548. they sit in the millisecond range instead of walking every call site. `code_grep` skips files a per-file
  549. trigram bloom filter proves cannot match (index cost ≈ 12.8 % of the indexed code bytes; results are
  550. identical to the full sweep, which took 3.6–7.8 s p50 on the same tasks; see
  551. [ADR-0012](docs/adr/0012-grep-content-prefilter.md)). Set `BASEMIND_GREP_BLOOM=0` to force the full
  552. sweep. Numbers vary with hardware and load; rerun the harness on your repository.
  553. </details>
  554. <details>
  555. <summary><strong>Git history queries</strong></summary>
  556. basemind precomputes a per-repo git-history index (path → commit posting lists, stored newest-first)
  557. so the history lookups — `git_log` with no filter, with `path`, and the commit walk behind `path` +
  558. `symbol`, plus the CLI's `git churn` and `git by-path` — are posting-list lookups. Warm in-process query latency on the same M4:
  559. | Repo | Commits | `git_log {path}` | `git_log {}` | index build | index size |
  560. |---|---|---|---|---|---|
  561. | django | 2 000 | 39 µs | 15 µs | 0.5 s | 1.7 MB (6 % of `.git`) |
  562. | tokio | 3 984 | 37 µs | 13 µs | 0.9 s | 2.1 MB (12 %) |
  563. | requests | 6 480 | 38 µs | 15 µs | 1.0 s | 1.9 MB (14 %) |
  564. | TypeScript | 2 000 | 37 µs | 13 µs | 3.2 s | 30 MB (12 %) |
  565. History queries answer in **tens of microseconds**, flat across history depth, because the
  566. newest-first posting lists decode only the commits a query returns. The index builds in well under a
  567. second to a few seconds and costs **6–22 % of `.git`** on disk.
  568. It is a pure accelerator: the tools use it only when it is fresh (`last_indexed_head == HEAD`) and
  569. otherwise walk history directly, so it can never serve stale results — and it rebuilds automatically
  570. when history is rewritten (filter-repo / rebase / force-push). Reproduce with
  571. `cargo bench --bench git_history` or the git-ops block in `scripts/harden.sh`.
  572. </details>
  573. <details>
  574. <summary><strong>Measuring query latency (<code>elapsed_us</code>)</strong></summary>
  575. Every latency-relevant tool — the code, git, document and memory lookups and `index_status` —
  576. reports its own latency as **`elapsed_us`** on its response.
  577. Don't wrap the CLI in `time`; ask basemind.
  578. Resolution is **microseconds** on purpose: an indexed `git_log` with `path` is ~37 µs, so
  579. millisecond granularity would round the hot path to `0`.
  580. **What `elapsed_us` includes** — the tool body's own execution: index and store lookups, git walks,
  581. ranking, and building the response.
  582. **What it excludes** — MCP / JSON-RPC transport (which the server cannot observe), argument
  583. deserialization, and serialization of the response itself. Excluding encoding keeps the number
  584. comparable across result-set sizes: it reports *query* cost, not *encoding* cost.
  585. **The one caveat, stated plainly:** most read tools begin by awaiting the in-RAM code map, and the
  586. git tools lazily build their history index on first use. Both waits happen *inside* the measured
  587. region, so a first call against a cold server is much slower than the steady-state call after it.
  588. When the server is still warming or building, the response carries a `notice`
  589. (`warming_up` / `building_index` / `rescanning`) — **discard any sample carrying a `notice`** if you
  590. are measuring steady-state latency.
  591. The CLI adds a second number, `startup_us`, covering process startup: clap parsing, the tokio runtime,
  592. the store open, and the config/git-cache load. It is reported separately because it is exactly the
  593. part of a `time basemind …` measurement that was never the query — and a long-running MCP server pays
  594. it once at boot, not per call:
  595. ```console
  596. $ basemind code symbols run_workspace_grep --limit 1 --json
  597. {
  598. ...
  599. "elapsed_us": 90, # the query
  600. "startup_us": 957887 # everything else a `time` wrapper would have charged to it
  601. }
  602. $ basemind code refs parse_kind --limit 3
  603. ...
  604. (6.5 ms query · 852.9 ms startup) # stderr: stdout carries only the answer
  605. ```
  606. That first example is the whole point: the query took 90 µs, while the process spent ~0.96 s getting
  607. ready to run it. A `time basemind …` wrapper would have reported the second number and told you
  608. nothing about the first.
  609. </details>
  610. ---
  611. ## Configuration
  612. <details>
  613. <summary><strong>Config file &amp; overrides</strong></summary>
  614. The config lives at the **repo root** as `basemind.toml` (committed). The cache it drives is derived
  615. state — held in the global cache under the XDG data directory, wiped and rebuilt on schema bumps —
  616. so config never belongs there and nothing basemind-owned is written into your repo. Run
  617. `basemind init` to drop a fully-commented scaffold (documenting every option) at the root. It can
  618. also live under the project-level [`.config/` convention](https://github.com/pi0/config-dir) —
  619. `.config/basemind.toml` or `.config/basemind/config.toml` — which is auto-discovered read-only; the
  620. root `basemind.toml` still wins when both exist. `basemind init --config-dir .config` (or
  621. `--config-dir .config/basemind`) scaffolds the convention. The legacy in-cache path
  622. (`.basemind/basemind.toml`, from before the global-cache move) is still read as a fallback for older
  623. checkouts. The full schema is at `schema/basemind-config-v1.schema.json`:
  624. ```toml
  625. # basemind.toml (repo root — commit this)
  626. "$schema" = "v1"
  627. [scan]
  628. respect_gitignore = true
  629. # Follow symlinks during the walk. Off by default — symlinks often escape the repo (e.g. Bazel's
  630. # bazel-* convenience symlinks). Turn on for repos that symlink real source into place. Ignored
  631. # (forced false) in a repository's own file unless the operator sets BASEMIND_ALLOW_FOLLOW_SYMLINKS=1.
  632. follow_symlinks = false
  633. # Glob syntax (include / exclude here, and every include / exclude / embed_* list below): paths are
  634. # repo-relative with forward slashes, matching is case-sensitive, and `*` also crosses `/` (so
  635. # `src/*.rs` matches `src/a/b.rs`). A pattern with no glob characters is gitignore-like: `generated`
  636. # matches every path segment of that name at any depth and everything beneath it; `docs/api` is
  637. # anchored at the root. Exclude beats include. An invalid glob, a negated (`!`) pattern, or an empty
  638. # `include` (it would index nothing) is a config error. For `extra_roots` files the globs are
  639. # matched against the path relative to that root.
  640. include = ["**/*"]
  641. # `exclude` is ADDED ON TOP of an always-on floor (node_modules, target, dist, build, out, .venv,
  642. # venv, __pycache__, *.pyc, .pytest_cache/.mypy_cache/.ruff_cache/.tox, .next/.nuxt/.svelte-kit,
  643. # vendor, .gradle, .terraform, coverage, bazel-*, .git, .basemind, .idea, .DS_Store) and of a
  644. # credential floor, so a secret never becomes searchable by every agent that can query the index:
  645. # .env and .env.*, .aws/, .ssh/, .gnupg/, .npmrc, .pypirc, .netrc, .git-credentials, id_rsa /
  646. # id_dsa / id_ecdsa / id_ed25519, *.pem, *.key, *.p12, *.pfx, *.jks, *.keystore. Note `.env.*` also
  647. # drops `.env.example`; list `.env.*` in floor_allow to index those templates (needs the
  648. # BASEMIND_ALLOW_REPO_CREDENTIALS grant below).
  649. exclude = []
  650. # Remove entries from that floor so the tree is indexed, by directory name (`build`), file name or
  651. # glob (`.env.*`, `*.pem`) or floor pattern (`**/build/**`). `.git` and `.basemind` can never be
  652. # allowed; an entry naming nothing is ignored with a warning. A credential entry (`.env`, `*.pem`,
  653. # keys) is honoured only with BASEMIND_ALLOW_REPO_CREDENTIALS=1 in the environment — a repository's
  654. # own file cannot un-exclude your secrets. The default `exclude` separately lists
  655. # dist/target/node_modules/.venv/bazel-*, so drop those from `exclude` too when allowing them.
  656. floor_allow = []
  657. # Index directories outside the repo root too — e.g. a Bazel external repo cache — so their
  658. # symbols resolve in search / references / outlines. External files are keyed by absolute path;
  659. # (re-)indexed on a full `basemind scan` only (not live-watched). Requires the operator to set
  660. # BASEMIND_ALLOW_EXTRA_ROOTS in the environment: this file lives inside the repository, so
  661. # without that opt-in a cloned repo could point basemind at your ~/.ssh. Even with the grant, a root
  662. # under .ssh / .aws / .gnupg or /etc, a filesystem root, and a root inside the repo are skipped.
  663. # Extra roots count toward max_candidates and follow symlinks only when follow_symlinks is on.
  664. extra_roots = ["/private/var/tmp/_bazel_you/abc123/external"]
  665. # Ceiling on how many candidate files one scan may keep, across the repo walk and every extra root.
  666. # Exceeding it aborts before any extraction or index write, and the error names the heaviest
  667. # contributing directories — so a vendored tree that slipped past .gitignore is a one-line fix
  668. # instead of an out-of-memory kill. It also bounds how far the walk may travel to find them. It does
  669. # NOT bound bytes read or index size, and does not apply to `--staged` / `--rev` (those enumerate
  670. # from git, not from a walk). 0 disables both bounds.
  671. max_candidates = 500_000
  672. # Per-grammar overrides, keyed by tree-sitter-language-pack grammar name (see `basemind lang list`;
  673. # an unknown key is a config error that suggests near matches).
  674. [languages.vimdoc]
  675. # false stops parsing that grammar's files as code (fixes misdetections: `.txt` is vimdoc, `.conf`
  676. # is nginx). They are then handled like any unrecognised file: routed to the document tier, where
  677. # `[documents] exclude` can drop them entirely. Already-indexed files are removed on the next scan.
  678. enabled = false
  679. [languages.jinja2]
  680. # Map extra suffixes (leading dot optional, case-insensitive, compound allowed) and exact file
  681. # names onto the grammar. Overrides beat built-in detection; a filename beats an extension.
  682. extensions = [".mako", ".tpl"]
  683. filenames = ["BUILD.in"]
  684. # `basemind lang install` also fetches this grammar (otherwise only the languages basemind ships
  685. # queries for are pre-fetched and the rest download on first use).
  686. preload = true
  687. [code_intel]
  688. # Precise, scope- and import-aware resolution (JS/TS via oxc; Python/Java via stack-graphs). On by
  689. # default. Set false to fall back to fast tree-sitter locals binding for every language. Applies to
  690. # files (re)scanned after the change.
  691. precise_resolution = true
  692. [documents]
  693. enabled = true
  694. # Embed documents for semantic search (ON — embeddings pay off on real prose / OCR).
  695. embed = true
  696. # Model preset: fast | balanced (default, 768-dim) | quality | multilingual.
  697. # Changing the preset forces a FULL RE-EMBED of the corpus (time + CPU): every document is
  698. # re-encoded at the new model's dimension.
  699. embedding_preset = "balanced"
  700. # Which non-code files become documents. Prose, data and config files (markdown, rst, json, yaml,
  701. # toml, xml, csv, ini, ...) are NOT in the code map; they are documents and are gated here. Default
  702. # (empty include) is everything that passes [scan]; exclude applies to document indexing itself and
  703. # beats include (same glob syntax as [scan]).
  704. # The default `exclude` drops low-value bulk: SVG icon/vector assets, lockfiles and test-data
  705. # directories (removing an entry re-indexes it). Setting the key REPLACES that list (it is not
  706. # merged): `exclude = []` indexes all of them, and a custom list must repeat any default entry you
  707. # still want.
  708. include = []
  709. exclude = [
  710. "*.svg", "pnpm-lock.yaml", "package-lock.json", "yarn.lock", "Cargo.lock", "poetry.lock", "*.lock",
  711. "**/test_data/**", "**/testdata/**", "**/fixtures/**", "**/__snapshots__/**",
  712. ]
  713. # Per-document size cap in bytes, independent of [scan] max_file_bytes (which caps source files), so
  714. # large PDFs / Office files are still extracted. Files over it are skipped and counted as too large
  715. # in the scan summary.
  716. max_file_bytes = 52428800
  717. # Backstop against pathological chunking cost: structured data (json, yaml, xml, svg, csv) is always
  718. # chunked linearly, and other text-like documents over these sizes (bytes, minimum
  719. # 1024) are chunked by a linear fixed-size chunker instead and counted as `docs_degraded` in the scan summary.
  720. # PDFs / Office files are never affected. text/plain (.txt, .log) has no markup to exploit, so its
  721. # cutover is lower.
  722. # A text-like file that xberg rejects (Helm template named .yaml, huge CSV, SVG with a huge entity) is also read as
  723. # text/plain through this chunker and counted as `docs_text_fallback`.
  724. markdown_chunk_max_bytes = 1048576
  725. plain_text_chunk_max_bytes = 4194304
  726. # Wall-clock budget (seconds) for one document's extraction + chunking. A document that overruns is
  727. # abandoned, skipped, and counted as `doc_timeouts`. It is remembered by content hash and not retried
  728. # while the file and these limits (this value, the two cutovers above, max_pages) are unchanged; editing
  729. # the file or changing a limit retries it.
  730. extraction_timeout_secs = 120
  731. # Wall-clock budget (seconds) for the whole document phase of one scan, started at the first document
  732. # that needs a real extraction (never below extraction_timeout_secs). Once spent, the remaining
  733. # documents are deferred (counted as `docs_deferred`, not failed) and picked up by the next scan.
  734. phase_budget_secs = 1800
  735. # A timed-out extraction cannot be cancelled and keeps a core busy until it finishes. At this many
  736. # still-running abandoned extractions (1 to 64), further documents are deferred instead of spawning
  737. # another thread. A soft bound; the live count shows as `abandoned_extractions` in the scan summary.
  738. max_abandoned_extractions = 4
  739. # Extra extensions to skip on top of the built-in archive/binary floor (case-insensitive; ".pdf" and
  740. # "pdf" are the same).
  741. extension_denylist = []
  742. # Embedding scope: with a non-empty embed_include only matching documents are embedded; embed_exclude
  743. # always wins. Left-out documents stay extracted + keyword-searchable. Editing either (or `embed`)
  744. # deletes the vector rows of documents that stop being eligible on the next scan.
  745. embed_include = []
  746. embed_exclude = []
  747. # `extract_archives` is still accepted and ignored: archive extraction was removed, so archives
  748. # (.zip/.tar/.jar/…) are always skipped, and `true` logs a warning.
  749. [code_search]
  750. enabled = true
  751. # Vector embeddings for code are OFF by default — a general English model on code isn't worth the
  752. # cost, and NL→symbol is already served by the BM25 keyword lane. Chunking + keyword search work
  753. # regardless. Turn on only for vector search over code (downloads an ONNX model, re-embeds on
  754. # preset change).
  755. embed = false
  756. # Same semantics as the [documents] pair: allow-list, with embed_exclude winning. Files left out are
  757. # still chunked and keyword-searchable; newly ineligible files lose their vector rows on the next scan.
  758. embed_include = []
  759. embed_exclude = []
  760. # Cap on chunks indexed per source file. A generated parser table or a checked-in bundle otherwise
  761. # fans one file out into a chunk count bounded only by max_file_bytes, and every chunk costs a
  762. # keyword posting, a vector row, and (with embed on) an embed. Over-cap files are still chunked and
  763. # cached — outline and grep are unaffected — they just contribute no postings and no vector rows.
  764. max_chunks_per_file = 2000
  765. [resources]
  766. # Memory ceiling for this process, in MiB. A positive integer is an explicit ceiling; 0 or "auto"
  767. # (the default) derives one — 75% of an enforced cgroup limit, or 25% of machine RAM, floored at
  768. # 2048 MiB; "off" disables it. ADVISORY: workers park while over the ceiling and are admitted anyway
  769. # after five seconds, so it shapes peak memory rather than enforcing a hard limit (document
  770. # extraction is stricter: over the ceiling one document runs at a time). To actually cap the
  771. # daemon's memory, run it from your own resource-controlled unit — see
  772. # `docs/systemd/basemind-comms.service`.
  773. max_footprint_mb = "auto"
  774. # Byte budget (MiB) for the MCP read stack's decoded-outline cache, per workspace. 0 = unbounded.
  775. # A miss costs one blob read and never changes an answer.
  776. max_map_cache_mb = 256
  777. # ONNX Runtime execution provider for embeddings, reranking and NER: cpu (default)
  778. # | auto | coreml | cuda | tensorrt. `auto` restores the platform default (CoreML on macOS), which
  779. # measured 7.6 GB resident for one tiny document against 0.8 GB on cpu.
  780. onnx_provider = "cpu"
  781. ```
  782. **Overrides.** Only the `documents.*` keys can be overridden, by a CLI flag or its
  783. environment variable (each flag's name is in `--help`; the variable is the flag upper-cased with a
  784. `BASEMIND_` prefix and underscores, e.g. `--documents-overlap` is `BASEMIND_DOCUMENTS_OVERLAP`).
  785. The `--llm-*` flags and `BASEMIND_LLM_*` variables are still accepted and ignored (see Deprecated
  786. keys below). Every other setting is file-only. Overrides apply to the CLI
  787. command they are passed to (the MCP tools do not accept them); a daemon-hosted scan or read
  788. stack loads only the file (plus the daemon caps below), so set those keys in `basemind.toml` for
  789. daemon workloads. Overrides are validated after merging, so an override cannot smuggle in a value
  790. the file would be rejected for (`documents.max_characters` under 64, `overlap >= max_characters`,
  791. `language.min_confidence` outside 0..1).
  792. **Trust boundary.** `basemind.toml` is authored by the repository, not by you, so settings that
  793. reach outside the process are gated on the operator's environment:
  794. | Setting in the repo's file | Honoured only when |
  795. |---|---|
  796. | `[scan] follow_symlinks = true` | `BASEMIND_ALLOW_FOLLOW_SYMLINKS=1`; otherwise reset to `false` with a warning (a tracked link can point at `~/.ssh`). |
  797. | `[scan] floor_allow` (a credential entry: `.env`, `*.pem`, `id_rsa`, ...) | `BASEMIND_ALLOW_REPO_CREDENTIALS=1`; otherwise the entry is ignored with a warning and the secret stays excluded (a clone could otherwise un-exclude your untracked `.env` and have every agent query it). Entries for build artifacts (`build`, `vendor`) need no grant. |
  798. | `[scan] extra_roots` | `BASEMIND_ALLOW_EXTRA_ROOTS=1` (every workspace this process scans) or a list of absolute workspace roots separated by `:` (`;` on Windows), which grants only those workspaces and their descendants. A relative entry is ignored with a warning, as is any other non-truthy word (`on`). A daemon is one long-lived process serving many repositories, so prefer the list form there: the bare `1` also opens `extra_roots` for any workspace it serves later. Credential directories (`.ssh`, `.aws`, `.gnupg`, `/etc`) and filesystem roots are refused even with the grant. |
  799. Grant variables accept `1`, `true` or `yes` (case-insensitive). They are read from the process
  800. environment; the env and CLI override layers are operator-supplied and never gated.
  801. Credential and key files are not indexed by default: the exclude floor (see `[scan]` above) drops
  802. `.env`, `.env.*` (which includes `.env.example`), `.aws/`, `.ssh/`, `.gnupg/`, `.npmrc`, `.pypirc`,
  803. `.netrc`, `.git-credentials`, SSH private keys and `*.pem` / `*.key` / `*.p12` / `*.pfx` / `*.jks` /
  804. `*.keystore`. Opt a file class back in with `[scan] floor_allow = [".env.*"]` — a credential entry
  805. only takes effect with the operator's `BASEMIND_ALLOW_REPO_CREDENTIALS=1` grant, so a repository's
  806. own file cannot un-exclude it. Unless
  807. `follow_symlinks` is granted, working-tree reads (including the watcher and `rescan paths`) refuse a
  808. symlinked file or a path that resolves outside the workspace, and a `basemind.toml` that is a symlink
  809. leaving the workspace is not followed.
  810. **The daemon treats `[resources]` and `[scan] max_candidates` as ceilings.** The effective value is
  811. the smaller of the file's and the daemon's cap; the `[resources]` sentinels `0` / `"auto"` / `"off"`
  812. resolve to the cap. The operator raises a cap in the daemon's own environment (a repository cannot):
  813. | Variable | Caps | Default |
  814. |---|---|---|
  815. | `BASEMIND_DAEMON_MAX_SCAN_THREADS` | `scan_threads` | 4 |
  816. | `BASEMIND_DAEMON_MAX_EMBED_THREADS` | `embed_threads` | 4 |
  817. | `BASEMIND_DAEMON_MAX_EMBED_BATCH` | `embed_batch_size` | 8 |
  818. | `BASEMIND_DAEMON_MAX_CONCURRENT_DOCUMENTS` | `max_concurrent_documents` | 4 |
  819. | `BASEMIND_DAEMON_MAX_FOOTPRINT_MB` | `max_footprint_mb` | 3072 |
  820. | `BASEMIND_DAEMON_MAX_MAP_CACHE_MB` | `max_map_cache_mb` | 1024 |
  821. | `BASEMIND_DAEMON_MAX_CANDIDATES` | `[scan] max_candidates` | 2000000 |
  822. | `BASEMIND_DAEMON_MAX_FILE_BYTES` | `[scan] max_file_bytes` | 67108864 (64 MiB) |
  823. | `BASEMIND_DAEMON_MAX_DOCUMENT_BYTES` | `[documents] max_file_bytes` | 536870912 (512 MiB) |
  824. | `BASEMIND_DAEMON_MAX_DOCUMENT_PAGES` | `[documents] max_pages` | 5000 |
  825. | `BASEMIND_DAEMON_MAX_EXTRACTION_SECS` | `[documents] extraction_timeout_secs` | 1800 |
  826. | `BASEMIND_DAEMON_MAX_CHUNKS_PER_DOCUMENT` | `[documents] max_chunks_per_document` | 20000 |
  827. | `BASEMIND_DAEMON_MIN_DEBOUNCE_MS` | floor for `[watch] debounce_ms` (a minimum, not a ceiling) | 50 |
  828. A cap variable must be a positive integer; anything else falls back to the default.
  829. **Other operator variables.**
  830. | Variable | Effect |
  831. |---|---|
  832. | `BASEMIND_DATA_HOME` | Root of the machine-global cache (default: the XDG data directory). |
  833. | `BASEMIND_GREP_BLOOM=0` | Force `code grep` to sweep every file instead of using the per-file trigram bloom prefilter. |
  834. | `BASEMIND_BLOB_GC_GRACE_SECS` | Age (seconds) below which the blob sweep keeps a blob; default 6 hours. |
  835. | `BASEMIND_WARM_READ_STACKS` | Daemon-hosted read stacks kept warm at once; default 3. |
  836. | `BASEMIND_NO_AUTOSPAWN=1` | Connect to a running daemon but never start one. |
  837. | `BASEMIND_MAX_DAEMONS` | Ceiling on live daemons per machine before a spawn is refused; default 8. |
  838. | `BASEMIND_NO_SEED=1` | Do not seed a new worktree's index from a sibling checkout. |
  839. | `BASEMIND_BIN`, `BASEMIND_FORCE_VERSION` | Plugin launcher: run a local build / pin a release (see [Installation](#1-as-a-plugin-recommended)). |
  840. **Reload.** The daemon re-reads a workspace's `basemind.toml` on the next request after it changes
  841. (size or modification time) and logs `config changed`. A file that no longer parses keeps the last
  842. good config and logs a warning. A hosted read stack with live sessions keeps its config until they
  843. reconnect, and `scan_threads` is fixed for the process lifetime (the daemon logs that a restart is
  844. required). `admin status` reports `config_stamp` (`<bytes>B@<unix seconds>`) to spot an edit.
  845. **Reserved keys.** These parse but nothing reads them yet, and setting one to a non-default value
  846. logs a warning: `[watch] live_l2`, `[cache] file_map_lru`, `[mcp] transport`, `[memory] enabled` /
  847. `scope_strategy` / `default_visibility`, `[comms] enabled` / `idle_timeout_secs` /
  848. `max_messages_per_room` / `retention_secs` / `max_rooms` / `workspace_root`,
  849. `[documents.ocr] backend` / `languages`, and `[documents.language] preferred_languages`.
  850. **Deprecated keys.** These are still accepted so an older `basemind.toml` keeps loading, and are
  851. ignored with a one-time warning:
  852. - The `[llm]` table (`model`, `api_key`, `base_url`, `temperature`, `timeout_secs`, `max_retries`,
  853. `max_tokens`), the `--llm-*` flags on `basemind scan` and the `BASEMIND_LLM_*` variables. Nothing
  854. calls a language model any more (the reranker is a local ONNX cross-encoder), so
  855. `BASEMIND_ALLOW_REPO_LLM` has nothing to grant.
  856. - `[documents] extract_archives`: archive extraction was removed and archives are always skipped;
  857. `BASEMIND_DAEMON_ALLOW_EXTRACT_ARCHIVES` has no effect. `max_archive_bytes` /
  858. `max_archive_entries` still apply: they bound the zip containers that Office files (docx, pptx,
  859. xlsx, odt) are.
  860. - `[documents.summarization] strategy = "abstractive"`: extractive (TextRank) summaries are used.
  861. - `[documents.ner] backend = "llm"`: no entities are extracted.
  862. **Removed sections.** `[crawl]` configured web crawling and `[shells]` configured agent shells; both
  863. were removed. The tables are still accepted so an older `basemind.toml` keeps loading (`basemind
  864. init` used to write an empty `[crawl]`); their contents are not validated or read, and a table with
  865. keys in it logs one warning.
  866. **Config changes take effect on the next scan.** Cached chunks and documents carry a fingerprint of
  867. the settings that shape them (`[code_search]` `max_characters` / `overlap` / `max_chunks_per_file`;
  868. `[documents]` chunk size, page cap, language detection, keywords, NER, summarization and
  869. `[resources] document_models`), so changing one re-chunks or re-extracts only the
  870. affected files. Embedding scope (`embed`, `embed_include`, `embed_exclude`, and the `enabled` switches)
  871. is reconciled too: the first scan after a change deletes the vector rows of files that are no longer
  872. eligible (and, when `[code_search] enabled = false`, their keyword postings) and rebuilds the rows of
  873. files that became eligible from the cached blobs, without re-embedding.
  874. </details>
  875. ---
  876. ## CLI reference
  877. <details>
  878. <summary><strong>Full command list</strong> — code · git · memory · admin · cache · agents · workspace</summary>
  879. Every MCP tool has a CLI command (enforced by `tests/cli_parity/`); the CLI also keeps shorthands
  880. and administrative commands that have no MCP tool. Add `--json` for
  881. machine-readable output (the same response types the MCP tools return, including `agents` and
  882. `workspace`). Human output prints source bodies, diffs and exports in full; only table cells are cut
  883. (to 200 characters, with a note on stderr), and the timing line goes to stderr. List commands take
  884. `--limit`, `--cursor` (resume from a previous `next_cursor`) and `--max-tokens`. Line and column
  885. arguments are 1-based.
  886. <!-- markdownlint-disable MD013 -->
  887. **Exit codes**
  888. | Code | Meaning |
  889. |---|---|
  890. | `0` | Success. |
  891. | `1` | Runtime error. |
  892. | `2` | Usage error: bad flag or argument (including an invalid `rescan` path, or a destructive command without `--yes`). |
  893. | `3` | Busy: another process holds the workspace writer lock. Retry later, or use `basemind rescan`, which the daemon serves. |
  894. | `4` | A required daemon is unreachable. |
  895. | `130` | Interrupted by Ctrl-C; completed work is committed and the index stays consistent. |
  896. With a comms daemon running, the one-shot CLI forwards memory operations, reference/caller reads,
  897. the grep prefilter and rescans to it (the daemon is the sole index writer) instead of failing or
  898. degrading to a truncated in-memory view.
  899. **Code (`basemind code`)**
  900. | Command | Purpose |
  901. |---|---|
  902. | `outline <path>` | A file's structure: symbols, 1-based lines, signatures, imports (`code_outline`). |
  903. | `symbols <name> [--kind]` | Find a definition by name, optionally filtered by kind (`code_symbols`). |
  904. | `read <path> --symbol <name> [--kind]` / `read <path> --line <n> [--end-line <m>]` | One symbol's source body, or an inclusive line span (`code_read`; alias `expand`). |
  905. | `grep <pattern> [--regex --path --language --context]` | Text search; the pattern is literal unless `--regex`. `--path` is a substring of the repo-relative path (`code_grep`). |
  906. | `search <query> [--lane hybrid\|semantic\|keyword]` | Search code by meaning; returns pointers. Needs `--features code-search` (`code_search`; alias `semantic`). |
  907. | `refs <name> [--relation --path --line --column]` | Usages of a name: call sites by default, or `--relation implementations\|importers\|definition` (`code_refs`; alias `references`). |
  908. | `callers <path> <name>` | Shorthand for `refs <name> --path <path>`: callers of one specific definition. |
  909. | `implementations <name>` | Shorthand for `refs <name> --relation implementations`. |
  910. | `dependents <module>` | Shorthand for `refs <module> --relation importers`. |
  911. | `definition <path> <line> <name> [--column]` | Shorthand for `refs <name> --relation definition`: the definition a reference binds to. |
  912. | `find [query] [--path-prefix --language]` / `files [--path-prefix --language]` | Locate a file by a fuzzy fragment of its name or path, or list indexed files (`find_files`). |
  913. | `chunk <path> [--chunk-id --byte-start]` | Fetch one code chunk's source body (CLI only). |
  914. **Git (`basemind git`)**
  915. | Command | Purpose |
  916. |---|---|
  917. | `log [--path --query --author --symbol --rev]` | Commit history: recent commits, commits touching a path, full-text search, a symbol's history, or one commit in full (`git_log`). |
  918. | `blame <path> [--line --end-line --symbol --rev]` | Who last changed a file, a line span, or one symbol (`git_blame`). |
  919. | `diff [path] [--from --to --structural]` | No path: working-tree status. A path alone: its working-tree diff against HEAD. `--from`/`--to`: between revisions. `--structural`: symbols added and removed (`git_diff`). |
  920. | `status` / `recent` / `touching <path>` / `search <query> [--author]` / `show <rev>` | Shorthands for `diff` with no arguments and for `log` with one filter. |
  921. | `symbol-history <path> <name>` / `blame-symbol <path> <name> [--rev]` / `diff-outline <path> [--rev]` | Shorthands for `log --path --symbol`, `blame --symbol` and `diff --structural`. |
  922. | `churn [--window --top-k]` | The most frequently changed files (CLI only). |
  923. | `by-path <regex> [--window]` | Commits whose changed paths match a regex (CLI only). |
  924. **Memory (`basemind memory`)**
  925. | Command | Purpose |
  926. |---|---|
  927. | `put <key> <value> [--tag]... [--individual]` | Store a note (`memory_save`). |
  928. | `get <key>` / `list [--prefix --tag]` / `search <query> [--tag]` | Read one note, list by key prefix, or search by meaning (`memory_search`). |
  929. | `delete <key>` | Remove a note (CLI only). |
  930. | `documents <query> [--mime-type --keywords --entity --scope]` | Search indexed PDFs / Office / HTML / images by meaning (`docs_search`). |
  931. **Admin (`basemind admin`)**
  932. | Command | Purpose |
  933. |---|---|
  934. | `repo` | Same payload as the top-level `basemind status` (`index_status`): index health plus branch and HEAD. |
  935. | `telemetry [--window --tool]` | What's been queried and how many tokens were saved. `--window` is one of `today`, `1h`, `24h`, `all`. |
  936. | `eval --tasks <file> [--out --report --markdown --baseline --tolerance --cost-tolerance --min-recall --warmup --mode]` | Score retrieval quality and token savings against gold from a JSONL task file; `--baseline` gates regressions. See [`benchmarks/eval/`](benchmarks/eval/README.md). |
  937. | `tokens --stdin` | Count tokens in stdin with the real o200k tokenizer (needs the `tokenizer` feature). |
  938. Index commands live at the top level: `status` (`index_status`), `rescan [paths] [--full]`
  939. (`index_rescan`) and `cache stats|gc|clear` (CLI only).
  940. **Cache (`basemind cache`)**
  941. | Command | Purpose |
  942. |---|---|
  943. | `stats` | Disk footprint (per-component + total, matches `du`) and process RAM. |
  944. | `gc [--dry-run]` | Reap blobs no workspace on the machine references. Cross-workspace reference-counted, keeps blobs younger than 6 h (`BASEMIND_BLOB_GC_GRACE_SECS`), serialised by a machine-wide lock. `--dry-run` only counts the blobs in the store, plus the marker-less workspace dirs the daemon's sweep would reap, and deletes nothing. |
  945. | `clear --component <comp> [--yes]` | Clear part of the cache (`blobs`, `views`, `views:<name>`, `lance`, `git-cache`, `telemetry`, `all`; default `git-cache`). Everything but `git-cache` asks for confirmation on a terminal and needs `--yes` otherwise. `blobs` is the **machine-global** store shared by every workspace. Refuses (exit 3) while a writer holds the workspace lock, and for `blobs` while the daemon runs. |
  946. **Agents (`basemind agents`, `--features comms`)**
  947. Every command takes `--as-agent <ID>` to act as a named sub-identity.
  948. | Command | Purpose |
  949. |---|---|
  950. | `register [--name --description --version --skill]` / `list [--thread]` | Publish your identity card / list agents the broker knows. |
  951. | `thread-start [--subject --path --member]` / `thread-list [--subject-contains --include-archived]` | Start a thread (addressed by ≥2 of subject / path / members) / list threads discoverable to you. |
  952. | `join <thread>` / `leave <thread>` / `members <thread>` | Join a thread for future inbox messages, leave it, or list its members. |
  953. | `add-member <thread> <id>` / `remove-member <thread> <id>` / `archive <thread>` | Manage membership and archive a thread (creator only). |
  954. | `post <thread> <subject> [--body --reply-to --tag]` | Post a message to a thread. |
  955. | `history <thread> [--since-hours --after-seq]` / `inbox [--mark-read]` / `wait [--thread --timeout-secs]` | A thread's history / your cross-thread inbox / block until a peer posts. |
  956. | `message <id>` | Read one message body in full — the only body path. |
  957. | `ack [--message-id … \| --thread <t> --to-seq <n>]` | Clear read messages by advancing per-thread read cursors. |
  958. | `cleanup [--dry-run \| --apply] [retention overrides]` / `status` | Preview/apply retention / report lifecycle health. |
  959. In the MCP inbox and CLI JSON output, rows with the same `body_sha` and a nonzero `body_len` carry the same
  960. body. Fetch it once with `message` and reuse it across matching rows. Acknowledge each message reference
  961. after handling it so each thread's inbox cursor advances independently.
  962. **Comms daemon (`basemind comms`, `--features comms`)**
  963. | Command | Purpose |
  964. |---|---|
  965. | `daemon` / `start` / `stop [--all]` / `status` | The broker daemon: run it, ensure it, stop it (`--all` stops every live daemon on the machine), or inspect pid / version / uptime. |
  966. | `doctor [--probe --clear-fatal]` | List every live daemon on the machine (pid / comms dir / version / uptime), pruning dead registry entries, and flag a pile-up over the ceiling (`BASEMIND_MAX_DAEMONS`, default 8). `--probe` also asks each daemon whether it can serve; `--clear-fatal` acknowledges a recorded fatal store error. |
  967. **Workspace (`basemind workspace`, `--features comms`)**
  968. | Command | Purpose |
  969. |---|---|
  970. | `workspaces` / `worktrees <repo-id>` / `branches <repo-id>` | List registered workspaces / a repo's worktrees / its local branches. |
  971. | `claim <repo-id> <name>` / `release <repo-id> <name>` | Take or give up an advisory claim on a worktree (a coordination hint; enforces nothing). |
  972. **Other commands (`scan`, `serve`, `watch`, …)**
  973. | Command | Purpose |
  974. |---|---|
  975. | `scan [--staged \| --rev <REV>] [--no-git-history] [--rebuild-git-history]` | Full scan, or index the git index / one revision. Ctrl-C stops it cleanly. |
  976. | `rescan [<path>…] [--full] [--no-git-history] [--rebuild-git-history]` | Update the given paths, or the whole tree. Routed through the daemon when one runs. |
  977. | `status` | Index health for this workspace: file counts, languages, scan age. |
  978. | `doctor` | Check root, config, index, grammars, pre-commit hook and daemon; exits 1 on a failed check. |
  979. | `completions <shell>` / `man` | Print a shell completion script (`bash`, `zsh`, `fish`, `elvish`, `powershell`) / the man page (roff) to stdout. |
  980. | `watch` | Keep the index fresh as files change (no server). |
  981. | `serve` | Stdio MCP entry point: ensures the daemon and relays to it (needs `--features comms`). The daemon keeps the index fresh by default. |
  982. | `daemon ensure` | Ensure the daemon and its HTTP transport are up and print the MCP URL (needs `--features comms`). |
  983. | `statusline` | One-line summary of the daemon's active workspaces for a shell prompt; prints nothing when no daemon runs. |
  984. | `init [--config-dir .config\|.config/basemind --rules-target --settings-target --print]` | Re-runnable onboarding: write `basemind.toml` (at the root or under the `.config/` convention), select capabilities, inject usage rules. |
  985. | `lang <list\|install\|clean>` | Manage downloaded language grammars. |
  986. | `hook install [--force]` | Add a git pre-commit hook that runs `basemind scan --staged`. Honours `core.hooksPath`, works in linked worktrees, never blocks a commit, and refuses to overwrite a hook it did not write unless `--force` (the old one is kept as `pre-commit.bak`). |
  987. <!-- markdownlint-enable MD013 -->
  988. </details>
  989. ---
  990. ## License
  991. MIT — see [LICENSE](LICENSE).
  992. [tree-sitter]: https://tree-sitter.github.io/tree-sitter/
  993. [tslp]: https://github.com/Goldziher/tree-sitter-language-pack
  994. [xberg]: https://github.com/xberg-io/xberg
  995. [LanceDB]: https://github.com/lancedb/lancedb

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.