claudeers.
// Productivity

atlas

Local project memory and token savings for Claude Code: an MCP server and hooks

// Productivity[ cli ][ api ][ claude ]#claude#productivity◷ Apache-2.0$open-sourceupdated 4 days ago

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up atlas (claude-plugin project) into my current project.
Found on https://claudeers.com/atlas-3
Repo: https://github.com/bloodfeast/atlas
Homepage/docs: —
Detected install method: claude-plugin → /plugin install atlas@bloodfeast/atlas
Category: productivity. Platforms: cli, api.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
unknown; community-verified: false. Confirm the source before running anything.
// or install directly (claude-plugin)

⚠ Unverified / not recently updated — review before pasting a run-this config.

/plugin marketplace add bloodfeast/atlas
/plugin install atlas@bloodfeast/atlas
// or clone
git clone https://github.com/bloodfeast/atlas

// compatibility

Platformscli, api
Operating systems—
AI compatibilityclaude
LicenseApache-2.0
Pricingopen-source
LanguageRust

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

atlas

atlas makes long Claude Code sessions cheaper without changing how you work. It is a local MCP server and a set of Claude Code hooks: large tool output stays on disk under a short handle and the model gets a digest, code reads get exact item ranges instead of guessed windows, and memory (rules, decisions, journals, handoffs) is recalled by relevance instead of loaded whole. It runs on your machine, has two direct dependencies, SQLite (rusqlite) and an ed25519 signature check, plus the crates those two pull in (every one is in Cargo.lock), and makes no network calls at query time.

You do not need Obsidian. A vault is any folder of Markdown files: atlas reads and writes the files itself and never touches Obsidian's .obsidian settings folder. Obsidian is optional, as a reader for the same folders. The one Obsidian-specific output is that make_link writes obsidian://open links between vaults, which open only in Obsidian (elsewhere they are plain text); links within a vault are standard [[wikilinks]].

Languages. Memory, recall and history, search over Markdown notes and sources, discussions, the work queue, projects and multi-repo, and the hooks work whatever programming language a project uses, as does .proto indexing (rpc call sites are found in any language's files). The code index (symbol, item ranges on reads, grep annotations) covers Rust, WGSL, .proto, Go, TypeScript, JavaScript, C#, Python, Java and Kotlin (through scip-go, scip-typescript, scip-dotnet, scip-python and scip-java when they are installed, or a prebuilt index.scip from CI, WSL or Docker, else an owned scanner), and any language with a SCIP indexer from a .scip file. Build and test digests recognise cargo test, nextest, go test (plain and -json), jest, vitest, dotnet test, pytest, Maven and Gradle output, and other runners get the generic digest. Ranked search (fts, sections, recall) splits words on spaces and punctuation, so text written without spaces (Chinese, Japanese, Thai) is found with search in substring mode or grep instead.

What it saves

Every assistant turn re-reads the whole context, so a result that enters at turn 10 of a 300-turn session is processed 290 more times. Measured on real sessions:

Without atlasWith atlas
The tool list, loaded with every session47 tools, 5,930 tokens (v0.1)14 tools, 6,057 bytes (about 1,514 tokens at 4 bytes a token, measured at v0.6.0); the full reference is one fetched resource
A lookup (7,067 answers against 96 lookups done before atlas, measured at v0.6.0)grep, then read the files6.4x fewer tokens in all (ratio of sums); 10.9x median per answer
Rules and memory at an agent's start (1,560 agents, measured at v0.6.0)the whole rulebook read once per agentthe relevant records injected as pointers: 108.4x fewer tokens
Memory questions (100-question evaluation, at v0.6.0)the whole rulebook loaded100/100 answered when the agent follows a result to its source, 99/100 reading only the first result; median 506 tokens each

Shell reads are 36% of what a builder session processes and startup context another 35%; those are the buckets atlas targets. atlas --token-report measures your own store the same way: it takes its baseline from your Claude Code transcripts from before atlas, by itself in the background, and nets what atlas puts into context (the tool list, hook injections, tool output) against what it saves. How each number was measured, and how to measure your own sessions with cargo xtask attrib, is on Token savings and method.

Beyond the savings

  • Orchestrated mode, asked at setup and never on by default: an orchestrate skill teaches the main session to delegate through lanes and lean briefs, and the hooks cap how many agents of each kind run at once and hand an agent off at its context limit to a fresh one.
  • atlas backlog lists ruled work that fell out of the queue, aging items first, each with the rulings behind it. It only proposes; the queue's written order never changes.
  • Pull request reviews. In a gh pr diff file read, context far from a change is one marker line that recall h:ID lines=A-B opens, and atlas pr-events serve wakes the session that waits on a review.
  • Long sections are searched whole. Semantic search embeds a long section as overlapping windows, so a question answered deep inside it finds it.
  • atlas worktrees keeps an append-only ledger of which lane owns which worktree.
  • A fresh install teaches Claude atlas. The server's instructions and a bundled atlas skill carry the habits (recall before asking, journal decisions, hand off before stopping), and atlas tells you at session start when an update arrives.

Install

atlas is a Claude Code plugin with prebuilt binaries for Windows x86_64, Linux x86_64 and aarch64, and macOS (Apple Silicon and Intel). In Claude Code:

/plugin marketplace add bloodfeast/atlas
/plugin install atlas@atlas

Restart Claude Code. On its first start atlas writes a starter configuration, atlas.json, in your configuration folder (%APPDATA%\atlas, ~/Library/Application Support/atlas or ~/.config/atlas) and downloads the embedding model (about 35 MB) in the background, checked against its pinned SHA-256. Until the model is in place, search and recall are lexical. Updates are signed and on by default (atlas settings off update turns them off). Building from source, uninstalling and the data folders are on Install and setup.

Quickstart (5 minutes)

  1. Install the plugin (above) and restart Claude Code.

  2. Optionally run the setup in the foreground to see each step; Claude can run it for you, since the plugin's bin folder is on the Bash tool's PATH (not on your own terminal's):

    atlas --setup
    

    Run by Claude, it has no terminal, so it lists its questions instead of asking them and records nothing; Claude puts them to you at the next session. In auto mode, Claude Code's classifier may block atlas --setup and atlas settings commands (with "No reason provided") until you tell Claude you allow them.

  3. Open a session in your project. Claude asks you about atlas: create a vault for this project at <path>? yes / other folder / no, and, unless atlas --setup asked already, whether to work in orchestrated mode (caps on how many agents run at once; no is fine; on yes the caps and compile slots start from this machine's cores, see the wiki's Orchestration page). It may also offer Claude Code settings. Say yes to the first: its Markdown becomes a searchable source, a folder holding code becomes a code root, and a new vault (an Obsidian-compatible folder) holds the project's notes and discussion threads. atlas settings undo reverts it all; it never deletes a note. A question you do not answer comes back at your next new session, until you answer it, and Claude may not always put it. A session with no user (claude -p, the SDK) asks nothing and counts as nothing asked, and atlas stays silent if it could not record your answer. atlas settings add-project . and atlas settings orchestrate do the same from a terminal. The vault question is per folder.

  4. Work as usual. Large Bash, Read and Grep results now arrive as digests with a handle; Claude pulls what it needs with recall key=h:ID item=NAME or failures=true. Grep and Read results name the enclosing item and its line range.

  5. Ask Claude to remember a decision (remember), and start the next session: relevant records are recalled on each prompt, within a 600-token budget (recall.budget_tokens). The recall defaults (600 tokens, a 0.53 recall.cos_floor) were chosen by a sweep that measured off-topic records as well as on-topic recall.

  6. Optionally, atlas settings offer proposes the Claude Code settings that cut cost (the 1-hour subagent cache, fewer goal check-ins). Nothing is written without a yes, and atlas settings undo reverts (it shows the change and asks first; --yes without a terminal). With the compaction features on (the default; "compact": {"enabled": false} or atlas settings off compact turns them off), atlas settings compact-md offers a Compact instructions block for a project's CLAUDE.md the same way. For a project with no rules, atlas --setup and atlas settings rules-template offer a starter CLAUDE.md and .claude/atlas-rules.md (the rules template).

Projects

One install serves several projects, each with its own index and memory store; recall, the hooks and the work queue see only the active project. A shared user layer is imported into every project.

One repository. Open Claude Code in it and answer yes, or run:

atlas settings add-project --vault .      # or --vault-at FOLDER; without either, no vault

A folder of repositories. Open Claude Code in the folder that holds them (each one level down). atlas offers to make it a project, or run:

atlas settings add-project --new .

That writes atlas.project.json, listing each repository by path and remote, and creates the project's vault beside atlas's configuration (--vault-at FOLDER for another folder, --no-vault for none); commit the file so the whole team gets the same layout. Describe how the repositories relate, and a prompt that names one gets its role and neighbours, while recall puts records about the repository you are working in first:

{
  "name": "acme",
  "repos": [
    {"name": "billing", "path": "billing", "role": "invoices and payments", "talks_to": ["auth", "ledger"]},
    {"name": "gateway", "path": "gateway", "role": "public API edge", "talks_to": ["billing"]},
    {"name": "ledger", "remote": "https://git.example/acme/ledger"}
  ]
}

On a fresh install, add-project --new first moves the current setup into a project of its own (shown, backed up, and reversed by the same atlas settings undo). In a terminal it asks for that project's name; otherwise the name is the folder holding atlas.json, made a valid project name (-2 if the new project takes it). An existing setup moves into a project of another name with atlas settings migrate-projects NAME. Everything else is on Projects and multi-repo.

Minimal configuration

atlas.json, with relative paths taken from its folder. Every key is checked, so a misspelt key is an error.

{
  "vaults": [{"name": "notes", "path": "../Notes"}],
  "sources": [{"name": "docs", "root": "../my-project", "include": ["**/*.md"], "exclude": ["target/**"]}],
  "code": {"roots": [{"name": "app", "root": "../my-project"}]}
}

Vaults are folders atlas may add to; sources are folders it only indexes; code roots feed symbol. After an edit, run /mcp and reconnect atlas, or restart Claude Code. Every key is on Configuration reference.

Security in brief

  • Local only. One process over stdio. No HTTP client or DNS in the code or its dependencies, and one socket: atlas pr-events serve, run only from the command line, listens on 127.0.0.1 for signed GitHub events and never connects out; the events reach it through gh webhook forward, which it starts with gh. Nothing reaches the network at query time. The model download at setup and the update check go through the system curl, to pinned https URLs, and are verified (SHA-256, and an ed25519 signature for updates).
  • Confined. Every path is checked to stay inside a configured folder, lexically and after resolving links; dot folders are refused.
  • A fixed deny-list. .env*, keys, keystores and credential files are never read, whatever the configuration says: not in a source, not in a vault (nor written there), not by atlas digest or atlas crop. A file Claude Code reads with such a name is never kept as a handle, and neither is the output of a shell command, atlas run or Grep that names one. That catches named files only, since a shell command can hide a path.
  • Nothing lost. No delete or rename tool exists; writes are additive or exact, atomic and audited with a stated reason. The memory store is append-only.

The threat model and every defence are on Security model. Report vulnerabilities privately, as SECURITY.md describes.

Documentation

The wiki is the full manual:

License

Apache License 2.0. See LICENSE and NOTICE.

// faq

What is atlas?

Local project memory and token savings for Claude Code: an MCP server and hooks. It is open-source on GitHub.

Is atlas free to use?

atlas is open-source under the Apache-2.0 license, so it is free to use.

What category does atlas belong to?

atlas is listed under productivity in the Claudeers registry of Claude-compatible tools.

6 views
★ 85 stars
unclaimed
updated 4 days ago

// embed badge

atlas on Claudeers
[![Claudeers](https://claudeers.com/api/badge/atlas-3.svg)](https://claudeers.com/atlas-3)

// retro hit counter

atlas hit counter
[![Hits](https://claudeers.com/api/counter/atlas-3.svg)](https://claudeers.com/atlas-3)

// reviews

// guestbook

0/500

// related in Productivity

🔓

Agent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas.

// productivitykepano/★ 52,609◷ MIT[ claude ]
🔓

Open source repository of plugins primarily intended for knowledge workers to use in Claude Cowork

// productivityanthropics/⟨Python⟩★ 34,871◷ Apache-2.0[ claude ]
🔓

Garry's Opinionated OpenClaw/Hermes Agent Brain

// productivitygarrytan/⟨TypeScript⟩★ 33,099◷ MIT[ claude ]
🔓

An open-source alternative to Claude Cowork (powered by opencode)

// productivitydifferent-ai/⟨TypeScript⟩★ 24,523◷ NOASSERTION[ claude ]
→ see how atlas connects across the ecosystem