basemind-code-search

name	basemind-code-search
description	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.

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

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.