| alwaysApply | true |
|---|
STOP. Before you call Grep, Glob, SemanticSearch, or Read to answer a structural question about this repository — query the Codemap SQLite index first. This is not optional when the question matches a trigger pattern below.
A local database (default .codemap.db) indexes structure: symbols, imports, exports, components, dependencies, markers, CSS variables, CSS classes, CSS keyframes.
This file is for developing Codemap in this clone. End users of the published package get the agent rule from templates/agents/ (via codemap agents init). Generic defaults: SQL and triggers stay project-agnostic — edit this rule for repo-specific paths and queries.
| Context | Incremental index | Query |
|---|---|---|
| Default — from this clone | bun src/index.ts |
bun src/index.ts query --json "<SQL>" |
| Same entry | bun run dev |
(same as first row) |
| Query (ASCII table — optional) | — | bun src/index.ts query "<SQL>" |
| Recipe | — | bun src/index.ts query --json --recipe fan-out (see bun src/index.ts query --help) |
| Recipe catalog / SQL | — | bun src/index.ts query --recipes-json · bun src/index.ts query --print-sql fan-out |
After bun run build, node dist/index.mjs matches the published codemap binary (same flags). bun link / global codemap also work when testing the packaged CLI.
Index another project: --root /path/to/repo, or set CODEMAP_ROOT or CODEMAP_TEST_BENCH (e.g. in .env — see docs/benchmark.md § Indexing another project). Full rebuild: --full. Targeted re-index: --files path/to/a.ts path/to/b.tsx.
Run incremental indexing to catch changes made outside this session:
bun src/index.ts- Does the question match a trigger pattern below?
- If yes → query the index. Do NOT use Grep/Glob/SemanticSearch/Read.
- If the index result is incomplete → THEN fall back to other tools, but always try the index first.
Violating this order is wrong even if you get the right answer — it wastes time and ignores the tool purpose-built for this.
If the question looks like any of these → use the index:
| Question shape | Table(s) |
|---|---|
| "What/which files import X?" | imports (by source) or dependencies (by to_path) |
| "Where is X defined?" | symbols |
| "What does file X export?" | exports |
| "What hooks does component X use?" / "List React components" | components |
| "What are the CSS variables/tokens for X?" | css_variables |
| "Find all TODOs/FIXMEs" | markers |
| "Who depends on file X?" / "What does file X depend on?" | dependencies |
| "How many files/symbols/components are there?" | any table with COUNT(*) |
| "What are the CSS classes in X?" | css_classes |
| "What keyframe animations exist?" | css_keyframes |
| "What fields does interface/type X have?" | type_members |
| "Is symbol X deprecated?" / "What does X do?" | symbols (doc_comment) |
| "Who calls X?" / "What does X call?" | calls |
- Reading implementation details you need to edit
- Reviewing logic, control flow, or business rules
- Searching for patterns the index doesn't capture (string literals, inline logic, etc.)
bun src/index.ts query --json "<SQL>"Human-readable: Omit --json to print console.table to the terminal (optional; wide results use more lines and bytes than JSON).
Row count: The CLI does not impose a maximum number of rows. Add LIMIT (and ORDER BY) in SQL when you need a bounded list. With --json, stdout is a JSON array on success; on failure, stdout is {"error":"<message>"} and the process exits 1 (invalid SQL, database open errors, or query bootstrap failures such as config/resolver — not only SQL runtime errors). The CLI sets process.exitCode instead of process.exit so piped stdout is not truncated.
Verbatim answers: When the user asks for lists, counts, or enumerated structural data from the index, paste or summarize from the query output without inventing rows — do not substitute a prose “summary” that omits rows the user asked to see. Use --json so the full result set is unambiguous.
| I need to... | Query |
|---|---|
| Find a symbol | SELECT name, kind, file_path, line_start, line_end, signature FROM symbols WHERE name = '...' |
| Find a symbol (fuzzy) | SELECT name, kind, file_path, line_start FROM symbols WHERE name LIKE '%...%' |
| See file exports | SELECT name, kind, is_default FROM exports WHERE file_path LIKE '%...' |
| See file imports | SELECT source, specifiers, is_type_only FROM imports WHERE file_path LIKE '%...' |
| Who imports this module? | SELECT DISTINCT file_path FROM imports WHERE source LIKE '~/some/module%' |
| Who imports this file? | SELECT DISTINCT from_path FROM dependencies WHERE to_path LIKE '%...' |
| What does this depend on? | SELECT DISTINCT to_path FROM dependencies WHERE from_path LIKE '%...' |
| Component info | SELECT name, props_type, hooks_used FROM components WHERE name = '...' |
| All components | SELECT name, file_path, props_type, hooks_used FROM components ORDER BY name |
| TODOs in a file | SELECT line_number, content FROM markers WHERE file_path LIKE '%...' AND kind = 'TODO' |
| Most complex files | SELECT from_path, COUNT(*) as deps FROM dependencies GROUP BY from_path ORDER BY deps DESC LIMIT 10 |
| CSS design tokens | SELECT name, value, scope FROM css_variables WHERE name LIKE '--%...' |
| CSS module classes | SELECT name, file_path FROM css_classes WHERE is_module = 1 |
| CSS keyframes | SELECT name, file_path FROM css_keyframes |
| Type/interface shape | SELECT name, type, is_optional, is_readonly FROM type_members WHERE symbol_name = '...' |
| Deprecated symbols | SELECT name, kind, file_path, doc_comment FROM symbols WHERE doc_comment LIKE '%@deprecated%' |
| Symbol docs | SELECT name, signature, doc_comment FROM symbols WHERE name = '...' AND doc_comment IS NOT NULL |
| Const values | SELECT name, value, file_path FROM symbols WHERE kind = 'const' AND value IS NOT NULL AND name LIKE '%...' |
| Class members | SELECT name, kind, signature FROM symbols WHERE parent_name = '...' |
| Top-level only | SELECT name, kind, signature FROM symbols WHERE parent_name IS NULL AND file_path LIKE '%...' |
| Who calls X? | SELECT DISTINCT caller_name, file_path FROM calls WHERE callee_name = '...' |
| What does X call? | SELECT DISTINCT callee_name FROM calls WHERE caller_name = '...' |
| Call hotspots | SELECT callee_name, COUNT(*) as fan_in FROM calls GROUP BY callee_name ORDER BY fan_in DESC LIMIT 10 |
Use DISTINCT on dependency and import queries — a file importing multiple specifiers from the same module produces duplicate rows.
For the full schema, advanced query patterns, and troubleshooting, read the skill at .agents/skills/codemap/SKILL.md.
After completing a step that modified source files, re-index before making any further queries. The index only reflects the state at the time it was last built — edits you just made won't appear until you re-index.
# Targeted — re-index only the files you just touched
bun src/index.ts --files path/to/file1.tsx path/to/file2.ts
# Incremental — auto-detects changed files via git
bun src/index.ts
# Full rebuild — after rebase, branch switch, or stale index
bun src/index.ts --full- After editing files — use
--fileswith the paths you modified (fastest). Deleted files are auto-detected and removed from the index - After switching branches or rebasing — run
--full - When unsure which files changed — run without flags to auto-detect via git