basemind-scan

<!-- AI-RULEZ :: GENERATED FILE — DO NOT EDIT Content-Hash: blake3:0f2cc34ae8970652066484ed94f3f2a965201654a29fdf3aa9318d2631422c39 Source-Hash: blake3:8e3d03b0a29d70e7684fb65ed1186f800ac703498c14f053341d8869d89b2bbe Schema-Version: v1 --> # basemind-scan — build or refresh the index (no MCP server required) basemind answers code-map questions from an index in a machine-global cache (Linux `~/.local/share/basemind/`, macOS `~/Library/Application Support/basemind/`; override `BASEMIND_DATA_HOME`), keyed by workspace. That index is built by `basemind scan`. This skill runs the scan via the **CLI**, so it works even when the MCP server (`basemind serve`) is not running — which is exactly the situation when basemind reports **"no index"** or **"no indexed files"**, or when MCP tools aren't loaded in the session. ## When to use - basemind / the statusline reports **no index** for this repo. - An MCP tool returns "no indexed files" or empty results that should not be empty. - The MCP server isn't running or isn't reachable, and you need the code map. - The index is stale after large changes and you want a full rebuild. ## How to run From the repository root: ```sh basemind scan # full working-tree scan basemind scan <path> # scope to a path (incremental) ``` Finding the binary (in order of preference): 1. `basemind` on `PATH`. 2. The plugin-managed binary the MCP launcher caches: `${XDG_CACHE_HOME:-~/.cache}/basemind/bin/<version>/basemind`. 3. A dev build: `cargo build --release` then `./target/release/basemind scan`. ## Notes - The scan writes the content-addressed blob store + Fjall inverted index into the machine-global cache (never inside the repo). Seconds for small repos; ~22 s for an ~80k-file TypeScript monorepo. - Files tree-sitter doesn't recognize as code go through the document tier; anything that isn't an extractable document (e.g. an exotic source file) is **skipped**, not counted as a failure. - If a `basemind serve` MCP server is already running for this repo it holds the store lock, so a CLI `scan` will fail with a lock error. Use `admin { mode: "rescan" }` over MCP (it re-indexes in-process) instead, or stop the server first. - **Indexing directories outside the repo** — set `scan.extra_roots` in the repo-root `basemind.toml` to a list of absolute paths (e.g. a Bazel external repo cache) to index them alongside the repo. This needs `BASEMIND_ALLOW_EXTRA_ROOTS=1` in the environment that launches basemind: the config file lives inside the repository, so without that operator opt-in the entries are ignored with a warning. A filesystem or volume root is refused either way. Their files are keyed by absolute path (so results for them are absolute, not repo-relative) and are (re-)indexed on a full `scan` only — the live watcher does not track them. Git tools (blame) don't apply to external files; the code map (symbols / references / outlines) and document search do. - After a successful scan, both the MCP tools and `basemind code …` have a fresh index. - The CLI shares the exact same machine-global cache as the MCP server — see the `basemind-cli` skill for the full query surface, or `basemind-code-search` / `basemind-git-history` / `basemind-documents` for the per-capability workflows.