basemind

KO | EN

gitlite — search

#hacktoberfest #react #go #machine-learning #linux #docker #macos #windows #kubernetes #awesome-list #security #ios #openai #open-source

(★ 84)

Full AI context and content layer for coding agents over one MCP server — tree-sitter code-map, document RAG, shared memory, multi-agent comms, web crawl, git history + blame. 300+ languages, 10+ agent harnesses, pure Rust.

File Explorer

Download Latest Version (.zip)

- - harness-interpreter.md
  - mcp-domain-migrator.md
  - mcp-tool-author.md
  - rust-perf-engineer.md
  - scanner-extension.md
  - surface-docs-writer.md
- - check.md
  - harden.md
  - scan.md
  - serve.md
- - code-style.md
  - crate-layout.md
  - harden-harness.md
  - inverted-index.md
  - mcp-surface.md
  - poly.md
  - scanner-pipeline.md
- - agent-comms.md
  - basemind-usage.md
  - mcp-tool-conventions.md
  - module-size-cap.md
  - perf-discipline.md
  - release-versioning.md
  - schema-and-blob-compat.md
  - tdd-and-poly.md
- .generated-manifest.json
- config.toml
- marketplace.json
- plugin.json
- statusline.sh
- - bm-doctor.md
  - bm-init.md
  - bm-scan.md
  - bm-stats.md
  - bm-statusline.md
  - bm.md
- - hooks.json
  - inbox-notify
  - run-hook.cmd
  - session-start
- plugin.json
- - bm-doctor.md
  - bm-init.md
  - bm-scan.md
  - bm-stats.md
  - bm-statusline.md
  - bm.md
- - hooks.json
  - inbox-notify
  - run-hook.cmd
  - session-start
- plugin.json
- - ci.yaml
  - docs.yaml
  - publish.yaml
- - pyproject.toml
- - basemind.ts
- extract.rs
- git_history.rs
- hashing.rs
- query.rs
- bm-doctor.md
- bm-init.md
- bm-scan.md
- bm-stats.md
- bm-statusline.md
- bm.md
- - Cargo.toml
- - Cargo.toml
- - Cargo.toml
  - README.md
- - build.rs
  - Cargo.toml
- - Cargo.toml
  - LICENSE-APACHE
  - LICENSE-MIT
  - README.md
- - Cargo.toml
  - CHANGELOG.md
  - LICENSE-APACHE
  - LICENSE-MIT
  - README.md
- - AUTHORS
  - Cargo.toml
  - CHANGELOG.md
  - LICENSE-APACHE
  - LICENSE-MIT
  - README.md
- - Cargo.toml
  - CHANGELOG.md
  - LICENSE-APACHE
  - LICENSE-MIT
  - README.md
- - 0000-record-architecture-decisions.md
  - 0000-template.md
  - 0001-unified-typed-code-graph.md
  - 0002-edge-provenance-and-confidence.md
  - 0003-graph-traversal-tools.md
  - 0004-community-detection.md
  - 0005-rendering-engine.md
  - 0006-interactive-ui-tauri.md
  - 0007-agent-launchable-display-tool.md
  - 0008-documents-code-graph.md
  - 0009-rationale-decision-nodes.md
  - 0010-branch-integration-release-strategy.md
  - 0011-mcp-tool-surface-redesign.md
  - README.md
- - code-review-panel.gif
- - basemind-banner.svg
  - basemind-social.png
  - demo.cast
  - demo.gif
  - mcp-demo.gif
  - MCP_DEMO.md
  - README.md
  - semantic-demo.gif
- ARCHITECTURE.md
- compress-output
- hooks.json
- inbox-notify
- pre-tool-guard
- read-cache
- run-hook.cmd
- session-start
- - basemind.js
- index.js
- install.js
- package.json
- README.md
- - bm-doctor.md
  - bm-init.md
  - bm-scan.md
  - bm-stats.md
  - bm-statusline.md
  - bm.md
- basemind.js
- package.json
- README.md
- - __init__.py
  - cli.py
  - downloader.py
- - test_downloader_platform.py
- pyproject.toml
- README.md
- - hermes.py
- - test_hermes_register.py
- README.md
- basemind-config-v1.schema.json
- README.md
- bench.sh
- codex-mcp-launch.mjs
- demo-record.sh
- demo.sh
- glibc228_compat.c
- harden.sh
- mcp-launch.sh
- package-release.sh
- release-bump.sh
- release-dry-run.sh
- sync-plugin-skills.sh
- sync-to-codex-plugin.sh
- update-homebrew-formula.sh
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - admin.rs
  - agents.rs
  - code.rs
  - comms_daemon.rs
  - context.rs
  - git.rs
  - graph.rs
  - init.rs
  - init_rules.rs
  - memory.rs
  - mod.rs
  - registry.rs
  - render.rs
  - shell.rs
  - web.rs
- - client.rs
  - client_forward.rs
  - code_search_proto.rs
  - cursor.rs
  - daemon.rs
  - daemon_cleanup_tests.rs
  - daemon_forward_handlers.rs
  - daemon_forward_tests.rs
  - daemon_guards.rs
  - daemon_handlers.rs
  - daemon_http.rs
  - daemon_lifecycle.rs
  - daemon_lifecycle_tests.rs
  - daemon_maintenance_tests.rs
  - daemon_response.rs
  - daemon_tests.rs
  - daemon_threads.rs
  - frontend_inproc.rs
  - frontend_named_pipe.rs
  - frontend_uds.rs
  - git_history_ops.rs
  - http_frontend.rs
  - identity.rs
  - ids.rs
  - keys.rs
  - memory_proto.rs
  - mod.rs
  - model.rs
  - proposals_proto.rs
  - protocol.rs
  - relay.rs
  - resolved_proto.rs
  - scope.rs
  - singleton.rs
  - store.rs
  - store_tests.rs
  - transport.rs
  - workspace_pool.rs
  - workspace_pool_tests.rs
- - code.rs
  - comms.rs
  - documents.rs
  - layered.rs
  - mod.rs
  - overrides.rs
  - resources.rs
  - shells.rs
  - source.rs
  - v1.rs
  - validate.rs
- - doc.rs
  - l1.rs
  - l2.rs
  - l3.rs
  - locals.rs
  - mod.rs
  - rationale.rs
- - commit.rs
  - mod.rs
  - remote.rs
  - worktree.rs
- - builder.rs
  - encoding.rs
  - fts.rs
  - keys.rs
  - mod.rs
  - proto.rs
  - reader.rs
  - remote.rs
- - keys.rs
  - keys_governance.rs
  - mod.rs
  - writer.rs
- - js.rs
  - mod.rs
  - model.rs
  - resolve.rs
  - resolve_pass.rs
  - resolver.rs
  - stackgraph.rs
  - xfile.rs
- - doc_links.rs
  - mod.rs
  - schema.rs
- - admission.rs
  - agent_api.rs
  - background.rs
  - budget.rs
  - codegraph.rs
  - codegraph_tests.rs
  - community.rs
  - completions.rs
  - cursor.rs
  - daemon_forward.rs
  - doc_links_cache.rs
  - file_url.rs
  - graph_html.rs
  - graph_svg.rs
  - graph_view.rs
  - helpers.rs
  - helpers_admin.rs
  - helpers_archmap.rs
  - helpers_calls.rs
  - helpers_calls_scan.rs
  - helpers_code.rs
  - helpers_code_search.rs
  - helpers_comms.rs
  - helpers_community.rs
  - helpers_compress.rs
  - helpers_documents.rs
  - helpers_files.rs
  - helpers_fingerprint.rs
  - helpers_git.rs
  - helpers_git_file.rs
  - helpers_governance.rs
  - helpers_graph.rs
  - helpers_graphview.rs
  - helpers_grep.rs
  - helpers_impls.rs
  - helpers_intel.rs
  - helpers_memory.rs
  - helpers_proposals.rs
  - helpers_registry.rs
  - helpers_shells.rs
  - helpers_telemetry.rs
  - helpers_traverse.rs
  - helpers_web.rs
  - host.rs
  - identity.rs
  - in_memory.rs
  - kneedle.rs
  - lazy_cache_tests.rs
  - lean.rs
  - lenient.rs
  - map_fingerprint.rs
  - memory.rs
  - memory_ops.rs
  - mod.rs
  - mode.rs
  - notifications.rs
  - prompts.rs
  - proposals_ops.rs
  - router_cache.rs
  - savings.rs
  - server_handler.rs
  - shared_state.rs
  - state.rs
  - tasks.rs
  - telemetry.rs
  - tokens.rs
  - tools.rs
  - tools_admin.rs
  - tools_comms.rs
  - tools_git.rs
  - tools_graph.rs
  - tools_memory.rs
  - tools_registry.rs
  - tools_shells.rs
  - tools_web.rs
  - toon.rs
  - traverse.rs
  - types.rs
  - types_admin.rs
  - types_archmap.rs
  - types_code.rs
  - types_comms.rs
  - types_community.rs
  - types_compress.rs
  - types_documents.rs
  - types_git.rs
  - types_governance.rs
  - types_graph.rs
  - types_graphview.rs
  - types_impls.rs
  - types_memory.rs
  - types_registry.rs
  - types_shells.rs
  - types_traverse.rs
  - types_web.rs
- - go-locals.scm
  - go.scm
  - javascript.scm
  - markdown.scm
  - python-locals.scm
  - python.scm
  - rust.scm
  - tsx-locals.scm
  - tsx.scm
  - typescript-locals.scm
  - typescript.scm
- - mod.rs
  - tests.rs
- - bm25.rs
  - exact.rs
  - mod.rs
  - rrf.rs
- - attach.rs
  - daemon.rs
  - launcher.rs
  - mod.rs
  - session.rs
- - checkpoint.rs
  - cli.rs
  - delta.rs
  - detect.rs
  - handlers.rs
  - mod.rs
  - safety.rs
  - waste.rs
- - engine.rs
  - ingest.rs
  - mod.rs
- agent_cmd.rs
- backpressure.rs
- chunk.rs
- comms_cli.rs
- daemon_lock.rs
- embeddings.rs
- git_cache.rs
- hashing.rs
- lang.rs
- lang_cli.rs
- lib.rs
- main.rs
- path.rs
- query.rs
- render.rs
- scanner.rs
- scanner_code.rs
- scanner_doc_links.rs
- scanner_docs.rs
- scanner_docs_security_tests.rs
- scanner_file.rs
- scanner_filter.rs
- scanner_lanes.rs
- stdio_relay.rs
- store.rs
- store_blob.rs
- store_blob_codec.rs
- store_cache_admin.rs
- store_gc.rs
- store_gc_budget.rs
- store_gc_workspace.rs
- store_layout.rs
- store_lock.rs
- sysres.rs
- ui_cmd.rs
- url.rs
- version.rs
- watcher.rs
- agent_identity_smoke.rs
- bug_13_cli.rs
- bug_18_cli.rs
- bug_20_cli.rs
- bug_22_cli.rs
- bug_23_git_cache.rs
- bug_24_cli.rs
- bug_44_reembed_loop.rs
- bug_git.rs
- cache_paths.rs
- cli_parity.rs
- cli_smoke.rs
- code_intel_smoke.rs
- code_search_smoke.rs
- comms_cli_smoke.rs
- comms_idle_reap.rs
- comms_smoke.rs
- concurrency_smoke.rs
- config_root_smoke.rs
- config_schema.rs
- daemon_integration.rs
- daemon_singleton_smoke.rs
- dependency_security.rs
- embed_streaming_smoke.rs
- extra_roots_smoke.rs
- find_callers_resolved_smoke.rs
- git_cache_smoke.rs
- git_history_cli.rs
- git_history_daemon.rs
- git_history_serve.rs
- git_history_share_smoke.rs
- git_history_smoke.rs
- git_parity.rs
- git_smoke.rs
- goto_definition_xfile_smoke.rs
- governance_smoke.rs
- harden.rs
- http_frontend_smoke.rs
- incremental_resolve_smoke.rs
- incremental_scope_resolve_smoke.rs
- init_smoke.rs
- lang_fallback_smoke.rs
- max_lines.rs
- mcp_schema_wire.rs
- mcp_smoke.rs
- multisession_smoke.rs
- plugin_manifest_smoke.rs
- precise_resolution_smoke.rs
- property_smoke.rs
- publish_workflow_smoke.rs
- registry_prune_smoke.rs
- root_discovery_smoke.rs
- scan_durability_smoke.rs
- scan_smoke.rs
- schema_bump.rs
- serve_contention_smoke.rs
- serve_relay_smoke.rs
- shells_smoke.rs
- stackgraph_smoke.rs
- statusline_smoke.sh
- tasks_smoke.rs
- web_smoke.rs
- worktree_smoke.rs
- - extensions.json
  - launch.json
- - apple-touch-icon.png
  - CNAME
  - favicon-32.png
  - favicon.svg
  - og.png
  - robots.txt
- - content.config.ts
- .gitignore
- astro.config.mjs
- package-lock.json
- package.json
- README.md
- tsconfig.json
.ai-rulez-generated.json
.gitignore
.mcp.json
ATTRIBUTIONS.md
basemind.toml
buf.lock
build.rs
Cargo.lock
Cargo.toml
CHANGELOG.md
CONTRIBUTING.md
deny.toml
gemini-extension.json
kimi.plugin.json
LICENSE
llms.txt
package.json
poly-hooks.lock
poly.toml
README.md
rustfmt.toml
settings.json
Taskfile.yaml

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">

**The context and communication layer for coding agents.**

basemind turns any repo into an always-current map of its code, documents, history, and memory —
so agents answer from **structure and search** instead of burning their context window on `grep` and
file reads — and gives a team of agents a **shared channel to coordinate** while they work. One
server does both.

Code map across **300+ languages** · documents in **90+ formats** · semantic + full-text search ·
git history & blame · shared memory · web crawl · agent-to-agent comms

[![Docs](https://img.shields.io/badge/docs-basemind.ai-965aff?style=flat-square)](https://basemind.ai)
[![crates.io](https://img.shields.io/crates/v/basemind?style=flat-square)](https://crates.io/crates/basemind)
[![npm](https://img.shields.io/npm/v/basemind?style=flat-square)](https://www.npmjs.com/package/basemind)
[![PyPI](https://img.shields.io/pypi/v/basemind?style=flat-square)](https://pypi.org/project/basemind/)
[![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)
[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](https://raw.githubusercontent.com/Goldziher/basemind/main/LICENSE)

[Docs](https://basemind.ai) · [Install](#installation) · [Features](#what-you-get) · [How it works](#how-it-works) · [Performance](#performance) · [CLI](#cli-reference)

</div>

---

<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">
An agent reasoning from structure — <code>code</code> modes <code>outline</code> and <code>references</code> in a live session, statusline tracking tokens saved.

<div align="center"><a href="#demos">More demos ↓</a></div>

---

## 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](#how-it-works)), 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](#how-it-works). | `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 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`) |
| **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](#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.

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

In the session (not your shell), run in order:

```text
/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 latest *published* release, so you always get the current index format and
tool set and startup stays reliable even during a release. Prefer to control timing? Update the
marketplace regularly by hand instead.

</details>

<details>
<summary>Codex</summary>

```bash
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 plugin starts the latest published GitHub release from the project workspace; it never runs from
the installed plugin cache or races a shared `npx` install.

</details>

<details>
<summary>Cursor</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>Gemini CLI</summary>

```bash
gemini extensions install https://github.com/Goldziher/basemind
```

Update later with `gemini extensions update basemind`.

</details>

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

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

</details>

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

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

</details>

<details>
<summary>OpenCode</summary>

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

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

</details>

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

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

</details>

<details>
<summary>Hermes</summary>

Hermes exposes MCP servers through config, so basemind's tools are wired there. Two steps — the
binary + MCP wiring gives you the tools; a small standalone plugin package adds the helper skills,
slash commands, and comms notifications.

First [install the program](#install-the-program) (Homebrew / npm / cargo / release — **not** pip),
then add the server to `~/.hermes/config.yaml` (this is what gives you the nine domain tools):

```yaml
mcp_servers:
  basemind:
    command: basemind
    args: [serve]
```

For the helper skills, slash commands, and agent-comms notifications, install the standalone plugin
into the same Python environment Hermes runs in, then enable it (general plugins are opt-in):

```bash
pip install basemind-hermes-plugin
hermes plugins enable basemind
```

The plugin is pure-Python and ships no binary — it shells out to the `basemind` you installed above.
Comms auto-notifications are best-effort; the chat tools work regardless.

</details>

<details>
<summary>Antigravity &amp; pi</summary>

**Antigravity** uses a shared MCP config — [install the program](#install-the-program), then add the
[generic MCP block](#2-as-an-mcp-server). If you already use the Gemini extension,
`agy plugin import gemini` brings it across.

**pi**: `pi install git:github.com/Goldziher/basemind`. pi has no MCP support, so basemind runs
through its [CLI](#3-as-a-cli) here.

</details>

### 2. As an MCP server

If your tool speaks MCP but you're not using the plugin, [install the program](#install-the-program),
then register it:

```json
{
  "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`.

<details>
<summary>Per-tool specifics (Claude Code · Cursor · Windsurf · Codex · Gemini · Copilot · Droid · Cline · Continue · OpenCode · Hermes)</summary>

- **Claude Code** — `claude mcp add basemind -- basemind serve` (add `--scope user` for all
  projects; the `--` is required). Or commit a `.mcp.json` at the repo root with the block above.
- **Cursor** — put the block above in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
- **Windsurf** — `~/.codeium/windsurf/mcp_config.json` (or Cascade → MCP servers → manage), then
  **Refresh**.
- **Codex** — `codex mcp add basemind -- basemind serve`, shared by the CLI and IDE.
- **Gemini CLI** — `gemini mcp add basemind basemind serve`, or the block above in
  `~/.gemini/settings.json`.
- **GitHub Copilot CLI** — `/mcp add` in-session, or `~/.copilot/mcp-config.json` with
  `"type": "local"` and `"tools": ["*"]`.
- **Factory Droid** — `droid mcp add basemind "basemind serve"`, or `~/.factory/mcp.json`.
- **Cline** — MCP Servers icon → Configure → add the block above.
- **Continue** — `.continue/mcpServers/basemind.yaml` with `command: basemind`, `args: [serve]`.
- **OpenCode (without the plugin)** — `opencode.json` under key `mcp`, with `command` as an array
  `["basemind", "serve"]`.
- **Hermes** — `mcp_servers.basemind` in `~/.hermes/config.yaml` (YAML: `command: basemind`,
  `args: [serve]`). For helper skills + comms notifications, `pip install basemind-hermes-plugin`
  (a standalone pure-Python plugin, no binary), then `hermes plugins enable basemind` — see the
  Hermes plugin section above.
- **Any other tool** — point it at the command `basemind` with the argument `serve`.

</details>

### 3. As a CLI

The standalone program, for scripts, headless runs, and CI. [Install it](#install-the-program), then:

```bash
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](#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](https://github.com/Goldziher/basemind/releases) | 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.toml` scaffold at the repo root, if one doesn't already exist.
- Lets you pick which capabilities to advertise (interactive prompt in a TTY, or non-interactive
 with `--yes`, `--with <capability>`, `--without <capability>`). Capability slugs:
 `code-search-navigation`, `code-mapping-architecture`, `git-history`, `agent-comms`,
 `documents-rag`, `semantic-search`.
- Injects a "prefer basemind over grep/read/git" rules block into your repo's agent-instructions
 file — `.ai-rulez/rules/basemind-usage.md` if `.ai-rulez/config.toml` is present (run
 `ai-rulez generate` afterward), else `CLAUDE.md`, else `AGENTS.md`, else a new `CLAUDE.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 <auto|claude|agents|ai-rulez|none>`.

<details>
<summary>Statusline (Claude Code)</summary>

Run `/bm-statusline` once. This is a one-time step because Claude Code doesn't let plugins set the
main statusline themselves — so basemind asks the assistant to make the one-line settings change on
your behalf, and it sticks from then on.

It shows two lines:

```text
Opus · basemind · ⎇ main · 12% ctx
◆ basemind  ●  1,247 files · 23m ago  │  312 calls · 180 srch · 44 git · 12 docs  │  1.4M saved  │  ✉ 3 @reviewer
```

The dot is green when basemind is live and fresh, amber when idle, red when stale. The middle shows
activity by type, then tokens saved, then unread messages. Adjust with
`BASEMIND_STATUSLINE=full|compact|minimal`, or hide the top line with `BASEMIND_STATUSLINE_CONTEXT=0`.

</details>

---

## Demos

<img src="docs/media/demo.gif" alt="basemind CLI: scan, then symbol / reference / call-graph / blame queries" width="760">
The same engine from the CLI — <code>scan</code>, then symbol / reference / call-graph / blame queries.

<img src="docs/media/semantic-demo.gif" alt="Semantic search over the documents store" width="820">
Searching documents by meaning, not keywords, across 90+ formats.

<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">
Multi-agent code-review panel: named reviewers coordinate in a repo-scoped thread (post, reply, synthesize) — entirely over <code>basemind agents</code>.

---

## How it works

<details>
<summary>From one scan to instant answers</summary>

`basemind scan` reads your project once, in parallel. It maps your code with
[tree-sitter] (across [300+ languages][tslp]) and pulls text out of your documents with
[xberg], then saves the result to a global cache under the XDG data directory, keyed by workspace —
nothing is written into your repo. After that, `basemind serve` keeps the map in memory and answers
questions instantly — no re-reading the project for each one. When files change, it updates only what
changed. A single background daemon on the machine is the sole writer to that cache, so multiple
`serve` sessions on the same repo (or on different worktrees of it) all read and write concurrently
instead of one falling back read-only. See [Global cache & the daemon](#how-it-works) below.

Navigation is **scope- and import-aware** for JavaScript/TypeScript, **Python, and Java**: basemind
resolves each use to the definition it actually binds to, so a shadowed local isn't confused with an
import and `code` mode `definition` lands on the right target (including across files for imports). Every
other language still gets fast tree-sitter scope binding. Precise Python/Java resolution runs GitHub
stack-graphs-style `.tsg` name-binding rules via an in-tree engine (`crates/`), with no per-language
LSP server.

Resolution **refines, but never shrinks, a result set.** `code` mode `callers` reports every call site
whose callee matches the name — the same sound floor mode `references` uses — and marks each hit `resolved`
when resolution proved it binds to that definition (`resolved_total` counts them). It deliberately
does *not* return only the resolved subset: resolution cannot see through a module-object import
(`from pkg import mod` then `mod.f()`) or an unresolvable path alias, so filtering to it would drop
real callers and report the remainder as complete. Filter on `resolved` when you want precision; trust
`total` when you need completeness.

Markdown and Obsidian vaults are first-class: headings become navigable symbols (so `code` modes
`outline` and `symbols` work over a notes vault); `[[wikilinks]]`, `![[embeds]]`, and standard
`[text](Note.md)` links all become references — so mode `references` on `"Note"` returns that note's
backlinks regardless of link style; and `#tags` (inline or in YAML frontmatter) become references
too, so mode `references` on `"#project"` lists every note carrying that tag.

```mermaid
flowchart LR
 A(["Coding agent"])
 R["Your project code · documents · git"]
 S["basemind scan map code & read documents"]
 D[("Global cache per-OS data dir")]
 V["basemind serve answers questions"]
 R --> S --> D --> V
 A <-->|asks questions| V
 classDef accent fill:#2563eb,stroke:#1e40af,color:#fff
 class S,V accent
```

Search and memory are powered by a vector store ([LanceDB]).

</details>

<details>
<summary>Index lifecycle &amp; freshness</summary>

`basemind serve` answers the MCP handshake immediately and warms the code map into memory in the
background, so a client never blocks waiting for a large repo to load. The `status` tool reports
`warming` (still loading) and, once done, `warm_ms`; a first-time index build similarly reports
`indexing` / `index_build_ms`.

While the server isn't fully ready, `status` and every code-map read tool may carry a `notice`
object — `{ state, message, retry }` — instead of (or alongside) their normal result:

| `state` | Meaning | `retry` |
|---|---|---|
| `warming_up` | Loading an existing index into memory. | `true` |
| `building_index` | Indexing from scratch (no cache entry for this workspace yet). | `true` |
| `rescanning` | Incremental rescan after a file change; current results are usable but may be stale. | `false` |

Treat an empty or partial result carrying a `notice` as "retry shortly," not "no matches" — poll
`status` (or just retry the call) until the notice clears.

</details>

<details>
<summary>Global cache &amp; the daemon</summary>

Index state lives under a single global cache — `~/.local/share/basemind/` on Linux,
`~/Library/Application Support/basemind/` on macOS (override with `BASEMIND_DATA_HOME`) — keyed by
workspace, never inside your repo. The
content-addressed blob store is machine-wide too: identical file content scanned from different repos
or worktrees is extracted and stored once.

A single background daemon per machine is the sole writer to that cache. `basemind serve` opens its
store read-only and forwards writes (scan / rescan) to the daemon over a local socket, so N `serve`
sessions on the same repo — or on different worktrees of it — all read and write concurrently instead
of a second session silently falling back to a stale, read-only view. The daemon also keeps a cheap,
always-on registry of repos, worktrees, and branches (`workspaces` / `worktrees` / `branches`), and
`worktree_claim` / `worktree_release` give agent sessions an advisory way to avoid colliding on the
same worktree.

`basemind statusline` queries the daemon for the workspaces currently active and prints a compact
line for your shell prompt; it prints nothing when no daemon is running.

</details>

<details>
<summary>How agents coordinate</summary>

A single shared service in the background lets agents talk to each other — even across different
tools and different repos on the same machine. Agents coordinate in **threads** — each addressed by
at least two of subject / path-glob / members, discovered by scope rather than joined globally — and
each has a personal **inbox**. Messages come in two parts: a short headline (subject and sender)
that's cheap to skim, and the full body, fetched only when an agent wants to read it. An agent never
sees its own posts in its inbox. Idle threads auto-archive.

The plugin makes sure agents notice messages without being asked — through the built-in instructions,
a notice at session start and each turn, and a quiet background check every few seconds.

```mermaid
flowchart LR
 A["Agent A Claude Code · repo X"]
 B["Agent B Cursor · repo Y"]
 BR["Shared comms service threads · inboxes"]
 A <-->|post · read| BR
 B <-->|post · read| BR
 classDef accent fill:#2563eb,stroke:#1e40af,color:#fff
 class BR accent
```

</details>

<details>
<summary>Agent shells</summary>

Included in every prebuilt download (and in `cargo install --features shells` / `full`): agents can
open terminal sessions in the background, type into them, and read what's on screen — no extra tools
to install. Sessions can be fully headless, or opened in a real terminal tab or window so you can
watch along. A spawned session and the agent that started it can message each other over comms.

</details>

---

## Token saving

<details>
<summary>Good habits the plugin sets up for you</summary>

The plugin nudges agents toward the cheap path by default:

- Get a file's outline before opening it — then read only the part you need.
- Search for a definition instead of grepping for it.
- Look up who calls a function instead of grepping for call sites.
- Refresh the index after edits instead of restarting the server.
- Don't re-read a file basemind already mapped.

Optional guardrails enforce this at the moment a tool is used:

- **Guard** — gently redirects `grep`-style searches to the matching basemind tool. On by default;
  set `BASEMIND_GUARD=off` to disable, or `redirect` to block instead of nudge.
- **Output compressor** — `BASEMIND_COMPRESS_OUTPUT=1` shrinks long command output. It never touches
  anything that looks like a credential and leaves output alone if it can't help.
- **Re-read shortcut** — `BASEMIND_DELTA_READS=1` shows just what changed when an agent re-reads a
  file it already read this session.

</details>

<details>
<summary>Compression that understands code</summary>

basemind shrinks code by keeping the shape and dropping the bodies — function signatures and imports
stay, the implementations go — because a signature is useless without its shape. For prose it does a
light cleanup (extra whitespace, filler, repeated paragraphs). It reports honest before/after token
counts, and the code version is exact — nothing is lost, just set aside. `expand` brings any one
function's full body back when an agent actually needs it: compress to an outline, expand only what
you need.

</details>

---

## Performance

<details>
<summary>Scan speed</summary>

Measured on an Apple M4 (10 cores — 4 performance + 6 efficiency, 16 GB, macOS 26) with the
hardening harness (`scripts/harden.sh`), which clones each upstream repo fresh and scans its code
map. Warm, steady-state numbers; the first scan of a cold project is slower.

| Project | Files | Languages | Scan time |
|---|---|---|---|
| gin | 130 | Go | 0.1 s |
| requests | 128 | Python | 0.1 s |
| ripgrep | 221 | Rust | 0.6 s |
| tokio | 861 | Rust | 0.4 s |
| react | 7 242 | TS / JSX | 2.0 s |
| django | 7 065 | Python | 2.4 s |
| TypeScript compiler | 81 324 | TS / JS / JSON | 18 s |

The TypeScript compiler is the worst case — 81k files in about 18 seconds. Re-scans only look at
what changed, so keeping a project up to date is far faster than the first scan.

Once running, most code questions answer in **under a millisecond**, symbol and call-graph searches
in a few milliseconds, and document search in around 200 ms — because the map is held in memory
rather than read from disk each time.

</details>

<details>
<summary>Git history queries</summary>

basemind precomputes a per-repo git-history index (path → commit posting lists, stored newest-first)
so the history modes — `touching`, `recent`, `churn`, `by_path`, and `symbol_history`'s commit walk
— are posting-list lookups. Warm in-process query latency on the same M4:

| Repo | Commits | `git` `touching` | `git` `recent` | index build | index size |
|---|---|---|---|---|---|
| django | 2 000 | 39 µs | 15 µs | 0.5 s | 1.7 MB (6 % of `.git`) |
| tokio | 3 984 | 37 µs | 13 µs | 0.9 s | 2.1 MB (12 %) |
| requests | 6 480 | 38 µs | 15 µs | 1.0 s | 1.9 MB (14 %) |
| TypeScript | 2 000 | 37 µs | 13 µs | 3.2 s | 30 MB (12 %) |

History queries answer in **tens of microseconds**, flat across history depth, because the
newest-first posting lists decode only the commits a query returns. The index builds in well under a
second to a few seconds and costs **6–22 % of `.git`** on disk.

It is a pure accelerator: the tools use it only when it is fresh (`last_indexed_head == HEAD`) and
otherwise walk history directly, so it can never serve stale results — and it rebuilds automatically
when history is rewritten (filter-repo / rebase / force-push). Reproduce with
`cargo bench --bench git_history` or the git-ops block in `scripts/harden.sh`.

</details>

<details>
<summary>Measuring query latency (<code>elapsed_us</code>)</summary>

Every latency-relevant mode — all of `code` and `graph`, all of `git`, the `admin` read modes, and
the document / memory search modes — reports its own latency as **`elapsed_us`** on its response.
Don't wrap the CLI in `time`; ask basemind.

Resolution is **microseconds** on purpose: an indexed `git` mode `touching` is ~37 µs, so
millisecond granularity would round the hot path to `0`.

**What `elapsed_us` includes** — the tool body's own execution: index and store lookups, git walks,
ranking, and building the response.

**What it excludes** — MCP / JSON-RPC transport (which the server cannot observe), argument
deserialization, and serialization of the response itself. Excluding encoding keeps the number
comparable across `format: "json"` and `format: "toon"` and across result-set sizes: it reports
*query* cost, not *encoding* cost.

**The one caveat, stated plainly:** most read tools begin by awaiting the in-RAM code map, and the
git tools lazily build their history index on first use. Both waits happen *inside* the measured
region, so a first call against a cold server is much slower than the steady-state call after it.
When the server is still warming or building, the response carries a `notice`
(`warming_up` / `building_index` / `rescanning`) — **discard any sample carrying a `notice`** if you
are measuring steady-state latency.

The CLI adds a second number, `startup_us`, covering process startup: clap parsing, the tokio runtime,
the store open, and the config/git-cache load. It is reported separately because it is exactly the
part of a `time basemind …` measurement that was never the query — and a long-running MCP server pays
it once at boot, not per call:

```console
$ basemind code symbols run_workspace_grep --limit 1 --json
{
  ...
  "elapsed_us": 90,        # the query
  "startup_us": 957887     # everything else a `time` wrapper would have charged to it
}

$ basemind code references parse_kind --limit 3
...
(6.5 ms query · 852.9 ms startup)
```

That first example is the whole point: the query took 90 µs, while the process spent ~0.96 s getting
ready to run it. A `time basemind …` wrapper would have reported the second number and told you
nothing about the first.

</details>

---

## Configuration

<details>
<summary>Config file &amp; overrides</summary>

The config lives at the **repo root** as `basemind.toml` (committed). The cache it drives is derived
state — held in the global cache under the XDG data directory, wiped and rebuilt on schema bumps —
so config never belongs there and nothing basemind-owned is written into your repo. Run
`basemind init` to drop a fully-commented scaffold (documenting every option) at the root. The legacy
in-cache path (`.basemind/basemind.toml`, from before the global-cache move) is still read as a
fallback for older checkouts. The full schema is at `schema/basemind-config-v1.schema.json`:

```toml
# basemind.toml  (repo root — commit this)
"$schema" = "v1"

[scan]
respect_gitignore = true
# Follow symlinks during the walk. Off by default — symlinks often escape the repo (e.g. Bazel's
# bazel-* convenience symlinks). Turn on for repos that symlink real source into place.
follow_symlinks = false
# `exclude` is ADDED ON TOP of an always-on floor (node_modules, target, dist, build, out, .venv,
# venv, __pycache__, *.pyc, .pytest_cache/.mypy_cache/.ruff_cache/.tox, .next/.nuxt/.svelte-kit,
# vendor, .gradle, .terraform, coverage, bazel-*, .git, .basemind, .idea, .DS_Store). You can add to
# it but not remove a floor entry.
exclude = []
# Index directories outside the repo root too — e.g. a Bazel external repo cache — so their
# symbols resolve in search / references / outlines. External files are keyed by absolute path;
# (re-)indexed on a full `basemind scan` only (not live-watched). extra_roots always follow symlinks.
extra_roots = ["/private/var/tmp/_bazel_you/abc123/external"]

[code_intel]
# Precise, scope- and import-aware resolution (JS/TS via oxc; Python/Java via stack-graphs). On by
# default. Set false to fall back to fast tree-sitter locals binding for every language. Applies to
# files (re)scanned after the change.
precise_resolution = true

[documents]
enabled = true
# Embed documents for semantic search (ON — embeddings pay off on real prose / OCR).
embed = true
# Model preset: fast | balanced (default, 768-dim) | quality | multilingual.
# Changing the preset forces a FULL RE-EMBED of the corpus (time + CPU): every document is
# re-encoded at the new model's dimension.
embedding_preset = "balanced"
# Documents that are extracted + indexed but never embedded (keyword-only).
embed_exclude = []
# Route archives (.zip/.tar/.jar/…) into the recursive extractor. Off by default so one archive
# can't explode into thousands of embeds; true binaries are always skipped.
extract_archives = false

[code_search]
enabled = true
# Vector embeddings for code are OFF by default — a general English model on code isn't worth the
# cost, and NL→symbol is already served by the BM25 keyword lane. Chunking + keyword search work
# regardless. Turn on only for vector search over code (downloads an ONNX model, re-embeds on
# preset change).
embed = false
embed_exclude = []
```

Any tool call can override these settings for that one request, and settings map to environment
variables in the obvious way: `--llm-api-key` becomes `BASEMIND_LLM_API_KEY`.

</details>

---

## CLI reference

<details>
<summary>Full command list — code · graph · git · memory · admin · cache · web · agents · workspace · shell</summary>

CLI commands mirror the MCP tools 1:1 (enforced by `tests/cli_parity.rs`). Add `--json` for
machine-readable output.

**Code (`basemind code`)**

| Command | Purpose |
|---|---|
| `outline <path> [--l2]` | A file's structure: symbols, lines, signatures. `--l2` adds calls + docs. |
| `symbols <name> [--kind]` | Find a definition by name, optionally filtered by kind. |
| `grep <pattern> [--language --path-contains]` | Pattern search with filters. |
| `files [--path-contains --language]` | List indexed files. |
| `find <fragment>` | Locate a file by a fuzzy fragment of its name or path (fzf/fd-style). |
| `definition <path> <line> [--column]` | Resolve a reference position to its scope-resolved definition. |
| `references <name>` | Find everywhere a name is called. |
| `callers <path> <name> [--kind]` | Find callers of one specific definition. |
| `implementations <trait>` | Types that implement or inherit from a name. |
| `dependents <module>` | What imports a given module. |
| `expand <path> <name> [--kind]` | A symbol's raw source body (the inverse of an outline entry). |
| `semantic <query> [--limit --lane --format]` | Search code by meaning; returns pointers. Needs `--features code-search`. |
| `chunk <path> [--chunk-id --byte-start]` | Fetch one code chunk's source body (the `semantic` fetch half). |

**Graph (`basemind graph`)**

| Command | Purpose |
|---|---|
| `calls <name> [--direction --max-depth --max-nodes]` | Walk the call chain up (`callers`, default) or down (`callees`). |
| `neighbors <name> [--direction --depth --edges --max-nodes]` | A symbol's n-hop neighborhood — its blast radius before you change it. |
| `path <from> <to> [--edges --include-contains]` | Confidence-weighted shortest route between two symbols. |
| `subgraph <name> [--depth --edges --max-nodes]` | The neighborhood cut to its most central nodes — readable, not a dump. |
| `communities [--algorithm --max-communities]` | Cluster the graph into de-facto modules with deterministic labels. |
| `map [--granularity --focus --depth --edges --include-churn]` | Architecture overview: hub modules/symbols ranked by centrality + churn, plus dependency cycles (SCCs). `--edges` selects lanes (`calls`/`imports`/`inherits`/`both`/`all`); every edge carries a provenance tag (`extracted`/`inferred`/`ambiguous`) + confidence. |
| `export [--format --focus --edges --write]` | Render as node-link JSON / DOT / Mermaid / GraphML / Cypher / HTML / SVG. |
| `display [--format --no-open]` | Open a rendered view in the human's desktop viewer. `--no-open` writes the artifact and returns its path. |
| `open [--format --no-open]` | Return a live `http://…/ui` URL for the interactive graph (or a `file://` export). `--no-open` launches nothing. |

**Git (`basemind git`)**

| Command | Purpose |
|---|---|
| `status` | What's staged and unstaged right now. |
| `recent [--limit] [--no-files]` | Recent commits with their files (a recency window, not a search). |
| `search <pattern> [--field author\|message\|all] [--limit]` | Full-text search over commit history at full branch depth. |
| `touching <path>` / `by-path <pattern>` | Commits for a path or a changed-path regex. |
| `churn [--window --top-k]` | The most frequently changed files. |
| `diff <path> <old> <new>` / `diff-outline <path> [--rev]` | File or structure diff across commits. |
| `blame <path>` / `blame-symbol <path> <name>` | Who last changed each line / a symbol. |
| `symbol-history <path> <name>` | When a symbol's body changed over time. |

**Memory (`basemind memory`)**

| Command | Purpose |
|---|---|
| `put <key> <value>` / `get <key>` / `delete <key>` | Store, retrieve, or remove a value. |
| `list [--prefix]` | List keys, optionally by prefix. |
| `search <query>` | Search stored values by meaning. |
| `documents <query>` | Search indexed PDFs / Office / HTML / images by meaning. |
| `mine [--commits --min-count --min-confidence --max-files]` | Suggest notes from files that change together. |
| `proposals [--kind --limit]` | List pending suggestions. |
| `accept <id> [--key]` / `reject <id> [--reason]` | Keep a suggestion / dismiss it for good. |
| `audit [--key --individual --dry-run --include-archived]` | Recompute memory importance, archive stale entries, refresh verdicts. |

**Admin (`basemind admin`)**

| Command | Purpose |
|---|---|
| `status` / `repo` | Index health (files, languages, scan state) / git identity (branch, HEAD, origin). |
| `rescan [PATH…] [--full]` | Re-index the working tree, or only the given paths. |
| `cache-stats` / `gc` | On-disk footprint + process RAM / reclaimable-blob report. |
| `cache-clear --component <c> [--confirm]` | Clear one cache component (`views`/`all` need the offline `basemind cache clear`). |
| `telemetry [--window --tool]` | What's been queried and how many tokens were saved. |
| `compress` / `delta` / `checkpoint` / `waste` | Outline a file, diff a re-read, summarize a session, flag wasteful tool use. |

**Cache (`basemind cache`)**

| Command | Purpose |
|---|---|
| `stats` | Disk footprint (per-component + total, matches `du`) and process RAM. |
| `gc` | Reclaim unused space (safe while the server runs). |
| `clear --component <comp>` | Clear part of the cache (`views`, `blobs`, `git-cache`, `all`, …). |

**Web (`basemind web`)**

| Command | Purpose |
|---|---|
| `scrape <url>` | Fetch and index a single page. |
| `crawl <seed-url>` | Follow links from a starting URL. |
| `map <url>` | Discover a site's pages without fetching bodies. |

**Agents (`basemind agents`, `--features comms`)**

Every command takes `--as-agent <ID>` to act as a named sub-identity.

| Command | Purpose |
|---|---|
| `register [--name --description --version --skill]` / `list [--thread]` | Publish your identity card / list agents the broker knows. |
| `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. |
| `join <thread>` / `leave <thread>` / `members <thread>` | Join, leave, or list the members of a thread. |
| `add-member <thread> <id>` / `remove-member <thread> <id>` / `archive <thread>` | Manage membership and archive a thread (creator only). |
| `post <thread> <subject> [--body --reply-to --tag]` | Post a message to a thread. |
| `history <thread> [--since-hours]` / `inbox [--mark-read]` / `wait [--thread --timeout-secs]` | A thread's history / your cross-thread inbox / block until a peer posts. |
| `message <id>` | Read one message body in full — the only body path. |
| `ack [--message-id … \| --thread <t> --to-seq <n>]` | Clear read messages by advancing per-thread read cursors. |
| `cleanup [--dry-run \| --apply] [retention overrides]` / `status` | Preview/apply retention / report lifecycle health. |

**Comms daemon (`basemind comms`, `--features comms`)**

| Command | Purpose |
|---|---|
| `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. |
| `doctor` | 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). |

**Shell (`basemind shell`, `--features shells`)**

| Command | Purpose |
|---|---|
| `spawn <command> [--cwd --env --title]` | Start a detached headless shell session; prints a `session_id`. |
| `send <session-id> <text> [--no-enter]` | Type into a session's stdin. |
| `capture <session-id> [--lines]` | Read up to 500 recent non-blank retained-output rows (50 by default). |
| `kill <session-id>` / `list` | End a session / list live sessions. |
| `broadcast <text> --session <id>…` | Send the same input to several sessions at once. |

**Other commands (`scan`, `serve`, `watch`, …)**

| Command | Purpose |
|---|---|
| `scan` / `rescan <path>` | Full scan / update one path. |
| `watch` | Keep the index fresh as files change (no server). |
| `serve [--no-watch]` | Start the server (keeps the index fresh by default). |
| `init` | Re-runnable onboarding: write `basemind.toml`, select capabilities, inject usage rules. |
| `lang <list\|install\|clean>` | Manage downloaded language grammars. |
| `hook install` | Add a git pre-commit hook that runs a scan. |
| `compress-output` / `delta --old <path>` | Backends for the optional guardrails above. |
| `checkpoint` / `detect-waste` | Summarize a session / flag wasteful tool use. |

</details>

---

## License

MIT — see [LICENSE](LICENSE).

[tree-sitter]: https://tree-sitter.github.io/tree-sitter/
[tslp]: https://github.com/Goldziher/tree-sitter-language-pack
[xberg]: https://github.com/xberg-io/xberg
[LanceDB]: https://github.com/lancedb/lancedb

basemind

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

basemind

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README