ctx

name	ctx
description	Codebase intelligence via the indexed ctx CLI. Use when exploring an unfamiliar codebase, locating symbols or their callers, checking for existing implementations before writing new code, enforcing architecture rules, or scoring the quality impact of changes.

ctx — code intelligence

ctx maintains a symbol-level index of this codebase (.ctx/codebase.sqlite). Prefer its queries over grep: they resolve symbols, call graphs, and structure instead of matching text.

All quality commands share one exit-code convention: 0 clean, 1 findings, 2 operational error. Treat exit 1 as content, not failure.

Keep the index fresh

ctx index            # incremental; run after pulling or large edits
ctx index --force    # full rebuild (schema changes, corruption)

Orient in the codebase

ctx map --budget 2000        # token-budgeted architectural overview
ctx query find <name>        # locate symbols by name
ctx query callers <fn>       # who calls this?
ctx query deps <symbol>      # what does this depend on?
ctx query impact <symbol>    # blast radius of changing it
ctx source <symbol>          # exact source of a symbol
ctx explain <symbol>         # signature, doc, relationships
ctx search "<query>"         # hybrid name/text search

Avoid writing duplicate code

ctx similar <symbol>         # near-duplicates of one function
ctx duplicates --against main  # new near-duplicate pairs in your change

Run ctx similar before implementing a helper that sounds generic — an implementation may already exist.

Quality gates

ctx check --against HEAD --json   # architecture rules (.ctx/rules.toml)
ctx score --against main --fail-on "check_violations>0,new_duplication>0"
ctx hotspots                      # churn x complexity refactoring targets

Recommended agent workflow

1. Start: ctx map --budget 2000 to orient (the SessionStart hook does this automatically when installed).
2. Before writing code: ctx query find / ctx similar to find prior art; ctx query impact before refactoring shared symbols.
3. After edits: ctx index then ctx check --against HEAD --json; fix any violations immediately.
4. Before finishing: ctx score --against main and address regressions (rising complexity, new duplication, rule violations).

Never edit .ctx/rules.toml (project policy) or the generated hook scripts; regenerate the latter with ctx harness init.