ProjectAtlas gives an agent one brief before it starts reading files

The 90 percent figure carries its own caveat

The repository description leads with tokens saved and a reduction of over 90 percent. The next paragraph in the same README walks it back, and that second paragraph is the one to read.

The claim is described as a workload-specific local estimate taken from the project's published audit. It is explicitly not a universal savings guarantee, and it is explicitly not a provider-billing result. A token dashboard that reported real billing would need a provider key and a live account; this one deliberately has neither, which is also why the project states that there is no hosted index and no credentials.

That framing is consistent with everything else about the tool. It keeps state in a SQLite database in a `.projectatlas/` directory beside the repository, hashes with BLAKE3, scans with `.gitignore` awareness and watches the filesystem for incremental refreshes. The token numbers are an internal accounting of work the agent did, not a receipt from a provider.

One session brief, then the smallest slice that answers it

The agent loop is five steps, and the first one is not a search. Bind the intended project, and refresh the index only when it may be stale. Start with a single `atlas_session_brief` using `compact: true`. Follow whichever call it returns: a summary, a search, a relation, a health finding or an exact slice. Continue from the selectors it hands back instead of repeating discovery. Then open the smallest exact source slice needed for the answer.

That ordering is the product. An agent that begins with a session brief receives ranked candidates and one ready next call, so it never has to enumerate the repository to find the right file. A sequence of narrowing calls with stable selectors replaces repeated open-and-scan cycles.

There is a fallback for the case where mapping the repository is itself the task: `atlas_overview`, then `atlas_folders`, then `atlas_files`. Freshness comes from a continuous `watch` or a bounded `watch --once`. The compact flag is on by default in the recommended call, which is the other half of the token argument: the brief itself is written to be small.

No .purpose files and no source header tax

Most tools that ask for structure ask you to add structure. ProjectAtlas explicitly does not: no required `.purpose` files, no source-header tax, no hosted index, no credentials.

Instead the map is built by scanning and then reviewed over time. What it holds is a project-local record of folders and files, reviewed purposes, deterministic summaries, symbols, graph relationships, searchable text, health findings and token telemetry. The purposes are the part that is human or agent reviewed, and they answer a different question from summaries: not what this file contains but which area is responsible for it.

The output format matters as much as the content. Compact TOON output and the smallest exact slice are named as the mechanism for keeping repeated repository orientation cheap, and exact source slices are described as the final evidence rather than the first thing an agent reads.

Maintenance is part of the same surface: purpose queues, health findings, lint and project-local configuration all sit in the maintenance row of what agents get, which suggests the index is expected to be corrected rather than merely regenerated.

The install docs pin v0.4.5 while the crate is a release candidate

Four install routes are offered, and the recommended one is the Codex plugin, which supplies a version-matched skill, a native runtime installer and MCP templates:

codex plugin marketplace add styler-ai/ProjectAtlas --ref v0.4.5
codex plugin add projectatlas --marketplace projectatlas

After that you tell Codex to use ProjectAtlas for the repo. The alternative for people who do not want Rust or Cargo on their machine is a native release binary. Cargo is the third route, pinned by tag and lockfile:

cargo install --git https://github.com/styler-ai/ProjectAtlas --tag v0.4.5 projectatlas-cli --locked

Claude Code and OpenCode are covered by running the native installer and then `projectatlas init`, which creates the project-local database, performs the initial index and writes version-matched host configs.

Here is the detail to watch. Every command and badge in the install section points at v0.4.5, while the workspace version in `Cargo.toml` reads 0.5.0-rc2 and the two most recent releases are the v0.5.0 release candidates from September. The worktree features are described as part of v0.4.5. If you follow the docs literally you get the older stable line, not what the workspace is currently building.

Worktrees get short aliases and their own databases

Git worktrees are usually where an agent-oriented tool has to compromise: either the agent leaves the checkout it was started in, or every worktree needs its own installation and index. ProjectAtlas takes a third route, letting the agent stay in one control checkout and address worktrees elsewhere on the filesystem by short 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)

The naming rules are precise in a way that matters for correctness. A missing target atlas can reuse validated control-atlas data and then reconcile the exact branch and dirty files into its own writable database, so hydration is not a copy of the control index. The name `main` refers to the selected control atlas rather than to a branch or a folder, which removes an obvious source of confusion.

Isolation is labelled read-only federation with repository-wide token totals held by the control atlas. Unregistering a worktree keeps the accepted totals without deleting Git, the source, the `.projectatlas` directory or any SQLite state, and Git stays the authority on the worktree lifecycle rather than the tool. Team-shared released atlases are named as future work, tracked as issue 456.

The token dashboard is a local snapshot

`projectatlas token --view tui` opens the human-facing view, and its first limitation is stated plainly: it is a local snapshot, not provider billing data.

Inside a control checkout that has registered worktrees, the view combines native-control and active and retired worktree aggregates without changing the dashboard layout, while an exact worktree report stays local to that worktree. It also shows the reconciled token estimate, observed and modelled navigation work, source attribution, calibration status and, at wide terminal sizes, a bounded live map built from resolved repository relations.

Rendering has two escape hatches for terminals that fight the default palette: `--theme light` for light terminals and `--theme terminal` to preserve the terminal background. The command is re-run to refresh rather than being live.

The design constraint behind all of this is stated as a no-change rule: the worktree view must not alter the dashboard layout. It is a small requirement that keeps the screenshot in the README and the versioned TUI design reference honest, since a comparison image is only useful if the thing it depicts has not moved.

Seven crates and a lint list that denies unwrap

The repository is a Cargo workspace of seven members, each named for the job it does: `projectatlas-cli`, `projectatlas-core`, `projectatlas-db`, `projectatlas-fs`, `projectatlas-service`, `projectatlas-symbols` and `projectatlas-lints`. The workspace uses resolver 3 and edition 2024, and the pinned toolchain lives in `rust-toolchain.toml` rather than being left to whatever rustup default a machine has.

The lint configuration is the interesting part. Unsafe code is denied outright and missing documentation is denied, which is why `missing_docs_in_private_items` is on as well. The clippy set raises everything to a warning and then denies a long list of specific mistakes: `unwrap_used`, `expect_used`, `panic`, `todo`, `unimplemented`, `dbg_macro`, `print_stdout`, `print_stderr`, `map_err_ignore`, `redundant_clone`, `needless_collect` and others.

Some clippy rules are explicitly allowed instead: `module_name_repetitions`, `similar_names`, `too_many_lines`, `too_many_arguments`, `type_complexity`, the cast family and `match_bool`. That split says something about the code. Errors are handled properly and helpers are documented, while clippy's opinions about naming and cast precision are treated as noise for this codebase.

The rest of the tree follows the same pattern: a `crates/` workspace, plus `docs/`, `fixtures/`, `openspec/`, `packaging/`, `plugins/`, `skills/` and `templates/`, and a `deny.toml` for dependency policy.

Editorial conclusion

Adopt ProjectAtlas if you pay per token and your agents keep rediscovering the same architecture by reading files, because a local index with reviewed purposes turns discovery into one tool call. Do not adopt it for its savings figure, since the over 90 percent number is a workload-specific local estimate from a published audit and not a billing result. Verify two things first. Run `projectatlas init` on one repository and read the token dashboard, accepting that it is a local snapshot rather than provider data. Then check the version you installed: the documented install path pins v0.4.5 while the workspace sits on 0.5.0-rc2, and the worktree features are described as landing in v0.4.5.

Frequently asked questions

Official sources

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