ProjectAtlas keeps a project-local SQLite map of a repository and exposes it to agents through MCP and a CLI. It uses folder and file purposes, graph links, summaries, symbols, search, and exact source slices to help agents narrow before they read.
Builders who want their agent to find the right files in a large repository before spending context on the wrong ones.
You can guide an agent to the right code with less repeated reading and less context waste.
Scans the repo into `.projectatlas/` with folders, files, purposes, summaries, symbols, graph relations, search text, and health findings.
Returns ranked candidates, summaries, relations, and exact source slices so an agent can narrow before reading broadly.
Provides a native CLI plus MCP tools for Codex, Claude Code, OpenCode, and other MCP-capable agents.
Can register and hydrate existing Git worktrees with short aliases and isolated local databases.
Keeps configuration, indexes, and telemetry beside the repo instead of using a hosted index or credentials.
Includes a local TUI that reports estimated tokens avoided, file reads avoided, and repository-wide navigation work.
codex plugin marketplace add styler-ai/ProjectAtlas --ref v0.4.5 codex plugin add projectatlas --marketplace projectatlas
projectatlas init
Rust-native, high-performance local repository intelligence for coding agents and large codebases.
A persistent SQLite map guides Codex, Claude Code, OpenCode, and other MCP-capable agents to the right code before they spend context reading the wrong files.
Every file not opened. Every folder not explored. ProjectAtlas guides coding agents with purpose metadata and an intelligent code graph, reducing token costs by over 90%.
The "over 90%" figure is a workload-specific local estimate from the published audit, not a universal savings guarantee or provider-billing result; see One Large-Application Audit.
ProjectAtlas is a native Rust CLI and MCP server that keeps a project-local map of folders, files, reviewed purposes, deterministic summaries, symbols, graph relationships, searchable text, health findings, and token telemetry. .gitignore-aware scanning, BLAKE3 hashing, SQLite storage, filesystem watching, and compact TOON output keep repeated repository orientation local and fast.
The map is deliberately agent-first: purposes identify the responsible area, graph relationships reveal connected code, compact summaries and outlines explain the selected files, and exact source slices provide the final evidence. Agents narrow before they read broadly.
No required .purpose files. No source-header tax. No hosted index or credentials. Project state lives beside the repository in .projectatlas/.
Point your agent to the ProjectAtlas GitHub repository and ask it to install the latest version of ProjectAtlas.
The Codex plugin is the recommended path:
codex plugin marketplace add styler-ai/ProjectAtlas --ref v0.4.5
codex plugin add projectatlas --marketplace projectatlas
Then tell Codex: “Use ProjectAtlas for this repo.”
| Route | When to use it |
|---|---|
| Codex plugin | Recommended agent setup; supplies the version-matched skill, native runtime installer, and MCP templates. |
| Native release | Install a verified prebuilt binary without Rust/Cargo. |
| Cargo | cargo install --git https://github.com/styler-ai/ProjectAtlas --tag v0.4.5 projectatlas-cli --locked |
| Claude Code / OpenCode | Run the native installer, then projectatlas init; it writes their version-matched project-local MCP configs. |
Initialize each repository once:
projectatlas init
That creates the project-local database, performs the initial index, and writes version-matched host configs. See installation, upgrades, and runtime repair for stale plugin caches, PATH conflicts, generated Claude Code/OpenCode configs, and manual installer commands.
projectatlas token --view tui
Compare the live dashboard with the versioned TUI design reference.
The TUI is a local snapshot, not provider billing data. In a control checkout with registered worktrees, it combines native-control and active/retired worktree aggregates without changing the dashboard layout; an exact worktree report remains local. It also shows the reconciled token estimate, observed and modeled navigation work, source attribution, calibration status, and—at wide terminal sizes—a bounded live map from resolved repository relations. Rerun the command to refresh it; use --theme light for light terminals or --theme terminal to preserve the terminal background.
Read the token methodology or the TUI and agent-integration guide for the detailed accounting and theme controls.
atlas_session_brief using compact: true.atlas_overview → atlas_folders → atlas_files remains the fallback when broader repository shape is itself the task. Continuous watch or bounded watch --once keeps active work fresh.
The complete agent and MCP workflow owns tool routing, project isolation, generated host configuration, cancellation, and runtime repair. The workflow guide covers human CLI use.
ProjectAtlas v0.4.5 lets an agent stay in one selected control checkout and address existing Git worktrees anywhere on the filesystem by short MCP alias:
atlas_worktree_list(include_retired: false)
atlas_worktree_add(worktree: "<returned-stable-selector>", alias: "issue-430")
atlas_init(worktree: "issue-430")
atlas_session_brief(worktree: "issue-430", query: "target behavior", compact: true)
A missing target atlas can reuse validated control-atlas data, then reconcile the exact branch and dirty files into its own writable database. main names the selected control atlas, not a branch or folder. It owns labelled read-only federation and repository-wide token totals; unregister retains accepted totals without deleting Git, source, .projectatlas, or SQLite state.
Git remains the worktree lifecycle authority. See Worktree atlas continuity for isolation, recovery, and diagrams; team-shared released atlases remain future issue #456 work.
| Need | ProjectAtlas surface |
|---|---|
| Task-oriented startup | Project identity, index state, ranked candidates, blockers, and one ready next call |
| Responsibility | Reviewed folder/file purposes before broad source reads |
| Connections | Symbols and resolved graph relationships with bounded selectors |
| Exact evidence | Current summaries, outlines, searches, and source slices |
| Freshness | .gitignore-aware scan plus incremental watcher refresh |
| Worktree continuity | Short-alias routing, safe target hydration, labelled read-only federation, and exact isolated databases |
| Maintenance | Purpose queues, health findings, lint, and project-local configuration |
| Human overview | The existing token-impact TUI with repository-wide control totals and a bounded Atlas map |
See the CLI/MCP capability guide, configuration reference, and generated language and relation support inventories.
The chart and table below describe one representative audit, not a universal savings constant. The default local estimator is ceil(chars_or_bytes / 4) and is separate from provider billing. ProjectAtlas reports measured source compression separately from modeled navigation narrowing. In v0.4.4, the primary tokens_avoided/average_tokens_avoided value admits 50% of the deduped aggregate folder-navigation baseline, charges the complete Atlas payload, and leaves every other category unchanged. maximum_tokens_avoided retains the all-files folder-scope calculation.
| Audit signal | Result |
|---|---|
| Repository shape | 679 files · 206 folders |
| Indexed intelligence | 5,145 symbols · 12,122 relations |
| ProjectAtlas lookups | 142 |
| Average baseline avoided per lookup | 1,557,144 estimated tokens |
| Average ProjectAtlas payload | 2,997 estimated tokens |
| Estimated without / with ProjectAtlas | 221,114,448 / 425,622 tokens |
| Legacy gross estimated saved | 220,688,826 tokens |
| Observed savings rate in this one audit | 99.8% |
Warm indexed CLI reads in the same audit stayed around 160–166 ms. Repository shape, hardware, database state, command bounds, and access pattern all matter; initial scan/build work is separate. The audit report owns the formulas, corpus details, command samples, caveats, and current telemetry-field meanings.
v0.4.5 ships through the full release matrix:
Full benchmark campaigns are manual-only and run only when explicitly requested.
ProjectAtlas v0.4.5 promotes the tested RC3 line to stable. The RC1, RC2, and RC3 notes cover worktree navigation, stabilization, and the shared root-cause fixes included in this release.
| Topic | Guide |
|---|---|
| Install, agent workflow, MCP, host configs, runtime repair | Agent integration |
| Scan, ignore, purpose, and runtime settings | Configuration |
| Human CLI workflow | Workflow |
| Existing Git worktree registration, hydration, routing, federation, and token continuity | Worktree atlas continuity |
| v0.4.5-rc2 stabilization, compatibility, boundaries, and proof policy | RC2 release notes |
| Formats and compact agent output | Format |
| Structural summaries | Structural summaries |
| Language and relation coverage | Language support · Relation support |
| Token methodology and large-app audit | Token-savings audit |
| System, database, indexing, navigation, and packaging design | Architecture |
| Published site and Rust API docs | ProjectAtlas Pages · CLI/runtime crate |
MIT. See LICENSE.
Sign in to join the discussion.
No comments yet. Be the first to say what this is good for.
High-performance code intelligence MCP server. Indexes codebases into a persistent knowledge graph — average repo in milliseconds. 158 languages, sub-ms queries, 99% fewer tokens. Single static binary, zero dependencies.
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code
Git-native persistent memory for AI coding agents. Implements Google OKF v0.2 with sub-300µs in-memory BM25 search, embedded MCP server, and progressive disclosure. Slashes token bloat by 80% with zero external databases or dependencies. Built in pure Go.
Local-first code intelligence graph for MCP and CLI. Builds a persistent map of your codebase so AI coding tools read only what matters, with benchmarked context reductions on reviews and large-repo workflows.
Stop your AI from making things up — it proposes, deterministic tools decide, every claim checked against ground truth with evidence. Grounded facts and context survive resets. Reverse engineering is the proving ground. MCP server + CLI.
20 MB lightweight cross-platform database client for 90+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具，支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90+ 数据库，提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。