Quick start → · Benchmark results → · Why not graph-based? → · Architecture → · ADRs →

ContextAtlas ships two equivalent paths — CLI and Claude Code Skills — both producing the same atlas.json. See Quick Start for setup.

The Problem

Claude Code currently learns your codebase by brute force. Every session starts fresh. Every "where is X?" triggers multiple grep calls. Every "what depends on Y?" is another flurry of file reads. On a mid-sized codebase, answering a single architectural question can consume 40+ tool calls and 100,000+ tokens before Claude has enough context to reason well.

Worse: the architectural intent that governs your code — the ADRs, the design decisions, the "we did it this way because" — is invisible to Claude. The rule that OrderProcessor must be idempotent lives in docs/adr/. When Claude proposes a change, it has no way to know that constraint exists.

Yesterday's understanding doesn't carry to today. Every conversation starts from zero. Your ADRs, your commit history, your test coverage — none of it is on the agent's table.

What if expensive understanding happened once, at index time, and every query became a dictionary lookup?

That's ContextAtlas.

What ContextAtlas Is

ContextAtlas is an MCP server that gives Claude Code a curated atlas of your codebase — fusing LSP-grade structural precision with architectural intent extracted from your ADRs, docs, and git history, delivered to Claude in single-call context bundles.

Every bundle Claude receives combines four independent signals about a symbol:

1. Structural data from the language server — definition, references, types, diagnostics. Compiler-grade precision.
2. Architectural intent from your ADRs, READMEs, and design docs — structured claims extracted by Opus 4.7 at index time, keyed to specific code symbols.
3. Historical context from git — recent commits touching the symbol, hot/cold indicators, co-change patterns.
4. Test associations — which tests reference the symbol, where coverage lives.

One MCP call returns all four, fused. No ADRs in your repo yet? You still get LSP + git + tests in one call instead of fifteen — a meaningful baseline improvement. Add ADRs and the bundles get richer. The architecture is designed so any subset of signals produces value.

Given an ADR stating that OrderProcessor must be idempotent, a call to get_symbol_context("OrderProcessor") returns:

SYM OrderProcessor@src/orders/processor.ts:42 class
  SIG class OrderProcessor extends BaseProcessor<Order>
  INTENT ADR-07 hard "must be idempotent"
    RATIONALE "All order processing must be safely retryable."
  INTENT ADR-12 soft "prefer async base class for new processors"
  REFS 23 [billing:14 admin:9]
    TOP ref:ts:src/billing/charges.ts:88
    TOP ref:ts:src/admin/orders.ts:12
  GIT hot last=2026-03-14
    RECENT "Fix idempotency bug in retry path" a3f2c1d
  TESTS src/orders/processor.test.ts (+11)

When Claude is asked to modify OrderProcessor, it sees the idempotency constraint before proposing changes — not after a user review catches the violation.

Who this is for. ContextAtlas is built for the average developer using Claude Code on real codebases — not just engineers at large orgs working on 500,000-file monorepos. Token-burn reduction scales with codebase size — dramatic on a 200-file framework, modest on a 30-file library. But architectural intent capture is size-invariant. A 30-file library can have meaningful architectural decisions worth surfacing, and Claude respecting them matters just as much as on a larger codebase.

Beyond tokens: a design-alignment case study

Efficiency and quality are necessary but not sufficient. The substantive value of context-grounding shows up in design choices on non-trivial code-change tasks.

A/B trial during v0.3 development. Identical 3-paragraph prompt across two ContextAtlas clones: implement a known bug fix — locate the bug, design and implement the fix, write tests, document via ADR. The only setup difference: MCP availability.

Arm B's approach landed in main. Both arms functionally fixed the bug at similar wall-clock and token cost. The substantive difference was alignment with project design thesis — the CA-aided arm could read the relevant ADR + prior architectural work from the atlas, and made a choice that fit. The vanilla arm couldn't see that context and chose an approach that worked but fought the architecture.

Arm A's substantive consideration wasn't lost — captured as future-work investigation trigger. The recall-vs-precision tradeoff is preserved.

Full synthesis at v0.3 Round 3 dogfood evidence.

N=1 trial; this is anecdote, not benchmark. The systematic benchmark suite (hono / httpx / cobra) measures efficiency and quality (see §The Numbers below). This A/B trial measures the substantively-distinct design-alignment axis — which doesn't fit benchmark-suite methodology (every code-change task is repo- specific) but is the substantive value proposition for cohort developers building on real codebases.

The Numbers

We benchmark ContextAtlas against baseline Claude Code on three repositories chosen to reflect realistic developer workloads:

Methodology. 24 prompts per repo, 6 task buckets, blind manual grading, pre-registered rubric, no cherry-picking. Full methodology in RUBRIC.md.

Efficiency: 50-71% tool-call reduction on architectural prompts

Phase 5 reference run on hono, six pre-registered prompts:

The headline case: h4-validator-typeflow ran 7.3× cheaper ($2.95 → $0.52) at equivalent answer depth. CA opens with the governing ADR by number; the baseline reconstructs the architecture from source. Tie and trick buckets (h5, h6) show CA net-negative as the rubric predicted — CA over-engineers on questions where architectural intent doesn't carry load. Bucket-aware methodology surfaces these expected cases rather than burying them.

Cross-language replication: the same architectural-intent win mechanism holds on Python (Phase 6 — httpx) and Go (Phase 7 — cobra). Phase 8 re-ran the locked prompt sets against v0.3-sharpened atlases at the same pinned target SHAs: 45-72% token reduction on architectural-intent prompts across all three target languages. Full synthesis at phase-8-v0.3-reference-run.md.

Quality: blind-graded, paired-t with confidence intervals

v0.5 shipped the LLM-judge methodology under paired-mode anonymization (per ADR-19). Cross-cell rollup paired-t at N=27 differences per axis (5 anchor cells × n=5 trials × 2 conditions; hono h1 auto-stretch to n=8):