How do I install the Basemind Scan skill?

Run npx skillmds@latest add goldziher/basemind-scan in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Basemind Scan safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Basemind Scan?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Basemind Scan free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Basemind Scan?

goldziher (@goldziher) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Basemind Scan by goldziher — Agent Skill

Name: Basemind Scan
Author: goldziher

Basemind Scan

Build or refresh the basemind index by running `basemind scan` via the CLI. Use this when basemind reports "no index" / "no indexed files", when the MCP server isn't available, or after large changes when the index is stale. Works without the MCP server — it shells the basemind binary directly.

goldziher 86d4602 3.3 KB Updated Sep 17, 2026

File contents

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:

basemind scan            # full working-tree scan
basemind scan <path>     # scope to a path (incremental)

Finding the binary (in order of preference):

basemind on PATH.
The plugin-managed binary the MCP launcher caches: ${XDG_CACHE_HOME:-~/.cache}/basemind/bin/<version>/basemind.
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.

---name: basemind-scandescription: Build or refresh the basemind index by running `basemind scan` via the CLI. Use this when basemind reports "no index" / "no indexed files", when the MCP server isn't available, or after large changes when the index is stale. Works without the MCP server — it shells the basemind binary directly.---# 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 runFrom the repository root:```shbasemind scan # full working-tree scanbasemind 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.

Frequently asked questions