basemind-code-search — navigate code without reading it
basemind pre-indexes the repo into a tree-sitter code map across 300+ languages. Structural
questions — where a symbol lives, what calls it, what shape a file has — resolve from the index in
milliseconds and return paths, line numbers, and signatures, not file bodies. That is a fraction
of the tokens of reading source, so it is the default, not an optimization.
basemind first, grep/read fallback. If a question is about where, what calls, what shape,
or what implements, a basemind tool answers it cheaper than grep/rg or opening files. Drop to
raw shell only when no tool covers the question.
The discipline
- Use
code mode outline before you open a file. A 1000-line file becomes a 30-line table of contents.
Read the actual source only once you have the exact span, then read that range, not the file.
- Use
code mode symbols instead of grep for a definition. It matches indexed symbol names and
returns path:line, skipping the comment/string/test-name noise grep drowns you in.
- Use
code modes references / callers instead of grepping call sites. Indexed call edges, not
text matches.
- Use
code mode grep instead of shelling out to ripgrep when you genuinely need regex over
content — it runs over the in-RAM index and returns capped, structured hits.
- Do not re-read a file basemind already mapped. If the outline answered the question, stop.
- Use
admin mode rescan after you edit code, not a server reconnect. Pass paths: [...] to limit it.
Tool routing
| Question |
MCP tool |
CLI |
| "Where is X defined?" |
code { mode: "symbols", name: "X" } (substring, optional kind) |
basemind code symbols "X" |
| "Jump to the definition of X used here?" |
code { mode: "definition", path: F, line } (scope-aware) |
basemind code definition F line [--column] |
| "What's the high-level architecture / module map?" |
graph { mode: "map" } |
basemind graph map |
| "What's the shape of file F?" |
code { mode: "outline", path: F } (add l2: true) |
basemind code outline F [--l2] |
| "What calls X?" (any name) |
code { mode: "references", name: "X" } |
basemind code references "X" |
| "What calls this specific definition?" |
code { mode: "callers", path: F, name } |
basemind code callers F name [--kind] |
| "Trace the call graph from a function?" |
graph { mode: "calls", name } (bounded BFS) |
basemind graph calls "name" [--direction --max-depth] |
| "What implements / extends / inherits X?" |
code { mode: "implementations", trait_name: "X" } |
basemind code implementations "X" |
| "What imports module M?" |
code { mode: "dependents", module: "M" } |
basemind code dependents "M" |
| "What files are indexed?" |
code { mode: "files" } (filter by language/path) |
basemind code files [--language --path-contains] |
| "Regex over file contents?" |
code { mode: "grep", pattern: "…" } |
basemind code grep "pattern" [--language --path-contains] |
| "What's indexed?" |
admin { mode: "status" } |
basemind admin status |
| "Refresh the index after editing?" |
admin { mode: "rescan", paths: […] } |
basemind admin rescan [path…] |
| "Fetch the next page?" |
pass next_cursor from the prior response as cursor |
— |
Examples
code { mode: "symbols", name: "MapCache" }
→ src/mcp/mod.rs:79:1 MapCache (struct)
src/mcp/mod.rs:88:1 MapCache (impl)
code { mode: "references", name: "process_file" }
→ src/scanner.rs:142:9 process_file
src/scanner.rs:201:13 process_file
code { mode: "outline", path: "src/mcp/tools.rs" }
→ 21 code router (function)
112 code helper (function)
Notes
- Matching on symbol names is substring:
code mode references with name: "bar" matches
Foo::bar() and bar() alike. There is no scope resolution — cross-check with code mode
outline when disambiguation matters.
- Lists are capped (
limit, default 100, max 1000). Index scanners use scan_cap = limit * 8 to
bound work on common names.
- Needs an index in the machine-global cache (Linux
~/.local/share/basemind/, macOS
~/Library/Application Support/basemind/; override BASEMIND_DATA_HOME) — run basemind scan
first (see the basemind-scan skill). "No indexed files" means the scan hasn't run in this repo yet.
For git history / blame / diffs see basemind-git-history; for document RAG and semantic search see
basemind-documents; for agent coordination see basemind-comms.
1---2name: basemind-code-search3description: Find where code is defined and used without reading files — symbol search, file outlines, references, callers, call graphs, implementations, dependents, and indexed regex over content. Reach for it whenever the user asks "where is X defined", "what calls Y", "what implements Z", "what's the shape of this file", or whenever you're about to grep or open files to learn structure.4---56# basemind-code-search — navigate code without reading it78basemind pre-indexes the repo into a tree-sitter code map across 300+ languages. Structural9questions — where a symbol lives, what calls it, what shape a file has — resolve from the index in10milliseconds and return **paths, line numbers, and signatures, not file bodies**. That is a fraction11of the tokens of reading source, so it is the default, not an optimization.1213**basemind first, grep/read fallback.** If a question is about _where_, _what calls_, _what shape_,14or _what implements_, a basemind tool answers it cheaper than `grep`/`rg` or opening files. Drop to15raw shell only when no tool covers the question.1617## The discipline1819- **Use `code` mode `outline` before you open a file.** A 1000-line file becomes a 30-line table of contents.20 Read the actual source only once you have the exact span, then read _that range_, not the file.21- **Use `code` mode `symbols` instead of `grep` for a definition.** It matches indexed symbol names and22 returns `path:line`, skipping the comment/string/test-name noise grep drowns you in.23- **Use `code` modes `references` / `callers` instead of grepping call sites.** Indexed call edges, not24 text matches.25- **Use `code` mode `grep` instead of shelling out to ripgrep** when you genuinely need regex over26 content — it runs over the in-RAM index and returns capped, structured hits.27- **Do not re-read a file basemind already mapped.** If the outline answered the question, stop.28- **Use `admin` mode `rescan` after you edit code**, not a server reconnect. Pass `paths: [...]` to limit it.2930## Tool routing3132| Question | MCP tool | CLI |33|---|---|---|34| "Where is X defined?" | `code { mode: "symbols", name: "X" }` (substring, optional `kind`) | `basemind code symbols "X"` |35| "Jump to the definition of X used here?" | `code { mode: "definition", path: F, line }` (scope-aware) | `basemind code definition F line [--column]` |36| "What's the high-level architecture / module map?" | `graph { mode: "map" }` | `basemind graph map` |37| "What's the shape of file F?" | `code { mode: "outline", path: F }` (add `l2: true`) | `basemind code outline F [--l2]` |38| "What calls X?" (any name) | `code { mode: "references", name: "X" }` | `basemind code references "X"` |39| "What calls this specific definition?" | `code { mode: "callers", path: F, name }` | `basemind code callers F name [--kind]` |40| "Trace the call graph from a function?" | `graph { mode: "calls", name }` (bounded BFS) | `basemind graph calls "name" [--direction --max-depth]` |41| "What implements / extends / inherits X?" | `code { mode: "implementations", trait_name: "X" }` | `basemind code implementations "X"` |42| "What imports module M?" | `code { mode: "dependents", module: "M" }` | `basemind code dependents "M"` |43| "What files are indexed?" | `code { mode: "files" }` (filter by language/path) | `basemind code files [--language --path-contains]` |44| "Regex over file contents?" | `code { mode: "grep", pattern: "…" }` | `basemind code grep "pattern" [--language --path-contains]` |45| "What's indexed?" | `admin { mode: "status" }` | `basemind admin status` |46| "Refresh the index after editing?" | `admin { mode: "rescan", paths: […] }` | `basemind admin rescan [path…]` |47| "Fetch the next page?" | pass `next_cursor` from the prior response as `cursor` | — |4849## Examples5051```text52code { mode: "symbols", name: "MapCache" }53→ src/mcp/mod.rs:79:1 MapCache (struct)54 src/mcp/mod.rs:88:1 MapCache (impl)5556code { mode: "references", name: "process_file" }57→ src/scanner.rs:142:9 process_file58 src/scanner.rs:201:13 process_file5960code { mode: "outline", path: "src/mcp/tools.rs" }61→ 21 code router (function)62 112 code helper (function)63```6465## Notes6667- Matching on symbol names is **substring**: `code` mode `references` with `name: "bar"` matches68 `Foo::bar()` and `bar()` alike. There is no scope resolution — cross-check with `code` mode69 `outline` when disambiguation matters.70- Lists are capped (`limit`, default 100, max 1000). Index scanners use `scan_cap = limit * 8` to71 bound work on common names.72- Needs an index in the machine-global cache (Linux `~/.local/share/basemind/`, macOS73 `~/Library/Application Support/basemind/`; override `BASEMIND_DATA_HOME`) — run `basemind scan`74 first (see the `basemind-scan` skill). "No indexed files" means the scan hasn't run in this repo yet.7576For git history / blame / diffs see `basemind-git-history`; for document RAG and semantic search see77`basemind-documents`; for agent coordination see `basemind-comms`.
goldziher