Surgical context for coding tools—less haystack, more needle.
Modern assistants fail in large codebases because they see too much or the wrong thing. Cartographer builds the right context at the right time: live code maps, symbol graphs, and minimal excerpts that let agents reason like seasoned maintainers.
Why now
Context windows grew; signal didn’t. Stuffing 100s of files is wasteful and fragile. We flip it: build a targeted working set—fast to compute, cheap to send, and specific to the task.
The thesis
Coding tools should compose insights from LSPs, ASTs, symbol graphs, and edit history to deliver a surgical context bundle. Less haystack, more needle.
Surgical context
A compact, task‑scoped package: callee chains, type contracts, config edges, relevant diffs, and the handful of files that matter—ranked, deduped, and trimmed.
# Example: “Implement UserService.refreshToken()”
context/
├─ focus/ # must-see snippets
│ ├─ user_service.ts:L88-142
│ └─ oauth_client.ts:L10-44
├─ calls/
│ ├─ user_repo.ts → db.ts
│ └─ oauth_client.ts → http.ts
├─ contracts/
│ ├─ IUserRepo.refreshToken(userId: string): Token
│ └─ IOAuthClient.refresh(token: Token): Token
├─ config/
│ └─ env.yaml (OAUTH_*)
└─ diffs/
└─ recent/ feature/refresh_tokenWhat Cartographer does
We maintain a live semantic index of your repo, then assemble a minimal, ranked bundle for each task: the few snippets and artifacts that unlock the answer.
1) Map
Ingest repo via LSP & parsers; build cross‑refs, call graphs, ownership maps, and change history.
2) Select
Given a task, traverse symbols to pick the smallest working set that still preserves invariants.
3) Pack
Trim to budget with contract summaries, snippet slicing, and deduped paths; add rationale.
4) Serve
Expose to agents/IDEs via API: ContextBundle + Evidence → fewer hallucinations, better edits.
Why it matters
Most failures in large repos are context failures: wrong file, missing invariant, or invisible side‑effect. Surgical context reduces retries, token burn, and review drag—letting assistants behave like focused teammates, not tourists.
Roadmap
Alpha
Python + TypeScript; CLI & API; VS Code bridge; GH Actions indexer.
Beta
PR reviewer with surgical bundles; diff‑aware test selection; repo heatmaps.
1.0
Multi‑repo graphs; policy gates; organization‑wide symbol search.