Back to Browse

Context MCP Server

Developer ToolsLow Risk10.0MCP RegistryLocal
Free

Server data from the Official MCP Registry

Call graphs, blast radius and API-breakage gates. Every answer reports its own completeness.

About

Call graphs, blast radius and API-breakage gates. Every answer reports its own completeness.

Security Report

10.0
Low Risk10.0Low Risk

Valid MCP server (0 strong, 2 medium validity signals). No known CVEs in dependencies. Imported from the Official MCP Registry.

4 files analyzed · No issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

How to Install

Install command not verified. See the repository for install instructions.

View repository

Documentation

View on GitHub

From the project's GitHub README.

ctx

Crates.io License: MIT

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, Java, 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:2368-2462  #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. At least 1005 undescended region(s) in this tree were not read; see `ctx doctor`.

That last line is the whole idea, and it does two jobs. It claims completeness for what ctx read, and it bounds that claim by counting what it never read — macro bodies and static/const initializers, whose contents are not parsed as code. A call hiding in one is absent rather than unresolved, so nothing else would have revealed it. 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 3.0× 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:

SCOPE: FILTERED (--exclude 'scripts/**'). Files outside this filter were never scanned and are NOT counted as blind spots below. Re-run without filters for whole-repo coverage.

## Internal recall — the number to trust
  1508/1585 = 95.1%   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.
     50  walk
     11  context
      4  est_tokens
      3  path

## Low-confidence zones (edges to distrust — grep to confirm)
  parity                           18% heuristic (11/61 edges)
  main                             7% heuristic (9/127 edges)
  refactor                         5% heuristic (1/20 edges)
  extract                          2% heuristic (4/235 edges)

That first line is the point, not boilerplate. This run excludes scripts/**, the Python tooling that writes and checks the figures in this file, because ctx's public surface is the CLI and the MCP server and a figure that moved every time a helper script changed taught only that the figure was noise. Excluding those files reads higher — 95.1% against 94.4% whole-repo — so ctx says so itself, naming the exact filter, and ctx doctor . with no flags still reports the unfiltered number. The excerpt is checked against live output including that line, so the narrowed scope cannot be published without it.

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:

ctxLSP-based (Serena)
setupone binary, grammars compiled ina language server per language, configured and running
startup~100 ms graph build, per queryserver warm-up, project indexing
determinismpure function of the source treedepends on server state, versions, build artifacts
uncertaintymarked per edge (~, *) + a miss censusresolved or absent, silently
coverage7 languages (today), one graph across all of themas 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:

grep -rn --include='*.py' --include='*.rs' --include='*.ts' \
  --exclude-dir={.git,node_modules,target,__pycache__,.venv,venv,dist,build} \
  '\bload(' .

On a small repo, grep wins. This repository, 14 source files:

grep -rn --include='*.rs' --exclude-dir=target '\bcoverage_report(' src/

194 tokens against ctx callers coverage_report's 215. Jump-to-definition is worse for ctx — grep -rn --include='*.rs' --exclude-dir=target 'struct Universe' src/ is 14 tokens against ctx def's 124. At this size the graph is overhead and you should use grep.

On a large repo it inverts. A 14,073-file tree:

"who calls X"ctx callersfair grepgrep linescallers ctx found
load4,01432,99478490
run44111,0172428
boot1,6934,7449831

3× to 25× fewer tokens. grep's cost scales with how common the string is; ctx's scales with how many call edges actually exist. boot is the weak case at 2.8× — worth knowing, because a tool that only ever reports its best ratio is advertising rather than measuring. run is the strong one: 242 matching lines, genuinely called from 8 places, and grep's output for it would not fit in most context windows.

But the size difference is not really the point — the two answer different questions. Same task, same repo:

grep:  src/mcp.rs:475:    query::coverage_report(&g, &unsupported, barg("explain"), false),
       src/query.rs:1548:pub fn coverage_report(
       src/query.rs:2177:        let out = coverage_report(&g, &[], false, false);

ctx:   mcp::dispatch  (src/mcp.rs:361)  → query::coverage_report
       query::tests::coverage_separates_internal_external_and_blind_spots  (src/query.rs:2856)
       query::tests::doctor_names_what_it_could_not_pin  (src/query.rs:2194)

grep returns lines containing the text — including the definition itself, mixed in with the calls. ctx returns the functions that call it. "What breaks if I change this signature" is answered by a list of callers, not a list of lines, so grep's output needs a second pass to read around each hit and work out which function it lands in. That pass is the part ctx has already done.

And grep is complete where ctx is not. ctx only reports edges it could resolve, so it undercounts — which is why every answer carries its own error bar:

completeness: 240 call site(s) named `load` could not be pinned
(scripts.regress 10, api 6, tests::progressive_integration 6, ...) —
this blast radius may be incomplete; grep `load` to confirm.

So: grep is complete and imprecise; ctx is precise and tells you where it isn't. They compose. ctx narrows 242 lines to 8 callers and then names the places you still need grep — which is a better division of labour than either tool doing the whole job.

Install

No Rust toolchain required — prebuilt binaries for macOS, Linux and Windows:

# macOS / Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Eagle-Logic/context/releases/latest/download/code-context-installer.sh | sh

# Windows (PowerShell)
irm https://github.com/Eagle-Logic/context/releases/latest/download/code-context-installer.ps1 | iex
# Homebrew
brew install eagle-logic/tap/ctx

To try it without installing anything, if you have node:

npx @eagle-logic/ctx doctor .

The npm package wraps the same prebuilt binaries as the installers above, so it is the same tool, not a reimplementation. It exists because an agent evaluating ctx mid-session can run npx but cannot install a Rust toolchain.

There is also a Dockerfile, which runs the MCP server over stdio against a mounted tree. No image is published, and it is slower and larger than every route above — it exists because MCP directory checks start a server in a container:

docker build -t ctx-mcp .
docker run --rm -i -v "$PWD:/workspace:ro" ctx-mcp

With a Rust toolchain (1.90+):

cargo install code-context        # the binary it installs is `ctx`

# or from source
git clone https://github.com/Eagle-Logic/context
cd context && cargo install --path .

Single binary, no runtime dependencies — the tree-sitter grammars are compiled in. Prebuilt for x86_64/aarch64 macOS, x86_64 Linux (gnu and static musl, so it drops into a distroless or scratch container), and x86_64 Windows.

macOS: use the installer script or Homebrew above. The release archives are not code-signed, so a .tar.xz downloaded through a browser gets quarantined by Gatekeeper and refuses to run until you clear it (xattr -d com.apple.quarantine ./ctx). The curl | sh path doesn't set the quarantine attribute and is unaffected.

The queries

Start here: ctx core to orient, ctx def to find a symbol, ctx context to work on it. That sequence is the tool. Everything below is a specialisation of it, and the whole-repo map at the bottom is measured at 42× the cost of core for the same orientation job.

# Everything needed to edit a symbol, in one call (def + types + callees + callers)
ctx context streamChat --max-tokens 4000
ctx context streamChat --include-source   # + the source, so it answers alone

# Who calls this? (resolved reverse call edges — the blast radius)
ctx callers basename

# How does execution get here? (transitive call tree, not one hop)
ctx trace decode_step --depth 4
ctx trace decode_step --reverse       # everything that reaches it

# The shortest call path between two symbols, hop by hop
ctx path main flush_kv_cache

# Where is a symbol defined? (jump-to-def without knowing the module)
ctx def SteerConfig
ctx def 'Type::method'                # qualified to disambiguate

# Breaking-change gate: public API removed/changed since a ref + who breaks
ctx changed --api --since main
ctx changed --api --strict --since main   # exit non-zero on a removal — for CI

# Plan a module move, then prove it landed
ctx move-plan native::gate native::routing::gate
ctx move-verify native::gate native::routing::gate

# Impact map of your current diff: changed modules + deps + callers
ctx changed                           # working tree vs HEAD
ctx changed --since main

# Structural diff between two refs (review a whole branch/PR)
ctx diff main..feature                # changed modules + who they break
ctx diff main..feature --api          # breaking API changes across the range

# Cross-language parity: is the Rust port faithful to the Python source?
ctx parity research/gate.py src/gate.rs
ctx parity research/gate.py src/gate.rs --aliases py-rust   # bridge __init__→new
ctx parity research/gate.py src/gate.rs --strict            # non-zero if missing

# Coverage report: internal call-graph recall + exactly what went unpinned
ctx doctor
ctx doctor --explain                  # full per-name census

# The modules that matter most (dependency centrality; --churn weights by volatility)
ctx core
ctx core --churn

# Wider views. `subtree` is the one to reach for; `map` is a cold-start or
# human-reader tool, not an agent's opening move — see "Maps, when you want them"
ctx subtree core::inference           # one module + upstream + downstream
ctx modules                           # module list + dep edges only
ctx map --view skeleton               # whole repo, architecture only
ctx map --max-tokens 8000             # hard cap: reduces detail, then prunes
ctx map -o CODEBASE_MAP.md            # write it out (goes stale on the next edit)

# Scoping (global, repeatable)
ctx map --lang code                   # code only, no prose
ctx map --exclude 'docs/archive/**'   # vendored trees, dead code

# Show each edge's call sites in map/subtree/callers (context always shows them)
ctx callers basename --verbose-edges

# Machine-readable
ctx map --format json

# Print the agent instructions block, measured for this repo
ctx snippet >> AGENTS.md              # or CLAUDE.md, .cursorrules, …

Every command except parity takes a repo path as its last positional argument, defaulting to .; parity takes a source and one or more targets instead. See EXAMPLES.md for each of these run against a real repo, with output.

Scoping the scan

--exclude '<glob>' and --lang are global, repeatable flags. Vendored trees, archived docs and dead code are usually tracked, so .gitignore will not exclude them: --exclude 'docs/archive/**'. And because a docs tree can dominate a code map — 78% of one 720-module repo's skeleton view — --lang code restricts the scan to code only, cutting that map from ~169k to ~35k tokens.

Module names are unique. They derive from paths, so src/lib.rs and src/main.rs both want to be crate, and a native/README.md collides with the src/native/mod.rs it documents. Because resolution indexes by name, a collision used to make one module unreachable and silently drop its reverse edges. Code now keeps the bare name, prose is renamed to name@stem, and every rename is reported on stderr.

ctx supported-exts prints every extension ctx parses, one per line, and --code drops Markdown. It is the machine-readable form of the (supported: …) line in ctx doctor, and it exists so tooling derives the set instead of restating it — bench/run.sh builds its grep --include list from it. A restated copy is how the benchmark harness came to measure JavaScript repos without opening their .js files.

Execution tracing

callers answers "who calls this" for exactly one hop. trace walks the call graph transitively — forward (what runs underneath a symbol) or --reverse (everything that reaches it) — cutting cycles and repeated subtrees with a marker instead of expanding forever. path <from> <to> gives the shortest route between two symbols:

$ ctx path main coverage_report
# path: main → coverage_report  (5 hop(s))
~ heuristic edge (verify) · * one branch of a dispatch fan-out

crate::main  [src/main.rs:443]
  → mcp::run  [src/mcp.rs:14]
    → mcp::handle_method  [src/mcp.rs:44]
      → mcp::tools_call  [src/mcp.rs:132]
        → mcp::dispatch  [src/mcp.rs:146]
          → query::coverage_report  [src/query.rs:1420]

"How does a request get from main to here" is one command rather than a grep chain. Both mark each hop's confidence and report call edges that leave the resolved graph, so a trace never quietly implies more certainty than it has.

How callers reports its own limits

callers never claims completeness. Reverse edges exist only for calls that resolved, and resolution drops rather than guesses, so the result is a floor. Three loss channels are knowable and reported in band:

  • Ambiguous name — more than one definition, so a call through an opaque receiver cannot be pinned to one of them. Prints INCOMPLETE with the definition count (ambiguous_name in JSON). Computed from the bare name, so qualifying the query cannot silence it.
  • Suppressed ubiquitous name — get, open, push, len and friends are never indexed, including a project-defined method that merely shares the name. Prints NOT INDEXED, because an empty result there carries no information at all (suppressed_common_name in JSON).
  • Measured misses for this name — the closing completeness line counts call sites bearing this name that ctx could not pin, and says where. When it reports none, the confirming grep can be skipped.

The first two set lower_bound: true, and so does a third: an undescended region that mentions this name. Rust macro bodies and static/const initializers are parsed as items and never read as code, so a call inside one is absent rather than unresolved. The check is textual — these regions were never parsed, so whether a spelling appears in them is the only question answerable about their contents, and it is exactly the grep the answer recommends. A macro that pastes a name together never spells it, so this is a floor like everything else here.

Both counts ride in the JSON: undescended_regions is the tree-wide total that ctx doctor reports, and undescended_regions_mentioning_query is the one that sets the flag. The per-name count is deliberate — tree-wide, the flag was true on every Rust repo, and a boolean that is always set carries no more information than one that is never set. The absence of a flag means "no known reason to distrust this" — not a guarantee: a call through a function-local import can still be missed.

That module-level channel is not uniform across languages, which is worth stating plainly. Python, TypeScript and Go each synthesize a module-level container, so X = make() written outside any function is a real call site. Rust does not: the initializer of a static or const is parsed as an item but never walked for calls, so pub static X: u32 = make(); contributes nothing. It is not an unresolved call site — it is absent — so it cannot lower recall. Rust is the only supported language with a live instance of this channel, and every such initializer containing a call is counted under "Not descended into" by ctx doctor. The calls are still missing; they are no longer missing silently. Before changing a signature, run the rg command ctx prints. This matters because callers is the pre-signature-change safety check, and "no callers" reads as "safe to change".

context, trace, and path close with the same measured completeness line.

Spans and content hashes

def, callers and context report a span and a content hash, not just a start line:

extract::Universe   [struct]   src/extract/mod.rs:1066-1083  #85eadbaee90b

The end line is the useful half. With only a start line an agent opens the file and guesses where to stop, which is how reading a 20-line struct turns into reading the 1,900-line module it happens to live in. The span says exactly what to read.

The hash covers the item's full source span, body included, and is position-independent — inserting a comment above a function does not change its hash. Two uses, both about not re-reading: an agent holding a span can tell it is unchanged without opening the file, and two identical spans are visibly identical without comparing text.

A one-line item reports :12, not :12-12. Both appear in --format json as end_line and hash alongside the existing line, so the addition is non-breaking for machine consumers.

Naming

def, callers, context, trace, and path all accept a bare name (to_config) or a qualified one (SteerOverride::to_config, pkg.mod.fn); a bare name lists every match so overloads are disambiguated by module + signature. callers is the inverse of the per-function → callee edges in map/subtree: it reports only resolved call sites, so it's precise where a text grep floods on a common method name. subtree accepts a full module name (core::inference, pkg.utils.validation) or any trailing suffix (inference).

More on the flagship commands

context is the agent-native one: a single call returns the definition, the type definitions referenced in its signature, its callees, and its callers — trimmed to --max-tokens — so an agent gathers full editing context for a symbol without a map→def→callers→subtree dance.

Every edge in it carries where the call happens, and the two directions are named rather than left to be inferred:

## Calls — dependencies (5, sites in src/query.rs)
- Totals::add  @ 1775
- coverage_report::pct  @ 1795, 1796
- Resolution::one  @ 1316, 1321, 1345-1349

## Callers — dependents (3)
- extract::build_universe  (src/extract/mod.rs:1094-1164  #b2e4439cb24a)  ~  @ 1153
- extract::candidates  (src/extract/mod.rs:641-741  #5bd2160c79a5)  @ 652, 686, 722

A site is a span, not a line — 1345-1349 is a call spread over five lines, and the reader needs all five. Edges dedup by callee, so one edge lists every site behind it; past four the rest become a count, because a symbol called from sixteen places in one function does not need sixteen line numbers to be found. The ~ is the same confidence mark the rest of the tool uses; context used to drop it, which made a guessed edge read exactly like a proven one.

Sites cost about 23% of a bundle's tokens (2,902 → 3,587 across eight symbols in this repo, len/3, same tree through both renderers). That is the whole of the increase, it is the thing being paid for, and it is confined to this command: map, subtree, callers, trace, core, modules and def are byte-for-byte unchanged, and show sites only under the global --verbose-edges.

--include-source goes one further and inlines the definition's own source plus the full body of every type in its signature, so the bundle answers on its own rather than telling an agent which file to open next:

$ ctx context pick --include-source
## Signature types
- a::Mode [enum]  src/a.rs:1  #ff2c9d1e4b70
    pub enum Mode { Fast | Slow }
```rust
pub enum Mode { Fast(u8), Slow }
```

The enum is the case that matters. A model shown Mode with no variants will invent a third one; shown two, it cannot. Note that the payload (Fast(u8)) survives only in the materialized source — the rendered signature collapses it — which is exactly the gap the flag exists to close.

Callees and callers stay pointers under the flag, deliberately: inlining them would spend the budget on the least relevant material in the bundle, and their spans already say what to read if you want it. A type that encloses the definition is listed but not materialized — a method returning Self, or any builder, names its own container, whose body already contains the definition printed above it. Either omission is stated in band rather than made silently.

This is also the shape for using ctx without an agent — one query before you paste a question into a model, instead of dumping files and hoping it picks the relevant part. That is worth more the smaller the model.

changed turns a diff into an impact map: it runs git diff (working tree vs HEAD, or vs --since <ref>, including untracked files), maps changed files onto modules, and renders those modules plus their upstream dependencies and — the point — their downstream callers, i.e. everything a review should re-check. An unborn HEAD or a clean tree is handled without error.

diff <A>..<B> is changed between two arbitrary refs — the whole-branch / whole-PR view. It maps the file changes onto B's module graph (built in a throwaway worktree when B is a ref; the working tree when B is omitted, as in ctx diff main), so the topology reflects the target state. --api runs the breaking-change surface diff across the same range. A...B is accepted and treated like A..B.

parity flattens each side into a bag of members keyed by (container, canonical-name, role) — collapsing camelCase/snake_case/ PascalCase and treating a Rust impl Type { fn m } the same as a Python class Type: def m — then reports members missing from the port, arity drift (receiver-excluded param count), dropped internal calls, moves (name matches, container differs), and additions. Multiple targets are compared as a union (a Python file that split into several Rust modules). It's deterministic and structure-only — never semantics — and it leans on the port preserving names, so it's a faithfulness check for mechanical ports, not a similarity score for rewrites.

Because it leans on names, canon() alone bridges most Python↔Rust dunder renames for free (it strips the underscores, so __len__↔len, __eq__↔eq, __hash__↔hash, __next__↔next already align). For the renames it can't — chiefly __init__→new, plus __str__→fmt/to_string, __getitem__→index, __iter__→into_iter — pass --aliases py-rust, or --aliases py-go for Go's conventions (__str__→String, __eq__→Equal). Every alias-based match is reported in its own Aligned via alias section, never silently folded, so the fuzz you opted into stays visible.

Renamed containers are inferred. Container is part of every member key, so renaming a type invalidates all of its members at once — and renaming the main type is the normal case in a port, not an edge case. parity pairs containers by shared member sets (requiring at least two shared members and a majority of the smaller container, so unrelated types are never paired), and container and member renames compose: TriStateRouter.__init__ → IntentGate.new needs both, and neither alias alone finds it. Every inferred pairing is listed under Inferred container renames — a wrong pairing must never masquerade as a clean parity result — and --alias Old=New overrides inference when the port shares too few names to infer from.

core ranks modules by dependency centrality — PageRank over the module graph, so the modules everything else leans on float to the top. It's the "where's the heart of this codebase" answer for an unfamiliar repo. This is the one command that overlaps what other repo-map tools do, and it's deliberately a small part of the surface.

Maps, when you want them

In our own use, map is the least useful command here — including with --max-tokens. It ships because it's occasionally the right tool, not because it's the point, and it's listed last for a reason.

The problem isn't the output; it's the shape of the transaction. A map is breadth paid for up front, before you know which part you'll need, and it's stale the moment you edit. In practice an agent spends that budget once and then still runs ctx context on the one symbol it actually touches — which would have answered the question on its own, current at the moment it was asked. Budget fitting bounds the cost but doesn't change the economics: a cheaper blob is still a blob.

Where it does earn its place: a genuine cold start on an unfamiliar repo, a committed CODEBASE_MAP.md for humans, or feeding another tool via --format json. For everything else, reach for context, trace, callers, or subtree — a scoped answer beats a ranked summary, which is the whole argument of this README.

map and subtree take --view to scale detail to informational need — each level adds a whole category, so token spend buys precision, not noise:

viewcontentsa 419-module Rust workspace
skeletonmodules, deps, re-exports, type names79 KB (~19k tok)
interface+ public signatures, struct fields, enum variants301 KB (~75k tok)
full (default)+ private items and call edges451 KB (~112k tok)

On a mid-size repo (70 files) skeleton is ~3k tokens, which is cheap enough that the cost isn't the objection — the objection is that it's the wrong shape. Rust visibility is pub-based; Python uses the underscore convention (dunders like __init__ count as public); TypeScript uses the export keyword (public class methods are interface, private/# members are dropped). Trait methods and trait impls are always interface.

map --max-tokens <N> is a hard cap. It first reduces detail, emitting the richest view at or below --view whose (~len/4) token count fits, and reports the view it chose on stderr. When even skeleton is over budget, detail is exhausted and the only remaining lever is dropping modules, so the least-central ones are pruned (PageRank, the same ranking core uses) until the map fits. The output states what was omitted, and dependency edges still name pruned modules — that name is what to feed subtree/context next.

Items inside a kept module are never truncated: you get fewer modules, each still whole. Only when a single module alone exceeds the budget does ctx emit an over-budget map, and it says so on stderr. Without --max-tokens, nothing is ever pruned.

Output shape

## prelude  (src/prelude.rs)
deps: core::inference
reexports: core::inference::Engine, core::inference::build as make_engine

## agent  (src/agent.rs)
deps: encode
- pub struct Tracked { pub id: usize, pub sig: Vec<f32>, pub pos: (f32, f32) }  [L64]
- pub trait Environment  [L54]
  - fn reset(&mut self) -> Percept  [L55]
  - fn step(&mut self, action: Action) -> Percept  [L56]
- impl Agent  [L192]
  - pub fn observe(&mut self, action: Option<Action>, p: &Percept)  [L204] → Agent::register_type, dist, encode::cosine
  - pub fn drive(&mut self, env: &mut dyn Environment)  [L221] → world::Grid::step*, sim::Replay::step*

Two markers qualify an edge. A trailing ~ means the target was inferred from a receiver whose type is not written in the source — trust it less. A trailing * means the edge is one branch of a dynamic-dispatch fan-out (dyn Trait, impl Trait, a bounded generic, a TS interface, a Python base class): every implementation that could run is listed, and exactly one of them does.

Each item also carries the first line of its doc comment (Rust ///, Python docstring) as a trailing — summary, so a signature map doubles as a labeled one at negligible token cost:

- pub fn to_config(&self, n_predict: i32) -> SteerConfig  [L317] → NativeSteerInstruction::to_config  — Build a SteerConfig from the explicit knobs (gate bypassed).

Agent integration

Two ways in. The CLI is the one to reach for first, and it is what this project's author uses exclusively.

The CLI, via an instructions file

ctx snippet prints a "Codebase Discovery" block measured for this repo — its module count, token cost, and call-resolution rate are read off your actual source, so the guidance is derived rather than asserted. Append it to whatever file your agent reads:

ctx snippet >> AGENTS.md        # or CLAUDE.md, .cursorrules, .windsurfrules …

The block names no vendor. It describes commands and a protocol, so it works with any agent that can read a file and run a shell command. The block is fenced by markers, so regenerating replaces it in place instead of appending a second, contradictory copy.

It teaches a query-first protocol: run ctx context <name> when you're about to touch a symbol, ctx callers before changing a signature, ctx trace/ctx path to follow control flow instead of grepping, and only read raw source for implementation bodies. Reaching for a whole-repo map is the exception, not the opening move.

MCP server, if you want typed tools

Documentation truncated — see the full README on GitHub.

Reviews

No reviews yet

Be the first to review this server!