ProjectAtlas: a local SQLite map that tells coding agents which files to read

The problem is orientation reading, not code generation

An agent asked to change one function usually starts by listing directories, opening files, and building a mental model of the repository. On a large application, that orientation pass can consume more context than the actual edit. ProjectAtlas attacks that specific cost. It keeps a persistent, project-local index of folders, files, reviewed purposes, deterministic summaries, symbols, graph relationships, searchable text, health findings and token telemetry, and exposes it to the agent over MCP. The README frames the goal as narrowing before reading broadly: purposes identify the responsible area, graph relationships reveal connected code, and exact source slices provide the final evidence. The audience is narrow and identifiable: teams running MCP-capable agents (Codex, Claude Code, OpenCode) against repositories where the agent repeatedly spends context on files it never needed. The repository is Rust, MIT-licensed, and stores state in a `.projectatlas/` directory beside the repository rather than on a hosted service.

How the map is built and what the agent actually calls

The mechanism is a local pipeline. Scanning is `.gitignore`-aware, files are hashed with BLAKE3, and results land in SQLite, with compact TOON output for the agent-facing responses. A filesystem watcher keeps the map fresh during active work. The README states plainly that there are no required `.purpose` files and no source-header tax, which matters: the index is derived from the repository as it exists, not from annotations you have to maintain in-tree. On the agent side the intended flow is a short sequence. Bind the project and refresh only when the index may be stale. Start with one `atlas_session_brief` call using `compact: true`. Follow the summary, search, relation, health or exact-slice call that brief returns. Continue from returned selectors instead of repeating discovery, and open the smallest exact source slice needed for the answer. The README keeps `atlas_overview` then `atlas_folders` then `atlas_files` as a fallback for when the broader repository shape is itself the task. That fallback ordering is the honest part of the design: the tool is optimized for locating a known target, not for open-ended exploration.

Install routes and the init step that writes host configs

There are four documented routes. The Codex plugin is described as the recommended path, installed with `codex plugin marketplace add styler-ai/ProjectAtlas --ref v0.4.5` followed by `codex plugin add projectatlas --marketplace projectatlas`. A native release provides a prebuilt binary without Rust or Cargo. Cargo users run `cargo install --git https://github.com/styler-ai/ProjectAtlas --tag v0.4.5 projectatlas-cli --locked`. For Claude Code and OpenCode, the README says to run the native installer and then `projectatlas init`, which writes their version-matched project-local MCP configs. Initialization is per repository: `projectatlas init` creates the project-local database, performs the initial index, and writes the host configs. The human-facing dashboard is `projectatlas token --view tui`, with `--theme light` for light terminals and `--theme terminal` to preserve the terminal background; rerunning the command refreshes the snapshot. The README is explicit that the TUI is a local snapshot and not provider billing data. It also notes that in a control checkout with registered worktrees the dashboard combines native-control and active/retired worktree aggregates without changing the layout. Note the version pinning: the plugin, the Cargo tag and the release all reference v0.4.5, and the README points to a runtime repair section covering stale plugin caches and PATH conflicts. Version-matched configs are a design choice with a cost, since a host config written for one version is expected to be rewritten on upgrade.

Worktree federation is the most interesting and least finished part

Version 0.4.5 adds the ability for an agent to stay in one selected control checkout while addressing existing Git worktrees elsewhere on the filesystem by short MCP alias. The documented sequence is `atlas_worktree_list(include_retired: false)`, then `atlas_worktree_add(worktree: "<returned-stable-selector>", alias: "issue-430")`, then `atlas_init(worktree: "issue-430")`, then `atlas_session_brief(worktree: "issue-430", query: "target behavior", compact: true)`. Two details deserve attention. First, a missing target atlas can reuse validated control-atlas data and then reconcile the exact branch and dirty files into its own writable database, which means the tool is reasoning about uncommitted state, not just committed trees. Second, `main` names the selected control atlas, not a branch or folder, and unregistering a worktree retains accepted totals without deleting Git, source, `.projectatlas` or SQLite state. Git remains the worktree lifecycle authority. The README is candid that team-shared released atlases remain future work tracked as issue #456, so the federation described here is single-user and local.

Where ProjectAtlas is the wrong tool

The 90 percent figure is the first limitation, and the project states it itself: the README calls it a workload-specific local estimate from the published audit, explicitly not a universal savings guarantee or provider-billing result, and points to the One Large-Application Audit section and the token methodology document. Treat any number you see in the TUI as a reconciled estimate with observed and modeled components and a calibration status, not as measured provider spend. The second limitation is scope. The whole design assumes the agent already has a target: the brief returns ranked candidates and one ready next call. If the task is genuinely exploratory, the README's own fallback of `atlas_overview` then `atlas_folders` then `atlas_files` is the path, and that path looks much more like ordinary directory traversal with extra steps. The third is operational. The map is only useful when fresh, which means either a continuous `watch` process or bounded `watch --once` invocations, plus a per-repository `init` and a `.projectatlas/` directory to keep out of version control. On a small repository, or one where an agent can read the entire tree inside its context window, the index, the watcher and the host configs are overhead with no payoff. The fourth is that the README's install guidance leans on pointing an agent at the repository and asking it to install the latest version, which is convenient but leaves you trusting the agent to pick a consistent version across plugin, binary and config.

Compared with letting the agent grep and read

The realistic alternative is not a competing product; it is the default behaviour of an MCP-capable coding agent working against a repository with no index at all. That baseline uses recursive listing, grep, and file reads, and its cost scales with how much of the tree the agent touches before it finds the right file. ProjectAtlas changes the shape of that cost by inserting a precomputed layer: a SQLite map with purposes, symbols and graph edges, queried through a small set of MCP tools that return selectors rather than file bodies. The difference is not that search is faster; it is that discovery results become persistent and reusable across calls, so the agent continues from returned selectors instead of repeating the same traversal. The trade is that the map must be built and maintained, and that its usefulness depends on purposes and summaries being good enough to rank candidates correctly. A plain grep has no such dependency: it is always as accurate as the query, and it never goes stale.

Licence and the ongoing cost of keeping the map current

ProjectAtlas is MIT-licensed, which in practice means you can vendor it, modify it and ship it inside internal tooling provided you keep the copyright and permission notice with the source. That is a permissive arrangement and it removes the usual procurement question for a developer tool. This is not legal advice; read the LICENSE file in the repository for the operative terms. The maintenance cost sits elsewhere. Every repository needs its own `projectatlas init`, every upgrade is expected to rewrite version-matched host configs for Claude Code and OpenCode, and the README dedicates a documentation section to runtime installation and repair covering stale plugin caches and PATH conflicts, which tells you those failure modes are common enough to document. The release cadence visible in the supplied material shows three tags inside two days in August 2026 (v0.4.5-rc2, v0.4.5-rc3, then v0.4.5), which is a normal release-candidate sequence rather than a sign of instability, but it does mean the pinned `--tag v0.4.5` in the Cargo command will need bumping deliberately rather than tracking a moving branch. Budget for the watcher process and for re-indexing time on large trees, and decide up front whether `.projectatlas/` belongs in your global gitignore or the repository's own.

Editorial conclusion

Adopt ProjectAtlas if you run Codex, Claude Code or OpenCode against a repository large enough that orientation reading dominates the bill, and you are willing to run projectatlas init per checkout and keep a resident watcher. Do not adopt it for a small single-package repository where an agent can read the tree directly, and do not treat the 90 percent figure as a forecast for your workload. Before committing, verify the exact runtime path of the installed projectatlas binary, confirm that atlas_session_brief with compact: true returns usable selectors on your own repository, and read docs/benchmarks/large-application-token-savings.md to see how the estimate is derived.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. styler-ai/ProjectAtlas on GitHub