\n\n# ContextAtlas\n\n**Stop watching Claude burn tokens grepping for context it can't possibly find.**\n\nContextAtlas turns your codebase into a *single-call* context bundle for Claude Code —\nfusing LSP-grade structure, architectural intent from your Architectural Decision Records (ADRs), git history, and test\nassociations. Measured **45-72% token reduction with zero quality regression across\nbenchmark axes** on architectural prompts across the hono / httpx / cobra benchmark suite.\n\n\n\n\n\n\n\n\n\n\n
\n\n
\n \n
\n\n[**Quick start →**](#quick-start) · [**Benchmark results →**](#the-numbers) · [**Why not graph-based? →**](#how-contextatlas-compares-to-alternatives) · [**Architecture →**](#architecture) · [**ADRs →**](docs/adr/)\n\n---\n\nContextAtlas ships two equivalent paths — CLI and Claude Code Skills —\nboth producing the same `atlas.json`. See [Quick Start](#quick-start)\nfor setup.\n\n## The Problem\n\nClaude Code currently learns your codebase by brute force. Every session\nstarts fresh. Every \"where is X?\" triggers multiple grep calls. Every\n\"what depends on Y?\" is another flurry of file reads. On a mid-sized\ncodebase, answering a single architectural question can consume 40+ tool\ncalls and 100,000+ tokens before Claude has enough context to reason\nwell.\n\nWorse: the architectural intent that governs your code — the ADRs, the\ndesign decisions, the \"we did it this way because\" — is invisible to\nClaude. The rule that `OrderProcessor` must be idempotent lives in\n`docs/adr/`. When Claude proposes a change, it has no way to know that\nconstraint exists.\n\nYesterday's understanding doesn't carry to today. Every conversation\nstarts from zero. Your ADRs, your commit history, your test coverage —\nnone of it is on the agent's table.\n\n**What if expensive understanding happened once, at index time, and\nevery query became a dictionary lookup?**\n\nThat's ContextAtlas.\n\n## What ContextAtlas Is\n\nContextAtlas is an MCP server that gives Claude Code a curated atlas of\nyour codebase — fusing LSP-grade structural precision with architectural\nintent extracted from your ADRs, docs, and git history, delivered to\nClaude in single-call context bundles.\n\nEvery bundle Claude receives combines four independent signals about a\nsymbol:\n\n1. **Structural data** from the language server — definition, references,\n types, diagnostics. Compiler-grade precision.\n2. **Architectural intent** from your ADRs, READMEs, and design docs —\n structured claims extracted by Opus 4.7 at index time, keyed to\n specific code symbols.\n3. **Historical context** from git — recent commits touching the symbol,\n hot/cold indicators, co-change patterns.\n4. **Test associations** — which tests reference the symbol, where\n coverage lives.\n\nOne MCP call returns all four, fused. No ADRs in your repo yet? You\nstill get LSP + git + tests in one call instead of fifteen — a\nmeaningful baseline improvement. Add ADRs and the bundles get richer.\nThe architecture is designed so any subset of signals produces value.\n\nGiven an ADR stating that `OrderProcessor` must be idempotent, a call\nto `get_symbol_context(\"OrderProcessor\")` returns:\n\n```\nSYM OrderProcessor@src/orders/processor.ts:42 class\n SIG class OrderProcessor extends BaseProcessor\n INTENT ADR-07 hard \"must be idempotent\"\n RATIONALE \"All order processing must be safely retryable.\"\n INTENT ADR-12 soft \"prefer async base class for new processors\"\n REFS 23 [billing:14 admin:9]\n TOP ref:ts:src/billing/charges.ts:88\n TOP ref:ts:src/admin/orders.ts:12\n GIT hot last=2026-03-14\n RECENT \"Fix idempotency bug in retry path\" a3f2c1d\n TESTS src/orders/processor.test.ts (+11)\n```\n\nWhen Claude is asked to modify `OrderProcessor`, it sees the\nidempotency constraint *before* proposing changes — not after a user\nreview catches the violation.\n\n**Who this is for.** ContextAtlas is built for the average developer\nusing Claude Code on real codebases — not just engineers at large orgs\nworking on 500,000-file monorepos. Token-burn reduction scales with\ncodebase size — dramatic on a 200-file framework, modest on a 30-file\nlibrary. But **architectural intent capture is size-invariant.** A\n30-file library can have meaningful architectural decisions worth\nsurfacing, and Claude respecting them matters just as much as on a\nlarger codebase.\n\n## Beyond tokens: a design-alignment case study\n\nEfficiency and quality are necessary but not sufficient. The\nsubstantive value of context-grounding shows up in **design\nchoices** on non-trivial code-change tasks.\n\n**A/B trial during v0.3 development.** Identical 3-paragraph\nprompt across two ContextAtlas clones: implement a known bug fix —\nlocate the bug, design and implement the fix, write tests,\ndocument via ADR. The only setup difference: MCP availability.\n\n| Arm | MCP | Approach selected |\n|-----|-----|-------------------|\n| A (vanilla) | none | Recall-first approach (broader matching; fought the project's precision-thesis with noise) |\n| B (CA-aided) | ContextAtlas | Precision-optimization approach (aligned with the project's pre-extracted-claims-with-structural-attribution thesis) |\n\n**Arm B's approach landed in main.** Both arms functionally fixed\nthe bug at similar wall-clock and token cost. The substantive\ndifference was *alignment with project design thesis* — the\nCA-aided arm could read the relevant ADR + prior architectural\nwork from the atlas, and made a choice that fit. The vanilla arm\ncouldn't see that context and chose an approach that worked but\nfought the architecture.\n\nArm A's substantive consideration wasn't lost — captured as\nfuture-work investigation trigger. The recall-vs-precision\ntradeoff is preserved.\n\nFull synthesis at [v0.3 Round 3 dogfood evidence](https://github.com/traviswye/ContextAtlas-benchmarks/blob/main/research/v0.3-round-3-dogfood-evidence-2026-04-26.md).\n\n**N=1 trial; this is anecdote, not benchmark.** The systematic\nbenchmark suite (hono / httpx / cobra) measures efficiency and\nquality (see §The Numbers below). This A/B trial measures the\nsubstantively-distinct *design-alignment* axis — which doesn't fit\nbenchmark-suite methodology (every code-change task is repo-\nspecific) but is the substantive value proposition for cohort\ndevelopers building on real codebases.\n\n## The Numbers\n\nWe benchmark ContextAtlas against baseline Claude Code on three\nrepositories chosen to reflect realistic developer workloads:\n\n| Repo | Language | Source files | Role |\n|---------------|------------|--------------|------------------------------|\n| honojs/hono | TypeScript | 186 | Mid-sized framework |\n| encode/httpx | Python | 23 | Focused production library |\n| spf13/cobra | Go | 19 | CLI framework |\n\n**Methodology.** 24 prompts per repo, 6 task buckets, blind manual\ngrading, pre-registered rubric, no cherry-picking. Full methodology in\n[RUBRIC.md](RUBRIC.md).\n\n### Efficiency: 50-71% tool-call reduction on architectural prompts\n\nPhase 5 reference run on hono, six pre-registered prompts:\n\n| Prompt | Bucket | Alpha calls | CA calls | Δ | Alpha $ | CA $ |\n|---|---|---:|---:|---:|---:|---:|\n| h1-context-runtime | win | 18 | 9 | **−50%** | $2.36 | $1.52 |\n| h2-router-contract | win | 11 | 5 | **−55%** | $0.60 | $0.53 |\n| h3-middleware-onion | win | 5 | 5 | 0% | $0.38 | $0.47 |\n| h4-validator-typeflow | win | 21 | 6 | **−71%** | $2.95 | **$0.52** |\n| h5-hono-generics | tie | 11 | 13 | +18% | $0.79 | $1.17 |\n| h6-fetch-signature | trick | 3 | 4 | +33% | $0.17 | $0.29 |\n| **aggregate** | | **69** | **42** | **−39%** | **$7.25** | **$4.50 (−38%)** |\n\nThe headline case: **h4-validator-typeflow ran 7.3× cheaper** ($2.95 → $0.52)\nat equivalent answer depth. CA opens with the governing ADR by number;\nthe baseline reconstructs the architecture from source. Tie and trick\nbuckets (h5, h6) show CA net-negative as the rubric predicted — CA\nover-engineers on questions where architectural intent doesn't carry\nload. **Bucket-aware methodology surfaces these expected cases rather\nthan burying them.**\n\nCross-language replication: the same architectural-intent win mechanism\nholds on Python ([Phase 6 — httpx](https://github.com/traviswye/ContextAtlas-benchmarks/blob/main/research/phase-6-httpx-reference-run.md))\nand Go ([Phase 7 — cobra](https://github.com/traviswye/ContextAtlas-benchmarks/blob/main/research/phase-7-cobra-reference-run.md)).\nPhase 8 re-ran the locked prompt sets against v0.3-sharpened atlases at\nthe same pinned target SHAs: **45-72% token reduction on architectural-intent\nprompts across all three target languages**. Full synthesis at\n[phase-8-v0.3-reference-run.md](https://github.com/traviswye/ContextAtlas-benchmarks/blob/main/research/phase-8-v0.3-reference-run.md).\n\n### Quality: blind-graded, paired-t with confidence intervals\n\nv0.5 shipped the LLM-judge methodology under paired-mode anonymization\n(per [ADR-19](docs/adr/ADR-19-llm-judge-methodology.md)). Cross-cell\nrollup paired-t at N=27 differences per axis (5 anchor cells × n=5\ntrials × 2 conditions; hono h1 auto-stretch to n=8):\n\n| Quality axis | Mean Δ (0-3 scale) | 95% CI | Tier |\n|---|---:|---|---|\n| Factual correctness | +0.370 | [0.176, 0.565] | **CLEAN** |\n| Hallucination | +0.296 | [0.032, 0.561] | Borderline |\n| Actionability | +0.148 | [0.005, 0.291] | Borderline |\n| Completeness | +0.037 | [-0.039, 0.113] | Not distinguishable |\n\n**Threshold pre-registration:** the three-tier framing (≥0.05 CLEAN;\n0.001-0.05 BORDERLINE; ≤0 NOT distinguishable) was locked before\nprecision values were computed. No goalpost-shifting after data.\n**76% tie rate confirms anonymization worked** — the judge couldn't\ntell which condition was which on three-quarters of comparisons.\n\nFull per-axis numerics + 9 named findings at the\n[Phase-9 reference doc](https://github.com/traviswye/ContextAtlas-benchmarks/blob/main/research/phase-9-v0.5-reference-run.md).\nHonest methodology limits documented in [§Methodology and Honest\nLimits](#methodology-and-honest-limits) below.\n\n## How ContextAtlas Compares to Alternatives\n\nA few deliberate framings — what ContextAtlas is and isn't relative to\nneighboring tools:\n\n**vs. graph-based code intelligence (Graphify and similar).** We're in\nthe same category — both build pre-computed indexes over codebases for\nLLM agents via MCP. That's genuine category overlap, and we want to be\nstraight about it. Where we differ:\n\n- **LSP-grounded vs. heuristic-extracted.** ContextAtlas delegates all\n structural questions to the language server (tsserver, Pyright,\n gopls, ruby-lsp, csharp-ls). Graphify derives structure via parsing\n and extraction.\n- **Pre-composed bundles vs. graph primitives.** ContextAtlas's MCP\n tools return fused bundles in one call. Graphify exposes graph\n operations (`graph_query`, `get_neighbors`, `shortest_path`) that\n callers compose.\n- **Narrow scope vs. broad scope.** ContextAtlas indexes code + prose\n + git. Graphify ingests documentation, diagrams, research papers,\n and more.\n- **Claim-first vs. graph-first.** ContextAtlas stores discrete claims\n with severity labels, optimized for \"what constrains this symbol?\"\n Graphify models the world as nodes and edges, optimized for \"what\n connects to this node?\"\n\nWhether our bets produce better results for a given workload is an\nempirical question. See [the numbers above](#the-numbers).\n\n**vs. session-memory tools (claude-mem, engram, anamnesis).** Those\ncapture accumulated session history — what Claude learned or did in\npast conversations. ContextAtlas provides static architectural ground\ntruth extracted from your code, ADRs, and docs. Different information\nsources with occasional overlap (when session discussions become ADRs\nor commits), but fundamentally different problems. Session-memory\ntools also can't really be committed to a repo; ContextAtlas's atlas\ncan.\n\n**vs. LSP-in-MCP (LSP-AI and similar).** ContextAtlas *uses* LSP as\nits source of structural truth. If you just want LSP-in-MCP, those\nprojects solve that well. ContextAtlas layers architectural intent\nand git history on top.\n\n**vs. embedding-based search.** We evaluated this and chose\nsymbol-keyed claims instead. Embeddings are fuzzy; LSP symbols are\nexact. Embedding-based ranking is a post-MVP enhancement contingent\non benchmark evidence that it helps — see\n[ADR-09](docs/adr/ADR-09-find-by-intent-fts5-bm25.md) for the full\nrationale.\n\n### The committed-atlas pattern\n\nContextAtlas produces a **committable team artifact** — `atlas.json` —\nthat lives in the repo alongside your code and ADRs. This is the piece\nthat turns ContextAtlas from a personal productivity tool into a team\nasset.\n\n- **New team member clones the repo:** they pull down `atlas.json`\n with everything else. On first run, ContextAtlas imports the\n committed atlas directly into their local cache — no extraction API\n calls, no 10-minute wait. Productive from the moment they open\n Claude Code.\n- **Contributor submits a PR:** if their code change affects\n architectural claims, they regenerate `atlas.json` as part of their\n commit. Reviewers see both the code change and the atlas diff in\n the PR.\n- **Developer bounces between machines:** atlas state is\n version-controlled, not trapped on one laptop.\n- **Returning to a project after months away:** pull the latest main,\n and the atlas reflects everything the team did in your absence.\n Only files changed since you last pulled need incremental reindex.\n- **Open-source projects:** casual contributors benefit immediately\n without paying any setup cost. The project's accumulated\n architectural knowledge flows to them automatically.\n\nFor teams that cannot commit the atlas, set `atlas.committed: false`\nin the config. Every developer runs their own extraction. The team\nartifact benefit is lost, but ContextAtlas still works as a personal\ntool.\n\nThis model — committed team artifact with a local cache for query\nperformance — is a categorical difference from both session-memory\ntools and knowledge-graph tools. Detailed in\n[ADR-06](docs/adr/ADR-06-committed-atlas-artifact.md).\n\n## Architecture\n\n```\n INDEX TIME (once per source change)\n ──────────────────────────────────────\n ADRs ──────────┐\n Docstrings ────┤\n Git commits ───┼──► Opus 4.7 extraction\n LSP symbols ───┘ │\n ▼\n atlas.json (committed to repo)\n │\n ▼\n SQLite + FTS5 BM25 (local cache)\n\n QUERY TIME (every Claude call, zero API)\n ──────────────────────────────────────\n Claude Code: get_symbol_context(\"X\")\n │\n ▼\n One fused bundle, sub-100ms\n (LSP refs + intent + git + tests)\n```\n\nFive layers, each with one job:\n\n1. **MCP interface.** `get_symbol_context`, `find_by_intent`, and\n `impact_of_change` tools exposed to Claude.\n2. **Query fusion.** Composes results from signal sources per query.\n3. **Signal sources.** LSP (via tsserver/Pyright/gopls/ruby-lsp/csharp-ls),\n intent registry (from SQLite), git, tests.\n4. **Extraction pipeline.** Opus 4.7 reads prose docs and emits\n structured claims keyed to symbols.\n5. **Storage.** SQLite index, SHA-keyed for incremental reindex.\n\nSignal fusion at query time works as a substantively cheap lookup:\nwhen Claude calls `get_symbol_context(\"OrderProcessor\")`, the MCP\nhandler hits the LSP for live structural facts (definition,\nreferences, types) + reads the symbol's pre-extracted intent claims\nfrom SQLite + folds in git heat + tests. The bundle returned to\nClaude is composed, not computed — substantive joins happened at\nindex time. This is the substantive distinction from graph-based\nalternatives that expose primitives (`get_neighbors`, `shortest_path`)\nwhich callers compose at query time.\n\nThe architectural promise: **expensive understanding happens once at\nindex time; queries are local dictionary lookups, zero API calls.**\nThis bounds cost, latency, and unpredictability — and it's a hard\ninvariant, not an optimization.\n\nFull design in [DESIGN.md](DESIGN.md).\n\n### Data flow and privacy\n\nWhat ContextAtlas does and doesn't send off your machine:\n\n**Sent to Anthropic's API (at index time only):**\n- Text contents of ADRs, READMEs, and other markdown docs configured\n via `.contextatlas.yml`\n- This happens once per document per change — only on initial index\n and on incremental reindex of changed files\n\n**Never sent anywhere:**\n- Your source code\n- Your git history\n- LSP symbol data (names, references, types)\n- Query contents at runtime\n\n**Stored locally only:**\n- The extracted claims database (`.contextatlas/index.db` by default)\n- All runtime query resolution happens against this local SQLite file\n\nAt query time — every `get_symbol_context` call Claude makes during\nyour work — ContextAtlas performs a local SQLite lookup plus local LSP\ncalls. No network traffic. No model calls. Your code never leaves your\nmachine during normal use.\n\nIndex-time extraction uses the Anthropic API per standard API terms. If\nyour ADRs contain sensitive architectural decisions, they'll be\nprocessed under those terms like any other API-submitted content.\n\n## The Three Tools\n\nThe three MCP tools are not three parallel features — they're one fused\ncontext substrate with three access patterns.\n\n**`get_symbol_context`** — *the primitive.* \"I know the symbol; give me\neverything.\" Returns the full fused bundle (signature, ADR claims,\nreferences, git heat, tests, types) in a single call. Multi-symbol\nmode handles up to 10 symbols per request (per\n[ADR-15](docs/adr/ADR-15-multi-symbol-get-symbol-context.md)).\n\n**`find_by_intent`** — *the semantic-query composite.* \"I don't know\nthe symbol; find it by what it does.\" Ranks by BM25 against indexed\nclaim text in local SQLite FTS5 — no embedding service, no external\ncalls, deterministic results (per\n[ADR-09](docs/adr/ADR-09-find-by-intent-fts5-bm25.md)).\n\n**`impact_of_change`** — *the blast-radius composite.* \"I'm about to\nchange this; what breaks?\" Adds git co-change patterns and test impact\non top of the primitive.\n\n## Refresh Discoverability\n\nContextAtlas atlas is a substrate you build once and refresh after code\nor ADR changes. ONE canonical entry point per cohort path; behavior\nadapts based on substrate state:\n\n| | CLI | Skills |\n|-----------------|-----------------------------------------------------|-----------------------------------------|\n| **Cold-start** | `contextatlas index` (full extraction) | `/index-atlas` (full extraction) |\n| **Refresh** | `contextatlas index` (Phase 4 SHA-diff incremental) | `/index-atlas` (refresh-aware workflow) |\n\nSHA-diff incremental refresh per [ADR-12](docs/adr/ADR-12-cli-subcommand-surface.md)\nis substantively cheaper than cold-start scaffolding. Unchanged ADR\nand docstring sources skip; only changed sources re-extracted.\n\n## Quick Start\n\n> **Status:** v0.9.0 shipped 2026-05-16. v1.0 public launch substrate\n> complete. Package not yet published to npm; install instructions\n> below describe the intended shape.\n\n**Runtime requirements:**\n\n- Node.js 20 or newer.\n- A language server for each language you configure:\n - **TypeScript** — `typescript-language-server` (declared as a\n **peer dependency** rather than a direct one, so you control the\n version). Install alongside ContextAtlas\n (e.g. `npm i -D typescript-language-server typescript`).\n - **Python** — Pyright on the PATH (also a peer dependency).\n - **Go** — `gopls` on the PATH (install via\n `go install golang.org/x/tools/gopls@latest`).\n - **Ruby** — `ruby-lsp` 0.26.x. Recommended install via Bundler in\n your project's `Gemfile` (`gem 'ruby-lsp', '~> 0.26.0', require:\n false` under `group :development`). Rails projects additionally\n benefit from `ruby-lsp-rails` 0.4.x. Ruby 3.3+ required (4.0+\n recommended).\n - **C# / .NET** — `csharp-ls` 0.24.x on the PATH (Roslyn LSP\n wrapper). Install via `dotnet tool install --global csharp-ls`.\n .NET SDK 8 minimum (10+ recommended; matches cohort backend\n pin). On Windows, the `%USERPROFILE%\\.dotnet\\tools` directory\n must be on PATH — the adapter enriches PATH automatically for\n Bash/Git-Bash where the SDK installer only configures\n PowerShell.\n\n### Path A — Claude Code Skills (60 seconds, no API key)\n\n```bash\nnpm install -g contextatlas\ncontextatlas init\n```\n\nThen in Claude Code:\n\n```\n/generate-adrs # Skip if you already have ADRs (any path; see Using existing ADRs below)\n/index-atlas # Build the atlas\n/prime-atlas # Verify connection (once per session)\n```\n\n### Path B — CLI (90 seconds, API key required)\n\n```bash\nnpm install -g contextatlas\nexport ANTHROPIC_API_KEY=sk-...\ncontextatlas init\ncontextatlas generate-adrs # Skip if you already have ADRs (any path; see Using existing ADRs below)\ncontextatlas index\ncontextatlas doctor # Verify health\n```\n\n### Using existing ADRs and docs\n\nContextAtlas extracts architectural intent from whatever ADRs and\ndocumentation you already have — `generate-adrs` is for repos\nwithout existing ADR substrate.\n\n- **Existing ADRs at `docs/adr/`?** Skip `generate-adrs`;\n ContextAtlas extracts your existing ADRs automatically.\n- **ADRs at a different path?** Set `adrs.path` in\n `.contextatlas.yml` (default: `docs/adr/`).\n- **README, design docs, or other prose?** ContextAtlas extracts\n these too via `docs.include` (default: `README.md` +\n `docs/**/*.md`). Add custom paths to extract additional\n documentation surfaces.\n\nThe extraction pipeline produces structured claims from any prose\nsource pointed at via config — existing substrate doesn't go unused.\nSee [Configuration](#configuration) below for full schema.\n\n### MCP server registration\n\nConfigure ContextAtlas as an MCP server in your Claude Code settings.\nChoose based on whether `contextatlas` is on your PATH:\n\n**Option A — global binary on PATH** (e.g., installed via\n`npm install -g` or `npm link`):\n\n```json\n{\n \"mcpServers\": {\n \"contextatlas\": {\n \"command\": \"contextatlas\"\n }\n }\n}\n```\n\n**Option B — direct dist invocation** (no global install needed):\n\n```json\n{\n \"mcpServers\": {\n \"contextatlas\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/contextatlas/dist/index.js\"]\n }\n }\n}\n```\n\n### First-run behavior\n\n- If `atlas.json` is already committed (teammate ran it first, or it\n came with the repo), ContextAtlas imports it instantly. No API\n calls. You're ready in seconds.\n- If no atlas exists yet, ContextAtlas runs full extraction. Depending\n on ADR count and size, this takes 1-10 minutes and costs a few\n dollars in Opus API credits (CLI path) or session tokens (Skills\n path). The resulting `atlas.json` can be committed so future\n contributors skip this step.\n- **Cost projection note.** Script-reported extraction costs use\n full-token API pricing; platform-billed actuals reflect prompt-cache\n discount on the shared `EXTRACTION_PROMPT` prefix and typically run\n **~3x lower**. v0.4 reference measurements: cobra $5.44 → $1.82,\n httpx $5.53 → $1.85, hono $10.89 → $3.65 (3.0x ratio consistent\n across targets). Treat projected costs as conservative upper bounds.\n- On subsequent runs, only files whose SHAs have changed since the\n last index get reprocessed. Usually seconds.\n\n## Configuration\n\nCreate `.contextatlas.yml` in your repo root:\n\n```yaml\nversion: 1\nlanguages:\n - typescript\n - python\n - go\n - ruby\n - csharp\nadrs:\n path: docs/adr/\n format: markdown-frontmatter\ndocs:\n include:\n - README.md\n - docs/**/*.md\ngit:\n recent_commits: 5\natlas:\n committed: true # default; commits atlas.json to your repo\n```\n\nFull reference at [`docs/config.md`](docs/config.md).\n\n## Methodology and Honest Limits\n\nCredibility is built by stating what we don't claim.\n\n**Statistical methodology.** All quality measurements are paired-t with\n95% confidence intervals — **no p-values**. NHST at n=5 is\nstatistically void; CIs preserve effect-size visibility. Threshold\npre-registration honored verbatim (Option α strict three-tier framing\nlocked before precision values computed).\n\n**Single-judge model.** v0.5 quality measurements use Sonnet 4.6 as\nthe judge with within-judge consistency ≥80% per axis (pass-1 vs\npass-2). Cross-vendor judge-panel graduation is post-v1.0 work.\n\n**Three benchmark repos.** All quantitative claims are bounded to\nhono (TypeScript, 186 files), httpx (Python, 23 files), and cobra\n(Go, 19 files), plus our own dogfood. Generalization beyond these is\npost-launch cohort work.\n\n**v0.5 substrate scope.** Quality-axis measurements are 5 anchor cells\n× n≥5 trials × 2 conditions (hono h1 auto-stretch to n=8); not\nfull-matrix replication. Matrix-completion graduation is post-v1.0.\n\n**v0.6 cross-cycle replication caveat.** A targeted matrix-replication\nsubset at v0.6 (8 cells × n=5) showed attenuation on 2 of 4 quality\naxes vs the v0.5 anchor cells (factual_correctness CLEAN→BORDERLINE;\nactionability BORDERLINE→NOT distinguishable). Root cause: the v0.5\nmeasurements were against an earlier atlas version, and the cross-cycle\nmethodology didn't control for atlas-substrate-version. Full causal\ninvestigation deferred to post-launch. Detail at\n[Phase-10 reference doc](https://github.com/traviswye/ContextAtlas-benchmarks/blob/main/research/phase-10-v0.6-reference-run.md).\n\n**v0.3 single-run methodology.** Phase 8 reports n=1 per cell;\nblind-graded quality-axis measurement was added at v0.5. The Beta-vs-\nBeta+CA reporting at Phase 8 carries the atlas-file-visibility caveat\n(bias direction conservative — actual CA contribution likely larger\nthan published numbers indicate).\n\n**Dogfooding is not a measured benchmark.** Throughout development,\nContextAtlas indexes its own ADRs and is used by Claude Code during\nwork on ContextAtlas itself. This is a development practice, not part\nof the four-condition matrix — which runs only against the three\nexternal targets.\n\n**Favorable and unfavorable results both published.** Phase 7's\ncross-harness asymmetry hypothesis was FALSIFIED on v0.3 substrate.\nv0.6's atlas-substrate-version confound was surfaced and disclosed.\nTie and trick buckets routinely show CA net-negative; we report them\ninline rather than burying them.\n\n## Status and Roadmap\n\n**Current:** v0.9.0 (shipped 2026-05-16). v1.0 public launch substrate\ncomplete; launch execution work folds into v1.0.0 without a separate\nv0.9.1 tag.\n\n**Recent cycle highlights** (full per-cycle scope at\n[`docs/release-history.md`](docs/release-history.md)):\n\n- **v0.9 (May 16):** Ruby adapter ship — fourth supported language\n via ruby-lsp + ruby-lsp-rails per ADR-21. Repo launch substrate\n (MIT license + community substrate + cycle docs migration to\n `docs/cycles/v0_X/`). Launch positioning work in progress.\n- **v0.8 (May 14):** Substrate-equivalence + path-comparability +\n BM25 activation. Closed Skill-substrate parity to CLI at 65-83%\n claim ratio across hono/httpx/cobra benchmarks.\n- **v0.7 (May 12):** Launch-bearing cycle — Path-3 entry-point-\n determined architecture (CLI/Skills equivalence per ADR-02\n graduation) + `generate-adrs` feature with canonical depth-floor\n enforcement via `validate-adrs`.\n- **v0.6 (May 9):** Pipeline mechanics + targeted matrix-replication\n subset (8 cells × n=5 × 2 conditions). F1 PRIMARY atlas-substrate-\n version confound surfaced; full causal investigation deferred to\n post-launch.\n- **v0.5 (May 4):** Quality methodology cycle — LLM-judge harness +\n paired-mode anonymization per ADR-19 + paired-t statistical\n primitive (ADR-19 §4 amendment). V1.0 ship-gate criterion #1\n parenthetical CLOSED.\n- **v0.4 (April 29):** Substrate hardening — LSP timing-race\n robustness via two-readiness-signals (ADR-18) + cost-projection\n disclaimers + dogfood foundation + doctor diagnostic script.\n- **v0.3 (April 28):** Atlas precision cycle — narrower attribution\n + multi-symbol API per ADR-15 + atlas schema v1.3 with\n `contextatlas_commit_sha` + Phase 8 cross-target validation\n (45-72% range).\n- **v0.2 (April 25):** Three-language baseline — Go adapter via\n gopls per ADR-14 + cross-language cobra/httpx reference runs.\n- **v0.1 (initial MVP):** Three MCP tools + TS/Python adapters +\n Opus 4.7 extraction pipeline + SQLite incremental reindex + Phase\n 5 hono reference run (50-71% tool-call reduction on architectural\n win-bucket prompts).\n\n**Roadmap (post-v1.0):**\n\n- Cohort exposure execution against carried-forward recruitment\n infrastructure (v1.0 ship-gate criterion #3)\n- Full benchmark matrix completion + cross-vendor judge panel\n- Semantic embedding layer for `find_by_intent` (evidence-gated)\n- Task-shaped bundle queries: `why_does_this_fail`,\n `onboard_to_feature`, `audit_change`\n- Additional language adapters by demand: Rust, Java, Kotlin\n- Non-markdown intent sources: RST, AsciiDoc\n\nFor detailed milestone arc and per-cycle scope:\n[ROADMAP.md](ROADMAP.md), [docs/cycles/](docs/cycles/),\n[docs/release-history.md](docs/release-history.md), and\n[research/v1.1-candidates.md](research/v1.1-candidates.md).\n\n## Language Support\n\nThe language adapter interface is a stable plugin surface — each new\nlanguage is an additive contribution, not a core change. See\n[`docs/language-adapter-guide.md`](docs/language-adapter-guide.md) for\nthe contributor onboarding walkthrough.\n\n| Language | Adapter | LSP Server | Shipped |\n|----------|---------|------------|---------|\n| TypeScript | `TypeScriptAdapter` | typescript-language-server | v0.1 |\n| Python | `PyrightAdapter` | Pyright | v0.1 |\n| Go | `GoAdapter` | gopls | v0.2 |\n| Ruby | `RubyAdapter` | ruby-lsp (+ ruby-lsp-rails) | v0.9 |\n| C# / .NET | `CsharpAdapter` | csharp-ls (Roslyn) | v1.1 |\n\n## Contributing\n\nContextAtlas is MIT licensed and welcomes contributions. Areas where\ncontribution will be especially valuable:\n\n- **New language adapters.** The `LanguageAdapter` interface is small\n and stable. Adding Java, .NET, Rust, Kotlin, or other language\n support is a self-contained project. See\n [`docs/language-adapter-guide.md`](docs/language-adapter-guide.md).\n- **Non-markdown intent sources.** Currently we support markdown ADRs\n with YAML frontmatter. RST, AsciiDoc, and other formats are welcome.\n- **Benchmark repos.** Additional benchmark coverage on more codebases\n strengthens the eval.\n\n## Benchmarks and Methodology\n\nBenchmarks and methodology live in a separate repository:\n[github.com/traviswye/ContextAtlas-benchmarks](https://github.com/traviswye/ContextAtlas-benchmarks).\nThat repo contains the harness code, locked prompt sets, published\nmeasurement results, and the full methodology document (RUBRIC.md).\nKeeping the harness out of this repo means the benchmarks measure the\npublished `contextatlas` package's actual behavior rather than an\ninternal monorepo build.\n\n## Credits\n\nBuilt during the \"Build anything with Opus 4.7\" hackathon.\n\nContextAtlas uses:\n- Claude Opus 4.7 for index-time intent extraction\n- typescript-language-server for TypeScript symbol resolution\n- Pyright for Python symbol resolution\n- gopls for Go symbol resolution\n- ruby-lsp for Ruby symbol resolution\n- csharp-ls for C# / .NET symbol resolution (Roslyn LSP wrapper)\n- better-sqlite3 for the index store\n- @modelcontextprotocol/sdk for MCP server implementation\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
"bytes": 32504,
"sha": "09ecce848dea3c5e658f604894176485f7803bc73dbcbec998f78f2a1b2e52e7",
"repo_slug": "traviswye/contextatlas",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_traviswye_contextatlas_c9731675/readme"
}
![\"ContextAtlas](\"https://raw.githubusercontent.com/traviswye/ContextAtlas/main/docs/demo.gif\")
\n