codebase-index

Codebase Index

Use the local index before reading repository files. It answers with ranked, numbered lines, so most answers need no Read and no Grep at all.

Route the question — always --compact

--compact prints path:start-end symbol per result with the matching lines numbered underneath ( 24| public static final String FILE_ID = ...). Cite those lines as path:24 directly. Read a range only when the lines shown do not answer the question — and then only that range, never the whole file.

Name members as Owner.member (TownService.refresh, activation::place, CoreError::ObjectDamaged) so same-named methods of other types are excluded. refs --compact lines are path:line kind caller -> target: the list of call sites with the calling function is usually the whole answer. Add --exclude-tests for production-only lists and --path <prefix> for one module. kind reference is a non-call use, e.g. an enum variant matched in a match arm.

impact --compact starts with # module <m>: build files depending on it: ... — the answer to "does another module depend on this", with no build-file grep.

Protocol

1. Pick one session tag per conversation (e.g. auth-fix-1); pass it to search/explain. Results already sent in this session print as (already sent) — use your earlier copy.
2. A header saying index stale → run codebase-index update once; NO INDEX → codebase-index index.
3. Batch independent questions into one Bash call (cmd1; echo ---; cmd2).
4. # partial: on refs/impact means the list may be incomplete. For Owner.member it lists possible_call sites (calls on a variable the index cannot type), nearest first: check those few lines, do not grep the repo.
5. Before relying on evidence from earlier in a long task, run codebase-index verify --session <tag> --json.
6. Grep only when the index returns nothing relevant or for non-code text.