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.
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.2
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.2 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. It combines 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.
| 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 |
| Maintenance | Purpose queues, health findings, lint, and project-local configuration |
| Human overview | The token-impact TUI and bounded Atlas map shown above |
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 and preserves a more conservative tokens_avoided headline alongside this legacy gross comparison.
| 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.2 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.
| Topic | Guide |
|---|---|
| Install, agent workflow, MCP, host configs, runtime repair | Agent integration |
| Scan, ignore, purpose, and runtime settings | Configuration |
| Human CLI workflow | Workflow |
| 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.