ctx

The binary is ctx. The crate is code-context (ctx was taken on crates.io in 2017).

A queryable code graph for coding agents. Not a map you paste at boot — a set of queries an agent runs mid-task: who calls this, how does execution get here, what breaks if I change it, what must a move touch, does my port still match the original.

One Rust binary. Tree-sitter for Rust, Python, TypeScript/TSX, JavaScript/JSX, Go, and Markdown. No language servers, no embeddings, no index to warm. The graph is a pure function of the source tree — same code in, same answer out — and it builds in ~100 ms, so every query runs against current source.

$ ctx callers resolve_call
1 caller(s) of 'resolve_call':

extract::Walk::rec  (src/extract/mod.rs:2265-2359  #ab0418a77d9f)  → resolve_call

completeness: no call site named `resolve_call` went unresolved anywhere in this
tree — this blast radius is complete to the limit of what ctx parses.

That last line is the whole idea. Every other code graph tells you what it found. ctx tells you what it missed — per edge, in aggregate, and with the grep list to check it yourself.

It matters because the failure mode of a code graph is silent. A blast radius that comes back short reads exactly like a blast radius that is complete, and an agent cannot tell the difference — so it changes the signature and ships the break. Every tool in this space has gaps; this one is built so you can enumerate them.

→ EXAMPLES.md — ten commands run against this repo, verbatim output, including the parts where ctx reports its own limits.

→ BENCHMARK.md — the same claims re-run on six public repositories pinned to exact commits, reproducible with ./bench/run.sh. Including the row where it finds a limitation in ctx.

→ What the integration itself costs — ctx's own MCP tool definitions sit in every turn whether a tool is ever called or not, which makes them 2.2× the standing cost of the CLI instructions block. That is the shape this project objects to, measured on itself.

Four things you won't find elsewhere

1. Every edge tells you how much to trust it

Every static analyzer guesses. ctx is the one that says where.

An edge backed by a resolved import, a path, a self receiver, or a declared type is unmarked — rely on it. An edge inferred from an opaque receiver (expr.method(), where nothing in the source states the type) is marked ~. A branch of a dynamic-dispatch fan-out is marked *. And ctx doctor names every callee it could not pin at all, with counts:

## Internal recall — the number to trust
  1355/1422 = 95.3%   of call sites that could be internal, ctx pinned this many.

## What ctx missed (callee names that exist here but went unpinned)
grep these; every other edge in the map is one ctx could prove.
     45  walk
      9  context
      3  path
      2  est_tokens

## Low-confidence zones (edges to distrust — grep to confirm)
  parity                           18% heuristic (11/61 edges)
  refactor                         5% heuristic (1/20 edges)

The recall number comes with the exact grep list for everything it doesn't cover. The denominator is honest too: a call into std or a third-party crate is excluded, because no internal edge could exist for it however good the resolver gets — and that classification is by evidence (is this name defined anywhere under the root?), not a hardcoded list.

Heuristic method attribution is also language-scoped. A unique method name is evidence only within one language; across languages it is coincidence, so tok.apply_chat_template(...) in Python is never attributed to a Rust method of the same name. Before that guard, 45 of 50 reported callers of that name were artifacts and ~18% of module dep edges were impossible Python→Rust edges — which then distorted core's ranking.

The honest bit isn't that coverage is high. It's that the gaps are enumerable.

That property is not decoration — it is how this tool gets built. Go support went from 36.8% to 89.6% internal recall on go-chi/chi in six steps, and every step was a class of call site the census had already named by count: package scope spanning files, constructor return types, calls leaving through an external import, a func literal shadowing its enclosing scope, the /vN in a module path binding the wrong package name, and method chains. Not one of those was visible in the aggregate number. Each was one line in What ctx missed, with the grep to confirm it.

A tool that reported only "36.8%" would have told you it was bad without telling you why, which is the position every other code graph leaves you in.

2. changed --api — a breaking-change gate that names who breaks

Builds the public API surface at a base ref (in a throwaway detached worktree) and in the working tree, then reports what was removed or whose signature changed — each with the callers it breaks.

$ ctx changed --api --since HEAD~1
# API changes vs HEAD~1
0 removed, 4 changed, 7 added.

## Changed signature — potentially breaking
- query::coverage_report  [fn]  (src/query.rs:1420)
    was: pub fn coverage_report(g: &Graph, unsupported: &[(String, usize)], json_out: bool) -> String
    now: pub fn coverage_report(g: &Graph, unsupported: &[(String, usize)], explain: bool, json_out: bool) -> String
    callers (5): mcp::dispatch, query::tests::coverage_separates_internal_external_and_blind_spots, …

--strict turns it into a CI gate, and fails only on removals. That asymmetry is deliberate. A removal is unambiguous: nothing can call what is gone. A signature change might be an added optional parameter or a new struct field — routine, compatible work — and ctx is structural, with no type resolution, so it cannot tell that from a changed parameter type. Failing on both was tried and would have blocked ordinary additive commits on the first real repo it met; a gate that cries wolf gets switched off, which is worse than no gate. So signature changes are reported, and under --strict say explicitly that they were reported and not failed.

Treat it as a tripwire that surfaces an unintended removal in review, not as a semver authority — a language-specific tool with a type system (cargo-semver-checks, apidiff, japicmp) is stricter within its language. The trade ctx makes is breadth: one gate across Rust, Python, TypeScript, JavaScript and Go in a polyglot repo.

# .github/workflows/ci.yml — PR-only; fetch-depth 0, the default shallow clone
# has no merge base.
- uses: actions/checkout@v7
  with: { fetch-depth: 0 }
- run: cargo install code-context --locked
- run: ctx changed --api --strict --since "origin/${{ github.base_ref }}"

This isn't a context tool. It's CI.

3. move-plan — a refactor oracle, not an actuator

move-plan <from> <to> emits every site a module relocation must touch; move-verify checks the result. ctx never writes source files.

ctx move-plan native::gate native::routing::gate   # file move + every import rewrite
# ... agent applies the edits ...
ctx move-verify native::gate native::routing::gate # exits non-zero if anything is orphaned

The reasoning: an agent can already make edits cheaply and precisely. What it cannot do is know it found every site, or prove nothing was orphaned. The scarce thing is ground truth, not typing — and staying read-only keeps ctx free of partial application and undo semantics.

Scope is bounded by what ctx can prove. Moves ride on import and link resolution — path arithmetic, deterministic, non-heuristic — which is ctx's strongest signal, so the site list is exact for the languages it parses. Dependents reached only by receiver inference have no literal string to rewrite and are listed separately as unverified, never mixed in with real sites. Rust mod declarations are not imports, so the plan names them as a required manual step rather than omitting them silently. Renaming a method is deliberately not offered: it would ride on receiver inference, which resolves a minority of call sites, and a plan built on that would silently miss some.

4. parity — cross-language port fidelity

Porting Python to Rust, or TypeScript to Python? parity answers "is this port a faithful structural copy?" Because the item model is language-neutral, a source module and its port are two renderings of one skeleton.

$ ctx parity research/gate.py src/gate.rs --aliases py-rust
# ctx parity — source → port
source 6 members · target 5 · aligned 5 (83% of source) · 1 via alias

## Missing in port (1) — in source, no counterpart in target
  fn   Gate.record                  gate.py:18

## Arity drift (1)
  fn   Gate.score               source=2 → port=1   gate.py:7

## Aligned via alias (1) — matched through a rename rule, not exactly
  fn   Gate.__init__  →  Gate.new   (via init → new)

parity: 5/6 source aligned · 1 missing · 1 arity · 0 call · 0 moved

A dropped method, a dropped parameter, and the __init__→new rename, in one command. --strict exits non-zero on any missing member. I'm not aware of another tool that does this. It might be more or less useful depending on your specific languages and abstractions.

"How is this different from aider's repo map?"

Aider's repo map — and the MCP servers that repackage it, like RepoMapper — compresses a repository into a ranked blob that gets injected at the start of a session, sized to a token budget. It's a good answer to "what is this codebase" for a model that has seen none of it.

ctx answers a different question. Once the agent is in a task, it doesn't need the repo ranked — it needs specific facts: trace, path, callers, context, changed --api, move-plan, parity. Those are queries mid-task, not a blob at boot. Ranking is one small command here (ctx core), not the product.

The nearer comparison is Serena, which does LSP-backed symbol navigation. Against it, ctx trades semantic precision for two things:

| | ctx | LSP-based (Serena) | |---|---|---| | setup | one binary, grammars compiled in | a language server per language, configured and running | | startup | ~100 ms graph build, per query | server warm-up, project indexing | | determinism | pure function of the source tree | depends on server state, versions, build artifacts | | uncertainty | marked per edge (~, *) + a miss census | resolved or absent, silently | | coverage | 6 languages (today), one graph across all of them | as many as you install servers for |

If you need type-perfect resolution inside one language, use an LSP. If you want the same graph across a polyglot repo with nothing to install and answers that state their own confidence, that's this.

ctx does ship the boot map too (ctx map), so you can have it if you want it. But we'll say plainly what dogfooding taught us: it's the least useful thing here. More on why.

"Why not just grep?"

Often you should. Here is the measurement, including where grep wins.

Counting tokens. Every figure in this README is ctx's own estimate — len/3, the same one --max-tokens and --metrics use. Recompute with a real tokenizer and you will get different absolutes; the ratios are what the argument rests on, and they come from one estimator on both sides. len/3 is also conservative for source code, which tokenizes closer to 3.5–4 characters per token, so if anything the grep figures below understate the gap.

The grep below is the one a competent agent would actually write — call syntax, language-filtered, skipping the same directories ctx skips — not a bare `grep -rn name