code-atlas

An evidence layer for AI coding agents. A local-first MCP server that indexes your codebase into a symbol graph, then answers resolved relationship questions — who calls this, what implements that, what breaks if I change this file — as rows, not as files to read.

PHP · TypeScript/JavaScript · Python · T-SQL. 24 tools. Deterministic, offline, no LLM in the core. Every edge says how it was resolved, and the adapters differ in how deep they resolve — measured per language.

~69× fewer tokens than grep-and-read to reach a resolved answer

Measured on two pinned public PHP repos (symfony/demo · brick/math): 8/8 answers correct, recall 1.0, precision 1.0, zero confidently-wrong answers. Relation questions range from 18× on a small tree to 117× on a wide one; the one scored onboarding lookup is 4.5×. The baseline is a fixed recipe — grep the name, then Read every matching file whole — not a live model, so the comparison is deterministic. Reproduce it · needs PHP and a one-time clone of the pinned repos.

The 30-second version

Ask "who calls member()?" in this repo's own TypeScript adapter.

grep — 28 hits, and it cannot tell you which are calls:

$ grep -rn 'member' adapters/typescript/src/ | wc -l
28

$ grep -rn 'member' adapters/typescript/src/ | head -3
adapters/typescript/src/qname.js:4:// §4.4 Q1). The root container is the repo-relative posix
adapters/typescript/src/qname.js:12:function member(container, name) {
adapters/typescript/src/qname.js:16:module.exports = { SEP, toPosix, member };

A comment, the definition itself, and an export line — not one of the three is a call. The agent has to open and read every one of the 28 to sort them out. That reading is the cost, and it is paid in context.

code-atlas — the 9 functions that call it, each resolved, with the tier it was resolved at:

// MCP tool call, not a shell command
find_callers(qname: "src/qname.js::member")

reason: "ok"   total_count: 9   truncated: false   depth: 1

RESOLVED  parseFile::collect               src/parse.js:278
RESOLVED  parseFile::emitBodyEdges         src/parse.js:508
RESOLVED  parseFile::emitDefaultAlias      src/parse.js:428
RESOLVED  parseFile::emitJsDocDeclarations src/parse.js:439
RESOLVED  parseFile::emitReExport          src/parse.js:419
RESOLVED  parseFile::resolve               src/parse.js:301
…

No comment, no definition, no export line — and total_count: 9 is the true size of the answer (distinct callers; the graph holds all 13 call sites behind them), not the length of the page you were handed. Building that index took 0.54 s.

Real output, reproduced on 2026-09-27 by pointing code-atlas at its own adapters/typescript/ (code-atlas-build there, 6 files).

Why code-atlas

grep returns every line containing the string. An LSP answers precisely but one editor buffer at a time. Neither gives an agent a countable answer it can act on, and both make it read files to find out. code-atlas parses each language with its best parser into a SQLite symbol graph, resolves cross-file edges once at index time, and serves callers, implementations, blast radius, reachability and the path between two symbols as rows.

Use it if: you have a large codebase (>10k files) you did not write · an AI agent is doing the reading, not a human in an IDE · you need the answer to be checkable, not plausible.

It is not a faster grep, an editor, or a language server — an LSP stays for precise in-buffer nav, and code-atlas never mutates code.

Agents do not reach for it on their own when grep can serve the question — on a 23k-file tree, five control-flow questions drew no index calls with every tool available (074). It pays off on relationship questions, and an agent is far likelier to use it once told when to: install the agent brief.

Architecture

<img src="docs/assets/architecture.svg" alt="MCP client talks stdio to the language-agnostic core, which drives per-language adapters over a versioned JSONL contract, stores a symbol graph in SQLite, and feeds a deterministic onboarding layer with an opt-in LLM package behind three seams." width="100%">

The core is language-agnostic — no per-language branches, CI-gated. Adapters parse files and emit a common {nodes, edges} vocabulary; the core stores them, resolves cross-file edges, and exposes the MCP tools. Everything runs offline against local SQLite, with incremental updates via git diff.

Languages

| Language | Parser | Status | |---|---|---| | PHP (8.5 grammar, 8.1+ runtime) | nikic/php-parser | Available — see adapters/php/ | | TypeScript / JavaScript (Node ≥ 18) | TypeScript compiler API | Available — see adapters/typescript/ | | T-SQL (Node ≥ 18) | purpose-built scanner, no production dependencies | Available — see adapters/sql/ | | Python (≥ 3.12 grammar) | stdlib ast | Available — see adapters/python/ | | C# / .NET | Roslyn | Deferred — see Roadmap |

Resolution depth differs by adapter. A CALLS edge the adapter could not pin to one definition is stamped HEURISTIC rather than guessed, and the share of those is the depth measure (scripts/edge_health_report.py); PHP is the depth standard:

| Adapter | HEURISTIC share of CALLS | Pinned sample | Report | |---|---|---|---| | PHP | 1–4 % | symfony/demo · brick/math · laravel | 137 | | TypeScript/JavaScript | 54.1% | ky | 153 | | Python | 82.2% | flask | 227 | | T-SQL | not measured this way — floors and layer shape instead | SQL samples | 233 |

Adding a language touches no core code — an adapter announces its own name, the file suffixes it owns and its capabilities on one handshake line, and the core routes files from that alone.

Quick start

Platform: runs on Linux, macOS, and native Windows. For heavy indexing on Windows, WSL2 on the Linux-native filesystem is recommended: a repo under /mnt/* crosses the 9p boundary (~100× slower — measured), and Defender's real-time scan adds a large cold-read cost — exclude the repo path or use a Dev Drive. The startup preflight warns about the /mnt/* case; the Defender cost it cannot see. The test and dev loop is POSIX-only — run it under WSL2 or Docker.

You need Python ≥ 3.12 with SQLite ≥ 3.25 and FTS5 (a standard CPython build has both), plus the runtime of whichever language you want to index: a PHP CLI ≥ 8.1 with Composer for PHP, Node.js ≥ 18 for TypeScript/JavaScript and T-SQL. The Python adapter is stdlib-only and runs on the same interpreter as the core. Incremental builds in a git repo need git ≥ 2.24; an older git falls back to full builds.

git clone https://github.com/cuongdinhngo/code-atlas.git
cd code-atlas
python3 scripts/setup.py /abs/path/to/your-project

That installs the core, sets up every adapter whose runtime is on PATH (PHP via Composer, TS/JS and T-SQL via npm, Python needs nothing), and writes <your-project>/.mcp.json with the correct interpreter, each CA_<LANG>_CMD and the working directory filled in — the three things that are easy to get wrong by hand. Run it with no path to print the snippet instead of writing it.

To run the server without a checkout: uvx --from git+https://github.com/cuongdinhngo/code-atlas.git code-atlas, or pipx run --spec git+https://github.com/cuongdinhngo/code-atlas.git code-atlas — the adapters still need their own runtimes on PATH, and a checkout to launch them from.

In Claude Code, install it as a plugin — the server, the hooks and the skill in one step, for every project. The plugin launches the console scripts by name, so put them on PATH with a tool install:

uv tool install git+https://github.com/cuongdinhngo/code-atlas.git   # or: pipx install git+…
claude plugin marketplace add cuongdinhngo/code-atlas
claude plugin install code-atlas@code-atlas

Its hooks stay silent in a repo with no .code-atlas/; without the console scripts on PATH, the SessionStart hook prints the install line once and every hook exits 0 (376). Adapter CA_<LANG>_CMD variables stay per machine, as below. Already wired .mcp.json or the hook snippet by hand? Remove those, or each event fires twice (contrib/claude-code/).

Installed with uvx/pipx, the plugin or by hand? Add each adapter yourself — the core resolves any CA_<LANG>_CMD generically from the variable name, so each is one env var, not a code change:

npm ci --prefix adapters/typescript
export CA_TYPESCRIPT_CMD="node /abs/path/to/code-atlas/adapters/typescript/index.js --server"

npm ci --prefix adapters/sql          # dev-only deps; the scanner itself has none
export CA_SQL_CMD="node /abs/path/to/code-atlas/adapters/sql/index.js --server"

# Python adapter — stdlib only; use the same interpreter that runs the core
export CA_PYTHON_CMD="python3 /abs/path/to/code-atlas/adapters/python/index.py --server"

Then reload your MCP client (in Claude Code: restart, or re-approve the project's .mcp.json) and call get_index_status first — it is the cheap (~100-token) entry point that says whether there is an index, how stale it is, and what to call next. Then build_or_update_index, then query.

<details> <summary>Wiring it by hand, or running the server from a container</summary>

By hand: pip install -e ., then composer install --working-dir=adapters/php, then point an .mcp.json at your repo — command = code-atlas (or python3 -m code_atlas.main), cwd = the repo to index, env.CA_PHP_CMD = php /abs/path/to/code-atlas/adapters/php/index.php --server. The adapter lives in this checkout, so CA_PHP_CMD must be an absolute path. Details in adapters/php/README.md.

In a container — no host Python or PHP needed; the image bundles the pinned adapters:

docker build -f docker/Dockerfile.runtime -t code-atlas-server .

// .mcp.json — the server indexes the mounted repo and writes .code-atlas/graph.db into it
{"mcpServers": {"code-atlas": {"command": "docker",
  "args": ["run", "-i", "--rm", "-v", "/abs/path/to/your-project:/workspace", "code-atlas-server"]}}}

MCP speaks over stdio, so -i is required; the server indexes /workspace, so mount the repo there. Add "--user", "1000:1000" to keep .code-atlas/ writes owned by you. See docker/.

</details> <details> <summary>On native Windows</summary>

The runtime is fully supported; setup differs only in path/quoting and the checks the startup preflight surfaces at build time — long paths, core.autocrlf, and an adapter missing from PATH.

• Adapter command — prefer the list form in .code-atlas.toml, so a Windows path's backslashes are never eaten by POSIX quoting (the table needs $env:CA_TRUST_PROJECT_FILE = '1' — see the config table):

  [adapter_cmd]
  typescript = ["node", "C:\\code-atlas\\adapters\\typescript\\index.js", "--server"]
  python     = ["python", "C:\\code-atlas\\adapters\\python\\index.py", "--server"]
  

  Or set the env var in PowerShell: $env:CA_TYPESCRIPT_CMD = 'node C:\code-atlas\adapters\typescript\index.js --server'.

• Enable long paths so deep vendor/ / node_modules/ trees don't hit the 260-char limit (admin, then reboot): Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' LongPathsEnabled 1