Same answers, ~65% fewer tokens. atlas compiles your repo into a compact, ranked map your AI coding agent reads in one shot — so it stops burning context just to find its way around.
When an AI coding agent works in your repo, it spends most of its effort just figuring out where things are: opening file after file to learn the layout. atlas does that once and hands the agent a single ~2,000-token map — every function signature, type, and import, ranked by importance, with no function bodies. The agent gets its bearings immediately and gets to work. It's the idea behind aider's repo map, unbundled into a standalone tool you can point at any agent.
In our benchmark, agents given an atlas map answered structural questions about a codebase using ~65% fewer tokens at identical accuracy (20/20 correct with and without the map — 85,670 → 29,781 tokens) — typically resolving in a single turn instead of three. On open-ended edit tasks the map cuts turns too, though token savings there vary by task. These are numbers you can reproduce yourself — the harness and the 20 verified questions are in the repo.
| Structural-comprehension benchmark | Without map | With atlas | Δ |
|---|---|---|---|
| Tokens to answer | 85,670 | 29,781 | −65.2% |
| Turns to answer (median) | 3 | 1 | −2 turns |
| Accuracy | 20 / 20 | 20 / 20 | 0 regressions |
20 verified structural questions · claude-sonnet-4-6 · 3 runs/arm · pytest 8.2.0 (92k LOC) · default 2,048-token map · read-only both arms. Edit-task token deltas are high-variance, so we headline only the stable, accuracy-gated signal.
Run atlas src --budget 600 on this repo and it prints:
# atlas: src (3740 LOC, 16 files) | budget 600 | rendered 585 tok
## cache.rs (#1 — imported by 1 file(s))
pub struct Cache
pub fn open(&Path) -> Cache
pub fn get(&mut self, &str, u64) -> Option<ParsedFile>
pub fn save(self)
pub fn content_hash(&str) -> u64
imports: parse.rs
used by: parse.rs
Files are ordered by importance (a PageRank over the import graph), #1 being the most central. Each file shows its public symbols, what it imports, and what depends on it — everything an agent needs to navigate, nothing it doesn't. The header reports the budget and the actual rendered token count.
Want to see more output before installing? The example gallery has real maps for a Python service, a TypeScript app, and a mixed Go/Rust/Python repo, each with the exact command used.
What it maps: Python (.py, .pyi), TypeScript/JavaScript (.ts, .tsx, .js, .jsx, .mjs, .cjs, …), Rust (.rs), Go (.go), Java (.java), and C/C++ (.c, .h, .cpp, .hpp, …). It honors your .gitignore and an optional .atlasignore, and always skips hidden directories and common vendored/build folders (node_modules, target, dist, build, venv, __pycache__, vendor, …). If a file you expected isn't there, it's almost always an unsupported language or a skipped directory. For exactly what's extracted per language — symbol kinds, visibility rules, import-linking behavior, and caveats — see the language support matrix.
pip / pipx — for the Python crowd, no Rust required:
pipx install --pre atlas-map # or: pip install --pre atlas-map
atlas is a Rust binary, not a Python package — the wheel just drops the native atlas command onto your PATH (the same way ruff and uv ship). The PyPI distribution is named atlas-map because atlas was taken; the command you run is still atlas. While atlas is in alpha the --pre flag is required.
Prebuilt binary — no Rust required (macOS & Linux):
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/fkenmar/atlas/releases/download/v0.2.1-alpha/atlas-installer.sh | sh
On Windows, grab atlas-x86_64-pc-windows-msvc.zip from the releases page. Binaries for all platforms (x64 + arm64) are attached to every release by cargo-dist. For Windows-specific PATH, PowerShell, and completion setup, see the Windows guide.
From source — any platform, needs Rust:
git clone https://github.com/fkenmar/atlas
cd atlas
cargo install --path .
This builds atlas into ~/.cargo/bin — make sure that's on your PATH (rustup sets this up by default).
Behind a corporate proxy, on an air-gapped host, or installing from an internal mirror? See docs/install-offline.md. atlas runs fully offline after install.
Either way, verify and take it for a spin:
atlas --version
cd path/to/your/project
atlas .
You should see a # atlas: … header followed by a list of ranked files. That's the whole tool.
atlas runs locally and does not collect telemetry; see
docs/PRIVACY.md for the offline/privacy model.
From zero to a map your agent can read:
pipx install --pre atlas-map # or any install method above
atlas --version # confirm it's on your PATH
cd path/to/your/project
atlas . --budget 1024 # a quick, small map to stdout
atlas . -o atlas-map.md # save the full default map to a file
Success looks like a header and a ranked file list — the most central file is
#1:
# atlas: your-project (3740 LOC, 16 files) | budget 1024 | rendered 1012 tok
## cache.rs (#1 — imported by 1 file(s))
pub struct Cache
pub fn open(&Path) -> Cache
...
If you instead see no supported source files found, it's almost always the
two first-run gotchas: you're pointing at a single file or a subfolder instead of
the repo root, or the project is in a language atlas doesn't map yet (the
error lists the file extensions it saw). Head to the full usage and
troubleshooting sections from here.
atlas . # map the current folder (2,048-token budget)
atlas . --budget 4096 # give it a bigger budget
atlas . --preset large # or a named preset: small|default|large|review
atlas . --focus src/auth # rank the files you're working on higher
atlas . --lang py,rs # only these languages
atlas . --no-private # public API surface only
atlas . --format json # JSON instead of Markdown
atlas . --format xml # XML, for wrapping in a Claude prompt
atlas . -o atlas-map.md # atomically write to a file
atlas . --for-agent # add a short Markdown note for agent context
atlas . --timings # print stage timings to stderr
atlas diff HEAD~1 HEAD # structural delta between two git revisions (or two dirs)
atlas serve --mcp # experimental MCP stdio server
atlas doctor # diagnose install, detected languages, and cache
atlas . --color always # force ANSI color (auto-detects a terminal otherwise)
When you run atlas in a terminal the Markdown map is colorized for scannability; piped, redirected, or --output file output stays plain, so feeding it to an agent or a file is unaffected (--color never to disable, NO_COLOR is honored).
Shell completions: atlas --completions <bash|zsh|fish|powershell|elvish> prints a completion script — e.g. atlas --completions zsh > ~/.zfunc/_atlas.
Pasting maps into an agent? A map is untrusted data derived from source. --format xml escapes the content so it can't break out of its container — see the prompt-injection threat model for safe wrappers and what escaping does (and doesn't) guarantee.
By default atlas aims for a 2,048-token budget. When a repo doesn't fit, it degrades in steps rather than truncating: it drops private symbols (the header shows public-only), then elides parameter detail, then collapses the lowest-ranked files to a single line. Raise --budget for more detail, or use --focus to protect the paths you care about.
atlas caches parse results in a .atlas/ directory at the repo root so re-runs are fast. It self-ignores (atlas writes .atlas/.gitignore), so it won't clutter your git status.
Pipe the output straight into your agent's context, or save it to a file:
atlas . -o map.md
--output writes through a same-directory temporary file and then renames it into place, so a failed run does not leave a partial map at the final path.
atlas writes the map to stdout, so it drops into any agent's context.
Save it and reference it — works with Claude Code, Cursor, Windsurf, Copilot, or any chat:
atlas . -o atlas-map.md
Then @-mention atlas-map.md in your prompt (or paste it in). Regenerate it whenever the structure changes — re-runs are warm-cached and finish in ~80 ms, so it's cheap to keep fresh.
For a pasted or attached Markdown map, --for-agent prepends a short note telling the agent to treat the map as a navigation index, not as source:
atlas . --for-agent -o atlas-map.md
Pipe it inline to any CLI agent:
{ echo "Repo map:"; atlas .; echo; echo "Task: add a --verbose flag"; } | your-agent
Focus the budget on what you're touching — --focus ranks those paths higher; repeat the flag for several:
atlas . --focus src/auth --focus src/api > atlas-map.md
Keep it in the repo so every contributor and agent starts oriented — commit atlas-map.md and regenerate it in a pre-commit hook or CI, or point your CLAUDE.md / AGENTS.md at it. To keep a committed map honest, gate it with --check — like rustfmt --check, it regenerates the map and compares byte-for-byte against the committed file instead of writing, exiting 1 if it's stale (so CI or a hook fails until you regenerate and commit):
atlas . --check atlas-map.md
For copy-paste recipes per agent (Claude Code, Cursor, Copilot, terminal agents) and per-editor task snippets, see the agent integration cookbook.
Experimental on
dev:atlas serve --mcpexposes read-only map, symbol lookup, thin symbol-index, and anchor-expansion tools over stdio JSON-RPC/MCP so compatible agents can pull fresh context directly.
Agent documentation entry points live in llms.txt and
llms-full.txt. They point agents at the README, benchmark
history, comparison guide, security policy,
PRD, changelog, and MCP setup docs without turning the README into a doc index.
The full, browsable index of every guide is docs/README.md.
Want your agent to map first automatically? The atlas-orient skill
is a drop-in skill (Claude Code, Cursor, Codex, …) — or paste the ready-made
block from examples/AGENTS.md into your agent's rules.
For Claude Code and other MCP-compatible clients, see
docs/CLAUDE_CODE_MCP.md and the reusable
examples/claude-code.mcp.json config.
Most of an agent's token bill on an unfamiliar repo is exploration — reading files to build a mental model. A map gives it that model up front, but a naive map (dumping every file) is too big and costs more than it saves. atlas earns its keep two ways:
- Structure only. Signatures, types, and imports — never function bodies. That alone is a fraction of the source.
- Ranked and budgeted. It scores every file by how central it is to the codebase and packs the most important ones into a fixed token budget, so the map stays small enough to live in context every turn.
discover → parse → link → rank → budget → render
It reads your repo with tree-sitter, respects .gitignore (and .atlasignore), and caches parse results so re-runs are fast.
How atlas compares — the standalone combination is the point:
| atlas | Aider repo-map | ctags | concat / packers | |
|---|---|---|---|---|
| Works with any agent (standalone) | ✓ | embedded in Aider | ✓ | ✓ |
| Graph ranking + token budget | ✓ | ✓ (internal) | — | — |
| Reverse-dependency edges | ✓ | inside Aider | — | — |
| MCP server | ✓ | — | — | — |
| Single-binary install | ✓ | Python app | native pkg | varies |
| Deterministic, cache-stable output | ✓ | ✗ (varies run-to-run) | ✓ | ✓ |
Aider's repo-map pioneered the ranked-map idea; atlas unbundles it into a standalone, deterministic CLI/library/MCP tool usable with any agent. Full, fair breakdown — including tree-sitter CLI and Sourcegraph/SCIP — in docs/comparison.md.
Measured, equal budget (pytest 8.2.0, 20 comprehension questions, claude-sonnet-4-6, both arms 20/20 accuracy): atlas cut tokens −65.4% vs Aider repo-map's −31.3% at matched ~2k-token maps — atlas answers at half Aider's cost (atlas's map held 12/20 answer keys vs Aider's 2/20). atlas's output is also byte-identical run-to-run (so a committed map stays cache-stable in the prompt prefix), where Aider's is not. Methodology + caveats (N=1; edit-task variance): benchmark/history.md.
What about "write less code" skills like ponytail? Complementary, not competing — and a useful illustration of why a map matters. Ponytail is a behavioral nudge ("reuse, don't rewrite"); atlas is structural visibility (it shows the agent what already exists). On a find-and-reuse edit task (use the existing helper instead of reimplementing it), both arms that had an atlas map passed, and both arms without one failed — including ponytail-only: its nudge can't help an agent reuse code it can't see. atlas resolved it in 7 turns at ~half the tokens of the reimplementing run. Pair the two if you like; the map is what made reuse possible. (Find-and-reuse task, claude-sonnet-4-6, pytest 8.2.0, N=1 — the robust signal is the reuse-vs-reimplement PASS/FAIL, not the token counts; details in benchmark/history.md and docs/comparison.md.)
- First stop:
atlas doctor. Runatlas doctor(optionally with a path) for a quick diagnosis — it prints the installed version, the binary's location, which languages are supported, the source files it detects per language (or why it found none), and the cache status. It's fast and read-only. - Empty map / "0 files". atlas found no supported source under that path. Check the language is one it maps (Python, TS/JS, Rust, Go, Java, C/C++) and that you're pointing at the project root — not a single file, and not a vendored or ignored directory. The error includes the top file extensions atlas saw to make wrong-root or unsupported-language cases easier to spot.
command not found: atlas.~/.cargo/binisn't on yourPATH. Add it (rustup's installer normally does), or run the binary by its full path.- A symbol is wrong or missing. That's usually a tree-sitter extraction bug — please open an issue with a minimal snippet that reproduces it.
- Too much noise, or a missing file in a big repo. Tune what atlas maps with
.atlasignore,--focus,--lang, or by mapping a subdirectory — seedocs/monorepos.md. - Scripting atlas in CI. The exit codes are a stable contract (
0success,1operational error,2usage error) — seedocs/exit-codes.md. - Old
repomapnames or files (.repomapignore,.repomap/,REPOMAP.md). atlas doesn't read them — see the migration guide. - On Windows —
PATH, PowerShell, execution policy, and completions are covered in the Windows guide.
More answers in the FAQ.
Current release channel: alpha. The core works end-to-end and is benchmark-tested, but CLI flags, output shape, install paths, and docs may still change. Pin a version if you depend on the output. See the stability & deprecation policy for exactly what's a stable contract pre-1.0 (the JSON/XML schemas) versus what may change (the Markdown map), release readiness gates for the alpha/beta/stable criteria, STATUS.md for current state, CHANGELOG.md for what's landed, and docs/PRD.md for the full design. The ROADMAP lays out what's planned, grouped by user outcome.
Building tooling on the output? --format json is a versioned contract with a
machine-readable JSON Schema:
schemas/atlas-map.schema.json for the map and
schemas/atlas-diff.schema.json for
atlas diff --format json.
atlas diff <old> <new> shows the structural delta between two trees — added/removed/changed signatures and import edges — so an agent sees what moved without re-reading the tree. Each side is a directory or a git revision (atlas diff HEAD~1 HEAD, atlas diff v0.2.0 .); revisions are checked out via git under the hood (no extra setup). Markdown by default; --format json or xml for tooling and CI.
Experimental on dev: an MCP stdio server (atlas serve --mcp) lets compatible agents query the map, look up symbols, request a thin anchor index, and expand selected anchors on demand.
Conventions and workflow live in CONTRIBUTING.md and CLAUDE.md; architecture decisions in docs/adr/. To build and test:
cargo build && cargo test