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.4
codex plugin add projectatlas --marketplace projectatlasThen 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.4 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 initThat 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.
- Bind the intended project and refresh only when the index may be stale.
- Start with one
atlas_session_briefusingcompact: true. - Follow its returned summary, search, relation, health, or exact-slice call.
- Continue from returned selectors instead of repeating discovery.
- Open the smallest exact source slice needed for the answer.
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-rc1 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.4 ships through the full release matrix:
- Rust format, check, clippy, dependency policy, tests, doctests, and rustdoc.
- Linux x64, Windows x64, macOS x64, and macOS arm64 native packages.
- Prepublish and postpublish packaged-runtime installer smokes.
- Codex plugin plus Claude Code/OpenCode generated MCP-config checks.
Full benchmark campaigns are manual-only and run only when explicitly requested.
The v0.4.5-rc1 candidate and release notes cover short-alias routing, hydration, isolated federation, aggregate tokens, compatibility, and cross-platform proof. RC1 is published as a prerelease and does not replace the preceding stable GitHub Latest 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-rc1 highlights, compatibility, boundaries, and proof policy | RC1 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.