`.\n\n\nStatusline (Claude Code)
\n\nRun `/bm-statusline` once. This is a one-time step because Claude Code doesn't let plugins set the\nmain statusline themselves — so basemind asks the assistant to make the one-line settings change on\nyour behalf, and it sticks from then on.\n\nIt shows two lines:\n\n```text\nOpus · basemind · ⎇ main · 12% ctx\n◆ basemind ● 1,247 files · 23m ago │ 312 calls · 180 srch · 44 git · 12 docs │ 1.4M saved │ ✉ 3 @reviewer\n```\n\nThe dot is green when basemind is live and fresh, amber when idle, red when stale. The middle shows\nactivity by type, then tokens saved, then unread messages. Adjust with\n`BASEMIND_STATUSLINE=full|compact|minimal`, or hide the top line with `BASEMIND_STATUSLINE_CONTEXT=0`.\n\n \n\n---\n\n## Demos\n\n\n\n![\"basemind](\"docs/media/demo.gif\")
\nThe same engine from the CLI — scan, then symbol / reference / call-graph / blame queries.
\n\n![\"Semantic](\"docs/media/semantic-demo.gif\")
\nSearching documents by meaning, not keywords, across 90+ formats.
\n\n![\"Three](\"docs/demos/code-review-panel.gif\")
\nMulti-agent code-review panel: named reviewers coordinate in a repo-scoped thread (post, reply, synthesize) — entirely over basemind agents.
\n\n\n\n---\n\n## How it works\n\n\nFrom one scan to instant answers
\n\n`basemind scan` reads your project once, in parallel. It maps your code with\n[tree-sitter] (across [300+ languages][tslp]) and pulls text out of your documents with\n[xberg], then saves the result to a global cache under the XDG data directory, keyed by workspace —\nnothing is written into your repo. After that, `basemind serve` keeps the map in memory and answers\nquestions instantly — no re-reading the project for each one. When files change, it updates only what\nchanged. A single background daemon on the machine is the sole writer to that cache, so multiple\n`serve` sessions on the same repo (or on different worktrees of it) all read and write concurrently\ninstead of one falling back read-only. See [Global cache & the daemon](#how-it-works) below.\n\nNavigation is **scope- and import-aware** for JavaScript/TypeScript, **Python, and Java**: basemind\nresolves each use to the definition it actually binds to, so a shadowed local isn't confused with an\nimport and `code` mode `definition` lands on the right target (including across files for imports). Every\nother language still gets fast tree-sitter scope binding. Precise Python/Java resolution runs GitHub\nstack-graphs-style `.tsg` name-binding rules via an in-tree engine (`crates/`), with no per-language\nLSP server.\n\nResolution **refines, but never shrinks, a result set.** `code` mode `callers` reports every call site\nwhose callee matches the name — the same sound floor mode `references` uses — and marks each hit `resolved`\nwhen resolution proved it binds to that definition (`resolved_total` counts them). It deliberately\ndoes *not* return only the resolved subset: resolution cannot see through a module-object import\n(`from pkg import mod` then `mod.f()`) or an unresolvable path alias, so filtering to it would drop\nreal callers and report the remainder as complete. Filter on `resolved` when you want precision; trust\n`total` when you need completeness.\n\nMarkdown and Obsidian vaults are first-class: headings become navigable symbols (so `code` modes\n`outline` and `symbols` work over a notes vault); `[[wikilinks]]`, `![[embeds]]`, and standard\n`[text](Note.md)` links all become references — so mode `references` on `\"Note\"` returns that note's\nbacklinks regardless of link style; and `#tags` (inline or in YAML frontmatter) become references\ntoo, so mode `references` on `\"#project\"` lists every note carrying that tag.\n\n```mermaid\nflowchart LR\n A([\"Coding agent\"])\n R[\"Your project
code · documents · git\"]\n S[\"basemind scan
map code & read documents\"]\n D[(\"Global cache
per-OS data dir\")]\n V[\"basemind serve
answers questions\"]\n R --> S --> D --> V\n A <-->|asks questions| V\n classDef accent fill:#2563eb,stroke:#1e40af,color:#fff\n class S,V accent\n```\n\nSearch and memory are powered by a vector store ([LanceDB]).\n\n \n\n\nIndex lifecycle & freshness
\n\n`basemind serve` answers the MCP handshake immediately and warms the code map into memory in the\nbackground, so a client never blocks waiting for a large repo to load. The `status` tool reports\n`warming` (still loading) and, once done, `warm_ms`; a first-time index build similarly reports\n`indexing` / `index_build_ms`.\n\nWhile the server isn't fully ready, `status` and every code-map read tool may carry a `notice`\nobject — `{ state, message, retry }` — instead of (or alongside) their normal result:\n\n| `state` | Meaning | `retry` |\n|---|---|---|\n| `warming_up` | Loading an existing index into memory. | `true` |\n| `building_index` | Indexing from scratch (no cache entry for this workspace yet). | `true` |\n| `rescanning` | Incremental rescan after a file change; current results are usable but may be stale. | `false` |\n\nTreat an empty or partial result carrying a `notice` as \"retry shortly,\" not \"no matches\" — poll\n`status` (or just retry the call) until the notice clears.\n\n \n\n\nGlobal cache & the daemon
\n\nIndex state lives under a single global cache — `~/.local/share/basemind/` on Linux,\n`~/Library/Application Support/basemind/` on macOS (override with `BASEMIND_DATA_HOME`) — keyed by\nworkspace, never inside your repo. The\ncontent-addressed blob store is machine-wide too: identical file content scanned from different repos\nor worktrees is extracted and stored once.\n\nA workspace root must be a project: a git repository, or a directory containing `basemind.toml`.\nAnything else is refused, because basemind opens a root read-write and indexes every file beneath\nit — so an accidentally inherited root (`/`, your home directory, or wherever an MCP host happened\nto start) would become a whole-filesystem scan. Run `basemind init` to mark a directory you do want\nindexed, or set `BASEMIND_ALLOW_ANY_ROOT=1` to skip the check. A filesystem or volume root is\nrefused unconditionally and cannot be overridden.\n\nA single background daemon per machine is the sole writer to that cache. `basemind serve` opens its\nstore read-only and forwards writes (scan / rescan) to the daemon over a local socket, so N `serve`\nsessions on the same repo — or on different worktrees of it — all read and write concurrently instead\nof a second session silently falling back to a stale, read-only view. The daemon also keeps a cheap,\nalways-on registry of repos, worktrees, and branches (`workspaces` / `worktrees` / `branches`), and\n`worktree_claim` / `worktree_release` give agent sessions an advisory way to avoid colliding on the\nsame worktree.\n\n`basemind statusline` queries the daemon for the workspaces currently active and prints a compact\nline for your shell prompt; it prints nothing when no daemon is running.\n\nThe daemon is started on demand, detached with `setsid(2)`. That changes the session and the process\ngroup but **not** the cgroup, so on Linux an auto-spawned daemon lives in the cgroup of whatever\nshell or editor happened to start it — outside any `MemoryMax` you configured for basemind. No code\nin basemind can change that; a process cannot move its own children into a cgroup it does not\ncontrol. If you want an enforced memory ceiling, your unit has to be the thing that starts the\ndaemon: set `BASEMIND_NO_AUTOSPAWN=1` everywhere (basemind then connects to a running daemon but\nnever starts one; `basemind comms start` deliberately still does) and install the ready-made user\nunit at [`docs/systemd/basemind-comms.service`](docs/systemd/basemind-comms.service), which also\nlists the two commands that verify the ceiling is real rather than merely configured.\n\nThe daemon can additionally serve MCP over streamable HTTP on loopback, but that front-end is\n**opt-in**: it binds only when `BASEMIND_ALLOW_HTTP` is truthy in the daemon's environment, and every\nrequest must then present the bearer token published as the second line of `/http.addr`\n(mode `0600`). Plugin manifests and the CLI use the stdio transport and need none of this.\n\n \n\n\nHow agents coordinate
\n\nA single shared service in the background lets agents talk to each other — even across different\ntools and different repos on the same machine. Agents coordinate in **threads** — each addressed by\nat least two of subject / path-glob / members, discovered by scope rather than joined globally — and\neach has a personal **inbox**. Messages come in two parts: a short headline (subject and sender)\nthat's cheap to skim, and the full body, fetched only when an agent wants to read it. An agent never\nsees its own posts in its inbox. Idle threads auto-archive.\n\nThe plugin makes sure agents notice messages without being asked — through the built-in instructions,\na notice at session start and each turn, and a quiet background check every few seconds.\n\n```mermaid\nflowchart LR\n A[\"Agent A
Claude Code · repo X\"]\n B[\"Agent B
Cursor · repo Y\"]\n BR[\"Shared comms service
threads · inboxes\"]\n A <-->|post · read| BR\n B <-->|post · read| BR\n classDef accent fill:#2563eb,stroke:#1e40af,color:#fff\n class BR accent\n```\n\n \n\n\nAgent shells
\n\nIncluded in every prebuilt download (and in `cargo install --features shells` / `full`): agents can\nopen terminal sessions in the background, type into them, and read what's on screen — no extra tools\nto install. Sessions can be fully headless, or opened in a real terminal tab or window so you can\nwatch along. A spawned session and the agent that started it can message each other over comms.\n\n \n\n---\n\n## Token saving\n\n\nGood habits the plugin sets up for you
\n\nThe plugin nudges agents toward the cheap path by default:\n\n- Get a file's outline before opening it — then read only the part you need.\n- Search for a definition instead of grepping for it.\n- Look up who calls a function instead of grepping for call sites.\n- Refresh the index after edits instead of restarting the server.\n- Don't re-read a file basemind already mapped.\n\nOptional guardrails enforce this at the moment a tool is used:\n\n- **Guard** — gently redirects `grep`-style searches to the matching basemind tool. On by default;\n set `BASEMIND_GUARD=off` to disable, or `redirect` to block instead of nudge.\n- **Output compressor** — `BASEMIND_COMPRESS_OUTPUT=1` shrinks long command output. It never touches\n anything that looks like a credential and leaves output alone if it can't help.\n- **Re-read shortcut** — `BASEMIND_DELTA_READS=1` shows just what changed when an agent re-reads a\n file it already read this session.\n\n \n\n\nCompression that understands code
\n\nbasemind shrinks code by keeping the shape and dropping the bodies — function signatures and imports\nstay, the implementations go — because a signature is useless without its shape. For prose it does a\nlight cleanup (extra whitespace, filler, repeated paragraphs). It reports honest before/after token\ncounts, and the code version is exact — nothing is lost, just set aside. `expand` brings any one\nfunction's full body back when an agent actually needs it: compress to an outline, expand only what\nyou need.\n\n \n\n---\n\n## Performance\n\n\nScan speed
\n\nMeasured on an Apple M4 (10 cores — 4 performance + 6 efficiency, 16 GB, macOS 26) with the\nhardening harness (`scripts/harden.sh`), which clones each upstream repo fresh and scans its code\nmap. Warm, steady-state numbers; the first scan of a cold project is slower.\n\n| Project | Files | Languages | Scan time |\n|---|---|---|---|\n| gin | 130 | Go | 0.1 s |\n| requests | 128 | Python | 0.1 s |\n| ripgrep | 221 | Rust | 0.6 s |\n| tokio | 861 | Rust | 0.4 s |\n| react | 7 242 | TS / JSX | 2.0 s |\n| django | 7 065 | Python | 2.4 s |\n| TypeScript compiler | 81 324 | TS / JS / JSON | 18 s |\n\nThe TypeScript compiler is the worst case — 81k files in about 18 seconds. Re-scans only look at\nwhat changed, so keeping a project up to date is far faster than the first scan.\n\nOnce running, most code questions answer in **under a millisecond**, symbol and call-graph searches\nin a few milliseconds, and document search in around 200 ms — because the map is held in memory\nrather than read from disk each time.\n\n \n\n\nGit history queries
\n\nbasemind precomputes a per-repo git-history index (path → commit posting lists, stored newest-first)\nso the history modes — `touching`, `recent`, `churn`, `by_path`, and `symbol_history`'s commit walk\n— are posting-list lookups. Warm in-process query latency on the same M4:\n\n| Repo | Commits | `git` `touching` | `git` `recent` | index build | index size |\n|---|---|---|---|---|---|\n| django | 2 000 | 39 µs | 15 µs | 0.5 s | 1.7 MB (6 % of `.git`) |\n| tokio | 3 984 | 37 µs | 13 µs | 0.9 s | 2.1 MB (12 %) |\n| requests | 6 480 | 38 µs | 15 µs | 1.0 s | 1.9 MB (14 %) |\n| TypeScript | 2 000 | 37 µs | 13 µs | 3.2 s | 30 MB (12 %) |\n\nHistory queries answer in **tens of microseconds**, flat across history depth, because the\nnewest-first posting lists decode only the commits a query returns. The index builds in well under a\nsecond to a few seconds and costs **6–22 % of `.git`** on disk.\n\nIt is a pure accelerator: the tools use it only when it is fresh (`last_indexed_head == HEAD`) and\notherwise walk history directly, so it can never serve stale results — and it rebuilds automatically\nwhen history is rewritten (filter-repo / rebase / force-push). Reproduce with\n`cargo bench --bench git_history` or the git-ops block in `scripts/harden.sh`.\n\n \n\n\nMeasuring query latency (elapsed_us)
\n\nEvery latency-relevant mode — all of `code` and `graph`, all of `git`, the `admin` read modes, and\nthe document / memory search modes — reports its own latency as **`elapsed_us`** on its response.\nDon't wrap the CLI in `time`; ask basemind.\n\nResolution is **microseconds** on purpose: an indexed `git` mode `touching` is ~37 µs, so\nmillisecond granularity would round the hot path to `0`.\n\n**What `elapsed_us` includes** — the tool body's own execution: index and store lookups, git walks,\nranking, and building the response.\n\n**What it excludes** — MCP / JSON-RPC transport (which the server cannot observe), argument\ndeserialization, and serialization of the response itself. Excluding encoding keeps the number\ncomparable across `format: \"json\"` and `format: \"toon\"` and across result-set sizes: it reports\n*query* cost, not *encoding* cost.\n\n**The one caveat, stated plainly:** most read tools begin by awaiting the in-RAM code map, and the\ngit tools lazily build their history index on first use. Both waits happen *inside* the measured\nregion, so a first call against a cold server is much slower than the steady-state call after it.\nWhen the server is still warming or building, the response carries a `notice`\n(`warming_up` / `building_index` / `rescanning`) — **discard any sample carrying a `notice`** if you\nare measuring steady-state latency.\n\nThe CLI adds a second number, `startup_us`, covering process startup: clap parsing, the tokio runtime,\nthe store open, and the config/git-cache load. It is reported separately because it is exactly the\npart of a `time basemind …` measurement that was never the query — and a long-running MCP server pays\nit once at boot, not per call:\n\n```console\n$ basemind code symbols run_workspace_grep --limit 1 --json\n{\n ...\n \"elapsed_us\": 90, # the query\n \"startup_us\": 957887 # everything else a `time` wrapper would have charged to it\n}\n\n$ basemind code references parse_kind --limit 3\n...\n(6.5 ms query · 852.9 ms startup)\n```\n\nThat first example is the whole point: the query took 90 µs, while the process spent ~0.96 s getting\nready to run it. A `time basemind …` wrapper would have reported the second number and told you\nnothing about the first.\n\n \n\n---\n\n## Configuration\n\n\nConfig file & overrides
\n\nThe config lives at the **repo root** as `basemind.toml` (committed). The cache it drives is derived\nstate — held in the global cache under the XDG data directory, wiped and rebuilt on schema bumps —\nso config never belongs there and nothing basemind-owned is written into your repo. Run\n`basemind init` to drop a fully-commented scaffold (documenting every option) at the root. The legacy\nin-cache path (`.basemind/basemind.toml`, from before the global-cache move) is still read as a\nfallback for older checkouts. The full schema is at `schema/basemind-config-v1.schema.json`:\n\n```toml\n# basemind.toml (repo root — commit this)\n\"$schema\" = \"v1\"\n\n[scan]\nrespect_gitignore = true\n# Follow symlinks during the walk. Off by default — symlinks often escape the repo (e.g. Bazel's\n# bazel-* convenience symlinks). Turn on for repos that symlink real source into place.\nfollow_symlinks = false\n# `exclude` is ADDED ON TOP of an always-on floor (node_modules, target, dist, build, out, .venv,\n# venv, __pycache__, *.pyc, .pytest_cache/.mypy_cache/.ruff_cache/.tox, .next/.nuxt/.svelte-kit,\n# vendor, .gradle, .terraform, coverage, bazel-*, .git, .basemind, .idea, .DS_Store). You can add to\n# it but not remove a floor entry.\nexclude = []\n# Index directories outside the repo root too — e.g. a Bazel external repo cache — so their\n# symbols resolve in search / references / outlines. External files are keyed by absolute path;\n# (re-)indexed on a full `basemind scan` only (not live-watched). Requires the operator to set\n# BASEMIND_ALLOW_EXTRA_ROOTS=1 in the environment: this file lives inside the repository, so\n# without that opt-in a cloned repo could point basemind at your ~/.ssh. Extra roots count toward\n# max_candidates and follow symlinks only when follow_symlinks is on.\nextra_roots = [\"/private/var/tmp/_bazel_you/abc123/external\"]\n# Ceiling on how many candidate files one scan may keep, across the repo walk and every extra root.\n# Exceeding it aborts before any extraction or index write, and the error names the heaviest\n# contributing directories — so a vendored tree that slipped past .gitignore is a one-line fix\n# instead of an out-of-memory kill. It also bounds how far the walk may travel to find them. It does\n# NOT bound bytes read or index size, and does not apply to `--staged` / `--rev` (those enumerate\n# from git, not from a walk). 0 disables both bounds.\nmax_candidates = 500_000\n\n[code_intel]\n# Precise, scope- and import-aware resolution (JS/TS via oxc; Python/Java via stack-graphs). On by\n# default. Set false to fall back to fast tree-sitter locals binding for every language. Applies to\n# files (re)scanned after the change.\nprecise_resolution = true\n\n[documents]\nenabled = true\n# Embed documents for semantic search (ON — embeddings pay off on real prose / OCR).\nembed = true\n# Model preset: fast | balanced (default, 768-dim) | quality | multilingual.\n# Changing the preset forces a FULL RE-EMBED of the corpus (time + CPU): every document is\n# re-encoded at the new model's dimension.\nembedding_preset = \"balanced\"\n# Documents that are extracted + indexed but never embedded (keyword-only).\nembed_exclude = []\n# Route archives (.zip/.tar/.jar/…) into the recursive extractor. Off by default so one archive\n# can't explode into thousands of embeds; true binaries are always skipped.\nextract_archives = false\n\n[code_search]\nenabled = true\n# Vector embeddings for code are OFF by default — a general English model on code isn't worth the\n# cost, and NL→symbol is already served by the BM25 keyword lane. Chunking + keyword search work\n# regardless. Turn on only for vector search over code (downloads an ONNX model, re-embeds on\n# preset change).\nembed = false\nembed_exclude = []\n# Cap on chunks indexed per source file. A generated parser table or a checked-in bundle otherwise\n# fans one file out into a chunk count bounded only by max_file_bytes, and every chunk costs a\n# keyword posting, a vector row, and (with embed on) an embed. Over-cap files are still chunked and\n# cached — outline and grep are unaffected — they just contribute no postings and no vector rows.\nmax_chunks_per_file = 2000\n\n[resources]\n# Memory ceiling for this process, in MiB. A positive integer is an explicit ceiling; 0 or \"auto\"\n# (the default) derives one — 75% of an enforced cgroup limit, or 50% of machine RAM, floored at\n# 512 MiB; \"off\" disables it. ADVISORY: workers park while over the ceiling and are admitted anyway\n# after five seconds, so it shapes peak memory rather than enforcing a hard limit. To actually cap\n# the daemon's memory, run it from your own resource-controlled unit — see\n# `docs/systemd/basemind-comms.service`.\nmax_footprint_mb = \"auto\"\n# Byte budget (MiB) for the MCP read stack's decoded-outline cache, per workspace. 0 = unbounded.\n# A miss costs one blob read and never changes an answer.\nmax_map_cache_mb = 256\n```\n\nAny tool call can override these settings for that one request, and settings map to environment\nvariables in the obvious way: `--llm-api-key` becomes `BASEMIND_LLM_API_KEY`.\n\n \n\n---\n\n## CLI reference\n\n\nFull command list — code · graph · git · memory · admin · cache · web · agents · workspace · shell
\n\nCLI commands mirror the MCP tools 1:1 (enforced by `tests/cli_parity.rs`). Add `--json` for\nmachine-readable output.\n\n\n\n**Code (`basemind code`)**\n\n| Command | Purpose |\n|---|---|\n| `outline [--l2]` | A file's structure: symbols, lines, signatures. `--l2` adds calls + docs. |\n| `symbols [--kind]` | Find a definition by name, optionally filtered by kind. |\n| `grep [--language --path-contains]` | Pattern search with filters. |\n| `files [--path-contains --language]` | List indexed files. |\n| `find ` | Locate a file by a fuzzy fragment of its name or path (fzf/fd-style). |\n| `definition [--column]` | Resolve a reference position to its scope-resolved definition. |\n| `references ` | Find everywhere a name is called. |\n| `callers [--kind]` | Find callers of one specific definition. |\n| `implementations ` | Types that implement or inherit from a name. |\n| `dependents ` | What imports a given module. |\n| `expand [--kind]` | A symbol's raw source body (the inverse of an outline entry). |\n| `semantic [--limit --lane --format]` | Search code by meaning; returns pointers. Needs `--features code-search`. |\n| `chunk [--chunk-id --byte-start]` | Fetch one code chunk's source body (the `semantic` fetch half). |\n\n**Graph (`basemind graph`)**\n\n| Command | Purpose |\n|---|---|\n| `calls [--direction --max-depth --max-nodes]` | Walk the call chain up (`callers`, default) or down (`callees`). |\n| `neighbors [--direction --depth --edges --max-nodes]` | A symbol's n-hop neighborhood — its blast radius before you change it. |\n| `path [--edges --include-contains]` | Confidence-weighted shortest route between two symbols. |\n| `subgraph [--depth --edges --max-nodes]` | The neighborhood cut to its most central nodes — readable, not a dump. |\n| `communities [--algorithm --max-communities]` | Cluster the graph into de-facto modules with deterministic labels. |\n| `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. |\n| `export [--format --focus --edges --write]` | Render as node-link JSON / DOT / Mermaid / GraphML / Cypher / HTML / SVG. |\n| `display [--format --no-open]` | Open a rendered view in the human's desktop viewer. `--no-open` writes the artifact and returns its path. |\n| `open [--format --no-open]` | Return a live `http://…/ui` URL for the interactive graph (or a `file://` export). The live page needs the daemon's HTTP front-end, which is opt-in — set `BASEMIND_ALLOW_HTTP=1` in the daemon's environment; without it you get the `file://` export. `--no-open` launches nothing. |\n\n**Git (`basemind git`)**\n\n| Command | Purpose |\n|---|---|\n| `status` | What's staged and unstaged right now. |\n| `recent [--limit] [--no-files]` | Recent commits with their files (a recency window, not a search). |\n| `search [--field author\\|message\\|all] [--limit]` | Full-text search over commit history at full branch depth. |\n| `touching ` / `by-path ` | Commits for a path or a changed-path regex. |\n| `churn [--window --top-k]` | The most frequently changed files. |\n| `diff ` / `diff-outline [--rev]` | File or structure diff across commits. |\n| `blame ` / `blame-symbol ` | Who last changed each line / a symbol. |\n| `symbol-history ` | When a symbol's body changed over time. |\n\n**Memory (`basemind memory`)**\n\n| Command | Purpose |\n|---|---|\n| `put ` / `get ` / `delete ` | Store, retrieve, or remove a value. |\n| `list [--prefix]` | List keys, optionally by prefix. |\n| `search ` | Search stored values by meaning. |\n| `documents ` | Search indexed PDFs / Office / HTML / images by meaning. |\n| `mine [--commits --min-count --min-confidence --max-files]` | Suggest notes from files that change together. |\n| `proposals [--kind --limit]` | List pending suggestions. |\n| `accept [--key]` / `reject [--reason]` | Keep a suggestion / dismiss it for good. |\n| `audit [--key --individual --dry-run --include-archived]` | Recompute memory importance, archive stale entries, refresh verdicts. |\n\n**Admin (`basemind admin`)**\n\n| Command | Purpose |\n|---|---|\n| `status` / `repo` | Index health (files, languages, scan state) / git identity (branch, HEAD, origin). |\n| `rescan [PATH…] [--full]` | Re-index the working tree, or only the given paths. |\n| `cache-stats` / `gc` | On-disk footprint + process RAM / reclaimable-blob report. |\n| `cache-clear --component [--confirm]` | Clear one cache component (`views`/`all` need the offline `basemind cache clear`). |\n| `telemetry [--window --tool]` | What's been queried and how many tokens were saved. |\n| `compress` / `delta` / `checkpoint` / `waste` | Outline a file, diff a re-read, summarize a session, flag wasteful tool use. |\n\n**Cache (`basemind cache`)**\n\n| Command | Purpose |\n|---|---|\n| `stats` | Disk footprint (per-component + total, matches `du`) and process RAM. |\n| `gc` | Reclaim unused space (safe while the server runs). |\n| `clear --component ` | Clear part of the cache (`views`, `blobs`, `git-cache`, `all`, …). |\n\n**Web (`basemind web`)**\n\n| Command | Purpose |\n|---|---|\n| `scrape ` | Fetch and index a single page. |\n| `crawl ` | Follow links from a starting URL. |\n| `map ` | Discover a site's pages without fetching bodies. |\n\n**Agents (`basemind agents`, `--features comms`)**\n\nEvery command takes `--as-agent ` to act as a named sub-identity.\n\n| Command | Purpose |\n|---|---|\n| `register [--name --description --version --skill]` / `list [--thread]` | Publish your identity card / list agents the broker knows. |\n| `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. |\n| `join ` / `leave ` / `members ` | Join, leave, or list the members of a thread. |\n| `add-member ` / `remove-member ` / `archive ` | Manage membership and archive a thread (creator only). |\n| `post [--body --reply-to --tag]` | Post a message to a thread. |\n| `history [--since-hours]` / `inbox [--mark-read]` / `wait [--thread --timeout-secs]` | A thread's history / your cross-thread inbox / block until a peer posts. |\n| `message ` | Read one message body in full — the only body path. |\n| `ack [--message-id … \\| --thread --to-seq ]` | Clear read messages by advancing per-thread read cursors. |\n| `cleanup [--dry-run \\| --apply] [retention overrides]` / `status` | Preview/apply retention / report lifecycle health. |\n\n**Comms daemon (`basemind comms`, `--features comms`)**\n\n| Command | Purpose |\n|---|---|\n| `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. |\n| `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). |\n\n**Shell (`basemind shell`, `--features shells`)**\n\n| Command | Purpose |\n|---|---|\n| `spawn [--cwd --env --title]` | Start a detached headless shell session; prints a `session_id`. |\n| `send [--no-enter]` | Type into a session's stdin. |\n| `capture [--lines]` | Read up to 500 recent non-blank retained-output rows (50 by default). |\n| `kill ` / `list` | End a session / list live sessions. |\n| `broadcast --session …` | Send the same input to several sessions at once. |\n\n**Other commands (`scan`, `serve`, `watch`, …)**\n\n| Command | Purpose |\n|---|---|\n| `scan` / `rescan ` | Full scan / update one path. |\n| `watch` | Keep the index fresh as files change (no server). |\n| `serve [--no-watch]` | Start the server (keeps the index fresh by default). |\n| `init` | Re-runnable onboarding: write `basemind.toml`, select capabilities, inject usage rules. |\n| `lang ` | Manage downloaded language grammars. |\n| `hook install` | Add a git pre-commit hook that runs a scan. |\n| `compress-output` / `delta --old ` | Backends for the optional guardrails above. |\n| `checkpoint` / `detect-waste` | Summarize a session / flag wasteful tool use. |\n\n\n\n \n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n[tree-sitter]: https://tree-sitter.github.io/tree-sitter/\n[tslp]: https://github.com/Goldziher/tree-sitter-language-pack\n[xberg]: https://github.com/xberg-io/xberg\n[LanceDB]: https://github.com/lancedb/lancedb\n",
"bytes": 47280,
"sha": "5bdc5011044845dff0a9b2ef1d386bbb2387e88fc12edfe9eb28bc4c07d8f08d",
"repo_slug": "goldziher/basemind",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_goldziher_basemind_fe42e03a/readme"
}![\"basemind](\"docs/media/basemind-banner.svg\")
\n\n**The context and communication layer for coding agents.**\n\nbasemind turns any repo into an always-current map of its code, documents, history, and memory —\nso agents answer from **structure and search** instead of burning their context window on `grep` and\nfile reads — and gives a team of agents a **shared channel to coordinate** while they work. One\nserver does both.\n\nCode map across **300+ languages** · documents in **90+ formats** · semantic + full-text search ·\ngit history & blame · shared memory · web crawl · agent-to-agent comms\n\n[](https://basemind.ai)\n[](https://crates.io/crates/basemind)\n[](https://www.npmjs.com/package/basemind)\n[](https://pypi.org/project/basemind/)\n[](https://github.com/Goldziher/basemind/actions/workflows/ci.yaml)\n[](LICENSE)\n\n[Docs](https://basemind.ai) · [Install](#installation) · [Features](#what-you-get) · [How it works](#how-it-works) · [Performance](#performance) · [CLI](#cli-reference)\n\n![\"An](\"docs/media/mcp-demo.gif\")