atlas

Project documentation as an index and a wiring gate — not as context fuel.

Why atlas · Measured Benchmarks · 30s Quickstart · Bootstrap (atlas init) · MCP Client Setup · The 15 Tools · Google Docs & Sheets

atlas is a local MCP server for coding agents. Ask "where is the damage model described?" and get back a file, a line, and a section anchor (~60 tokens) — instead of dumping 20,000+ tokens of raw Markdown into the context window.

When the agent finishes a task and tries to mark a work order ✅ DONE, atlas checks the codebase first: if the target function or class is defined with zero callers/references, the checkoff is refused.

┌──────────────┐    ~60 tok     ┌──────────────┐   section only   ┌─────────────────┐
│ atlas_where  │ ─────────────► │  atlas_read  │ ───────────────► │ atlas_code_find │
│ (BM25 / FTS5)│                │  (by anchor) │                  │  (9 languages)  │
└──────────────┘                └──────────────┘                  └────────┬────────┘
                                                                           │
       ┌───────────────────────────────────────────────────────────────────┘
       ▼
┌──────────────────────────────────────────────────────────┐
│ atlas_publish / atlas_set_status  (Wiring Gate)          │
│  ├─ callers > 0  ──► Write ✅ DONE + verify read-back    │
│  └─ callers == 0 ──► REFUSE write ("defined, 0 callers") │
└──────────────────────────────────────────────────────────┘

Works 100% offline with any folder of Markdown (docs/, specs/, adr/, gdd/) — plus optional live sync for multi-tab Google Docs and Google Sheets.

🛑 The Refusal (Why atlas Exists)

atlas exists because of a specific production failure. An agent implemented 1,070 lines, forgot the single dispatcher call that made them reachable, and reported "done". The next cleanup run saw an unused-function warning and deleted all of it — the lines were never committed, so nothing could be recovered. Nobody had asked the question atlas now asks before every checkoff: is this actually wired up?

That failure has a shape, and atlas answers it with a hard refusal instead of a warning nobody reads:

{
  "written": false,
  "refused": true,
  "refusal": "Acceptance refused — wiring check failed:\n  ✗ '_dispatch_unit_class_skill' is defined in scripts/turn_manager.gd:3774 but never called or bound (0 calls, 0 references)\n\nA ✅ without a caller documents an intention, not a result."
}

That check runs before any network or filesystem write, so it costs nothing when it blocks. It has caught this exact class of mistake twice in real use.

📊 Measured Benchmarks

All numbers below were measured with atlas measure on a real production project (5-tab specification document, 124 sections, 218 source files) — no synthetic estimates:

How atlas compares to other approaches

🧠 Context That Survives the Chat

Every new agent session starts blind. It re-reads the repository, re-discovers where things live, re-derives what the current state is — and when the context window fills up, the next session starts over. The map lives in the conversation, and conversations are disposable.

atlas moves the map next to the code:

• atlas_where answers "where is this documented?" in one call — for any fresh chat.
• atlas_status says which work orders are done, so the checklist survives the session.
• atlas init writes the architecture down once instead of re-deriving it every week.
• atlas_set_status records the outcome in the document, not in the transcript.

You can close a chat mid-task and open a new one. The next session asks three questions and is up to speed in three tool calls, without reading a single file end to end.

What it does not know is what you discussed. A decision that was never written down is gone — which is the same rule as before, just applied to conversations: if it matters, it belongs in the document.

⚡ 30-Second Quickstart

Requires Python 3.10+ and uv (or pipx). No Google account, no API key, and no network access required.

1. Install

# Recommended (installs `atlas` globally in an isolated environment)
uv tool install git+https://github.com/drproof/atlas-brief-mcp

# Or with pipx
pipx install git+https://github.com/drproof/atlas-brief-mcp

# Or from a local clone for development
git clone https://github.com/drproof/atlas-brief-mcp
cd atlas-brief-mcp
uv sync
uv run atlas --help

PATH note: If atlas is not found after uv tool install, run uv tool update-shell once (or add ~/.local/bin / %USERPROFILE%\.local\bin to your PATH).

2. Try it on the bundled demo project

atlas --root examples/demo doctor
atlas --root examples/demo where "Where is the damage model?"
atlas --root examples/demo brief "damage calculation"

Any folder of .md files works — docs/, specs/, atlas/, gdd/. The index lives in <root>/.atlas/index.sqlite, can be regenerated at any time, and your Markdown stays the source of truth.

🏗️ Bootstrap an Existing Repository

cd your-project
atlas init

Scans the repository — no LLM, no network, under 0.3 seconds for 50 files — and generates docs/ARCHITECTURE.md containing:

• Domains: every source folder with files, line counts, token estimates, and the largest functions per domain (not the first ones — those are getters).
• Context hotspots: files over 10,000 tokens that should never be read whole.
• Unwired symbols: functions over 15 lines whose name appears nowhere else — candidates for "implemented but never connected".

It also writes AGENTS.md, .antigravityrules, .mcp.json, and adds .atlas/ to .gitignore — but only if they don't already exist. atlas init never overwrites your rules.

atlas init --dry-run            # Preview what would be created, write nothing
atlas init --out docs/ARCH.md   # Custom output path
atlas init --force              # Regenerate deliberately

init records what it created in .atlas/managed.json. atlas lint uses that to separate managed documents (must be clean, exit code 1) from discovered legacy docs (reported as hints, exit code 0).

Supported Languages (9 Languages)

• GDScript & Godot Scenes (.gd, .tscn)
• Python (.py)
• TypeScript / JavaScript (.ts, .tsx, .js, .jsx — including React.memo(...) and forwardRef<...>(...) wrappers)
• Rust (.rs)
• C# (.cs)
• Go (.go)
• Java & Kotlin (.java, .kt)
• Swift (.swift)

Test functions (test_*, Test*, *_test) and framework-bound functions (@decorator, @mcp.tool()) are automatically excluded from unwired warnings.

Writing Without Google (100% Local Loop)

atlas init creates docs/ARCHITECTURE.md with Work Order 1 — ⬜ OPEN. If no Google document is bound to the project, atlas writes straight into that local Markdown file — with the same contract, read-back verification, and .atlas/mutations.log audit trail:

atlas set-status --wo 1 --status done    # ⬜ OPEN -> ✅ DONE in the Markdown file
atlas status                             # Reads the verified state

🔌 MCP Client Setup

The server speaks standard MCP over stdio. Because ATLAS_ROOT=. resolves relative to the client's working directory, one installation serves every project.

1. Claude Code / Cursor / Windsurf (.mcp.json)

Place this in your project root (or let atlas init create it):

{
  "mcpServers": {
    "atlas": {
      "command": "atlas",
      "args": ["serve"],
      "env": { "ATLAS_ROOT": "." }
    }
  }
}

2. Google Antigravity (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "atlas": {
      "command": "atlas",
      "args": ["serve"],
      "env": { "ATLAS_ROOT": "." }
    }
  }
}

3. Claude Desktop (claude_desktop_config.json)

Same block as above. On Windows, use "command": "atlas.exe" if the bare command name is not resolved.

Built-in Agent Guardrails: On connect, atlas delivers its own MCP instructions telling the agent to route documentation lookups through atlas_where → atlas_read instead of Read/Grep, and to call atlas_set_status / atlas_publish only after tests pass.

🛠️ The 15 Tools

☁️ Google Docs & Sheets (Optional)

If your team's living documentation or balancing tables live in Google Docs and Sheets, atlas indexes and updates them through the official Google APIs — including multi-tab documents:

atlas auth                     # One-time OAuth consent in the browser
atlas sync --query MYPROJECT   # Pull documents & sheets into the local cache
atlas status
atlas publish --wo 7 --title "Mission 1" --desc "Rooms 1-9"

Three engineering details that prevent common agent accidents:

1. Export to read, query directly to judge: The search index is built from Drive exports, but post-write verification queries documents.get directly — because the Docs API is consistent immediately after batchUpdate while Drive export caches lag by 0.5–2 seconds.
2. Append-only with revision lock: requiredRevisionId prevents a write from landing on a stale document revision, and an idempotency guard prevents duplicate status headers when a work order already exists in the live doc.
3. Tab-scoped status updates: replaceAllText uses tabsCriteria so status changes only affect the active tab, never archive tabs.

📏 Measure It on Your Own Project

You don't have to take our benchmark numbers on faith — run the exact same measurement on your own repository:

cd your-project
atlas init          # Or point at existing docs
atlas measure       # Compares naive full-doc read vs. atlas index per question

Documents: 4 · naive baseline: 28,011 tokens per question

Question                                           naive   atlas   saved
------------------------------------------------------------------------
Where is 7.6 Built engine features described?     28,011     885     97%
Where is 01_Units_Stats described?                28,011     689     98%
...
------------------------------------------------------------------------
Total                                            224,088   5,945     97%

By default, questions are derived from your section headings (which is optimistic because the question shares words with the heading — atlas measure explicitly notes this). For an independent benchmark, pass your own question list:

atlas measure --questions my-questions.txt    # One question per line

🧭 What atlas Is Not

• Not a prose editor: It writes verified status markers and spreadsheet rows/cells, not design prose.
• Not a web crawler: It indexes the documentation folders in your repository (and optional bound Google Docs).
• Not a test replacement: The wiring gate verifies that a symbol is defined and referenced/called — not that its logic is bug-free.

🧪 Automated Tests

uv run pytest -q                                           # 209 unit & integration tests (offline)
uv run python scripts/smoke_mcp.py --root examples/demo    # End-to-end JSON-RPC MCP smoke test

All 209 tests run completely offline. Every Google Docs & Sheets interaction is tested against deterministic fakes — including edge cases where the API swallows a write or lags on export.

📄 License

MIT — see LICENSE.