Atlas

A local-first codebase intelligence layer for AI coding agents.

AI coding agents waste a large share of their context budget re-deriving facts about a codebase they've already seen where a symbol is defined, who calls it, what breaks if it changes. Atlas builds a persistent, queryable model of a repository and exposes it to any agent through a small, typed tool surface (an MCP server plus a CLI), so an agent queries for structure instead of reading dozens of files to orient itself, and opens source only for the handful it actually needs to edit.

This repository is the Phase 0 proof of concept from project.md: single-language (Python), local, no embeddings the cheap, deterministic "structure discovery" core the larger product is built on.

Scope honesty. Phase 0 deliberately implements a slice, not the whole plan. What's here vs. what's planned is spelled out in Status below. Where a shortcut is taken (name-based call resolution, lexical search), the tools say so in their output rather than overclaiming a core design principle of the plan (§11).

What it does

• Parses Python with tree-sitter into a graph of definitions (modules, classes, functions, methods, module-level variables), call sites, and imports.

• Resolves the call graph using the receiver's class (self.m()), local x = Foo() bindings, and explicit imports before falling back to name matching with a confidence on every edge, a hard cap on calls through unknown receiver types, and unresolved call sites kept rather than dropped.

• Ranks every symbol by importance with a personalized-PageRank engine, and fits query results to a token budget the Aider insight that a raw graph is still too big to hand an LLM.

• Caches incrementally in SQLite keyed by content hash: re-indexing only re-parses files that actually changed.

• Overlays uncommitted edits: queries re-parse touched files in-memory on top of the committed index, so answers reflect the live working tree.

• Provenance + freshness on every answer: each result points back to an exact path:line (and commit) and is tagged committed / working-tree / stale so an agent can verify a fact or fall back to reading source.

Related MCP server: codecortex

Documentation

Install

python -m venv .venv && source .venv/bin/activate
pip install -e ".[mcp,dev]"     # mcp = server extra, dev = pytest

Requires Python ≥ 3.10. The tree-sitter Python grammar ships as a wheel no network needed at runtime.

CLI

atlas index                       # build/update the index for the repo
atlas find authenticate           # locate a symbol definition
atlas callers authenticate        # who calls it (ranked, confidence-flagged)
atlas callees login_endpoint      # what it calls
atlas impact verify               # blast radius + tests to run
atlas search "auth flow"          # lexical intent search (Phase 0)
atlas context "add rate limiting" --budget 2000   # budget-fitted bundle
atlas read 'pkg/core.py::authenticate'            # raw source escape hatch
atlas stats                       # index health + how much is guesswork

Add --json to any query command for machine-readable output. Freshness is shown as ✓ committed, ● working-tree, ⚠ stale.

The index lives in .atlas/index.db at the repo root (add it to .gitignore).

MCP server

Expose the same index to any MCP client (Claude Code, Cursor, …):

atlas mcp --root /path/to/repo    # speaks MCP over stdio

Example Claude Code / client config:

{
  "mcpServers": {
    "atlas": {
      "command": "atlas",
      "args": ["mcp", "--root", "/path/to/repo"]
    }
  }
}

Tool surface

Deliberately small and composable (plan §7) not one "dump the graph" call:

Every response carries a freshness field and a source pointer.

Architecture

repo → parser (tree-sitter) → graph (defs/refs/calls/imports)
     → ranking (PageRank) → store (SQLite, content-hash keyed, incremental)
     → indexer (+ working-tree overlay, provenance, freshness)
     → query engine → { CLI, MCP server }

Testing

pytest

Measured context cost

python benchmarks/token_savings.py

Measured on this repo (~23k tokens to read cold) with the real cl100k_base tokenizer. oracle is a deliberately unfair baseline it assumes the agent already knows which files hold the answer, which is exactly what Atlas supplies so it is the conservative floor:

This does not validate the §9 claim. It measures context cost only. §9 requires token cost and task success rate together over a fixed task suite fewer tokens at lower accuracy is a product failure. Quote these as a necessary-but-insufficient signal, never as "70–90% token reduction".

get_context budgets are enforced against the real payload and verified to stay within budget under cl100k_base (a 1500-token budget emits ~1376 real tokens; the internal estimator is deliberately conservative).

Status

Implemented (Phase 0): Python parsing, def/call/import graph, confidence-scored call resolution, global + personalized PageRank, incremental content-hash cache, working-tree overlay, provenance + freshness, CLI, MCP server.

Deliberately not in Phase 0 (see project.md §8 roadmap): multi-language grammars, semantic embeddings, SCIP import/export, non-code artifacts, access control, CI integration, and the benchmark suite that must validate the token-savings claim before it's made publicly (§9). search_intent is lexical until the embedding layer lands, and the call graph is approximate by design for a dynamic language both are surfaced in tool output rather than hidden.

License

Apache-2.0. Open-core by design (plan §10): the CLI, local index, and MCP server are the free foundation intended to become shared infrastructure.