ProjectAtlas CLI
A local repository map for agents: the atlas CLI and MCP find the relevant code by file purpose instead of opening everything.
- 488 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Indexes project sources into a local database, writes project MCP configuration and installs hooks.
Install
- Works in
Manual install
codex plugin marketplace add styler-ai/ProjectAtlas --ref v0.5.0
codex plugin add projectatlas --marketplace projectatlasThe first Install variant in the README, for Codex.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Indexes project sources into a local database, writes project MCP configuration and installs hooks.
This is third-party code. Review the repository files before installing.
What it does
ProjectAtlas keeps a repository map in a project-local SQLite database: folder and file purposes, short summaries, symbols and the relations between them. An agent follows the map and opens only the code it needs. The native `atlas` CLI and the MCP server run on one index. Commands include `atlas next`, `atlas summary`, `atlas symbols relations` and `atlas token`. Each git worktree keeps its own map, and MCP can address registered worktrees by a short alias.
Who it is for. People running Codex or Claude Code on a large repository who burn context on hunting for the right files.
Good fit when
- Before an edit the agent reads dozens of files to locate the right spot.
- Before a refactor you need to see what a change touches: calls, imports, references.
- Several agents work in parallel in separate git worktrees.
- You want an estimate of token savings from `atlas token --view tui`.
Not a fit when
- The repository is small and the agent finds the right file on the first try.
- You need guaranteed coverage of dynamic code; the graph describes static facts.
- The project language is weakly supported; see the language matrix in the repository.
Example request
Use ProjectAtlas for this repo: find where watch refresh is implemented and show the related calls.Limitations
The graph describes static facts: unresolved references and coverage limits stay attached to answers, so dead code candidates need manual review. The optional parser pack of 150 grammars is listed for Linux x64 and Windows x64. Token savings in the README come from historical fixture runs and modeled estimates, not provider billing. Each repository must be initialized once with `atlas init`, and the map refreshed after edits with `atlas watch --once`.
How to disable. Remove the plugin or MCP entry from the agent configuration and delete the `.projectatlas` directory with its local database from the project.
FAQ
How do I install ProjectAtlas?
Ask your agent to install it from the repository, preferably via the marketplace plugin. For Codex that is `codex plugin marketplace add styler-ai/ProjectAtlas --ref v0.5.0`, then `codex plugin add projectatlas --marketplace projectatlas`.
Is Rust required to install?
No. Release binaries exist for Windows x64, Linux x64, macOS Intel and Apple Silicon. Building from source uses `cargo install`.
Where is the map stored?
Inside the project in a local SQLite database. Each git worktree keeps its own.
How do I connect it to Claude Code?
The native installer writes a project-local MCP configuration for Claude Code and OpenCode. Details are in `docs/agent-integration.md`.
What does `atlas token` do?
It shows a local token savings report. Observed source compression and modeled navigation are counted separately.
Discussion
No questions or reviews yet.
Related
CLI toolsMCP server keeping a Markdown map of code meaning beside the repo: the agent reads context before a task and suggests updates.
CLI that builds a codebase index and a 250-token map so an agent does not read hundreds of files to find the right one.
An MCP server and CLI in Go: the agent keeps an index of code and database schema in the repository, versions it in Git and reads it whole before each task
Local code graph for agents: an MCP server returns entry points, symbol links and change impact in one call
An MCP server and CLI for code research: search and understand your project and all of GitHub with fewer tokens
codesight maps a project in one run: routes, DB models, dependencies, env vars. It gives the map to an agent as files or through an MCP server
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| ProjectAtlas (this card) | no | 488 | ||
| CodeGraph | no | not required | 76,962 | builds a graph of symbols and code relations; this map rests on folder and file purposes, per-worktree maps and a token report |
| GitNexus | no | not required | 48,292 | indexes a codebase into a knowledge graph for MCP; here the main interface is the native `atlas` CLI sharing an index with MCP |
README in short
The README moves from the map idea to commands, parallel worktree work, token savings measurements, languages and installation.