Why Codemap
Local codebase intelligence for AI agents — what Codemap is for and what it is not.
Agents discover code by globbing, grepping, and reading files. On medium TypeScript trees that often means 3–5 tool calls and multi-MB context per structural question. AST-backed facts in .codemap/index.db make the answer one SQL (or recipe) round-trip.
Not grep semantics by default — use ripgrep / your IDE for raw text. Opt-in FTS5 (--with-fts / fts5: true) when body matches need to JOIN with symbols / coverage / markers.
What you get
| Question | Without index | With Codemap |
|---|---|---|
Where is UserService defined? |
Glob + Read + filter | find-symbol-definitions / show |
Who imports ~/utils/date? |
Grep + resolve aliases by hand | dependencies / impact |
Components using useQuery |
Grep + filter to components | components table / recipes |
| Heaviest import hubs | Impractical without a graph | fan-in |
Indexed structural queries stay sub-millisecond on typical trees; the real win for agents is token cost — rows instead of whole-file reads, compounded across a session.
Four tenets (short)
- Structural over semantic — facts the AST and resolver can prove; no embeddings in the box.
- Predicate-as-API — SQL + named recipes; SARIF/annotations are output modes, not primitives.
- Local-first, agent-native — SQLite on disk; CLI, MCP, HTTP, GitHub Action share the same recipes.
- Honest scope — say what not to use it for. See When to skip.
Vs alternatives (axes)
| Axis | Codemap | Static linters | Repo-map style tools | LSP |
|---|---|---|---|---|
| Thesis | Query structure with SQL | Emit findings / fixes | Summarize into a blob | Per-edit semantic helpers |
| Who decides | The agent (via SQL) | The tool’s rules | The tool’s ranking | The editor |
| Best for | Where / what / who lookups | “Is this dead / banned?” | First-touch priming | Refactor / hover / types |
Named peers in the SQLite / agent-context cohort (SQL vs Cypher vs fixed tools vs quality gates): Comparison.
They don’t compete for the same slot — use Codemap and a linter and an LSP.