Skip to main content
plugin

atlas — Claude Code plugin: what it does, how to install

atlas is a Claude Code plugin providing local indexing and memory recall. It cuts token consumption in long sessions by caching tool output on disk.

Apache-2.0 ★ 135 updated 2026-11-17

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add bloodfeast/atlas
/plugin install atlas@atlas
Open on GitHub

What atlas does

The plugin runs a local stdio MCP server coupled with Claude Code hooks. Instead of flooding the conversation with large build or test traces, atlas stores raw output on disk under a short handle and passes a concise digest to the model. Project rules, decisions, and handoffs are fetched by relevance rather than dumped into context at startup.

Its code index resolves exact symbol boundaries for languages like Rust, Go, Python, TypeScript, and Java using SCIP indexers or internal scanners. Markdown vaults work with standard folders, so installing Obsidian is optional. Once initialized, the server makes no network calls, storing state inside a local SQLite database.

Initial setup requires downloading a 35 MB embedding model file in the background. In auto mode, Claude Code's classifier can occasionally block atlas --setup until explicitly allowed in the prompt.

What it helps with

  • trim token usage from massive terminal output in long sessions
  • retrieve exact symbol ranges in source code without reading entire files
  • recall relevant architectural decisions from local Markdown journals
  • manage subagent concurrency limits and handoffs across lanes

Example prompts for the agent

  • Run atlas backlog to check aging items that dropped out of the work queue
  • Recall our previous decision about database connection pooling
  • Run atlas --token-report to measure token savings against baseline sessions

How to install atlas

Plugin marketplace

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

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about atlas

How to install atlas in Claude Code?

Run /plugin marketplace add bloodfeast/atlas, then run /plugin install atlas@atlas and restart Claude Code.

What does atlas do?

It manages a local code index and memory store, replacing bulky command output with digests and recalling documentation on demand.

What is required to run atlas?

It requires an initial internet connection to download a 35 MB embedding model. After that, it runs strictly offline via local SQLite without needing Obsidian.

Source text

SKILL.md · Apache-2.0
# 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 atlas | With atlas |
|---|---|---|
| The tool list, loaded with every session | 47 tools, 5,930 tokens (v0.1) | 14 tools, 6,118 bytes (about 1,530 tokens at 4 bytes a token, measured at v0.6.1); 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 files | 6.4x fewer tokens in all (ratio of sums); 10.9x median per answer |
| Memory questions (100-question evaluation, at v0.6.0) | the whole rulebook loaded | 100/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](https://github.com/bloodfeast/atlas/wiki/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](https://github.com/bloodfeast/atlas/wiki/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):

   ```sh
   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](https://github.com/bloodfeast/atlas/wiki/Memory-and-rule-files#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:

```sh
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:

```sh
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:

```json
{
  "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](https://github.com/bloodfeast/atlas/wiki/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.

```json
{
  "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](https://github.com/bloodfeast/atlas/wiki/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](https://github.com/bloodfeast/atlas/wiki/Security-model).
Report vulnerabilities privately, as [SECURITY.md](SECURITY.md) describes.

## Documentation

The wiki is the full manual:

- [Overview](https://github.com/bloodfeast/atlas/wiki/Overview): what atlas is and the rules it is built to
- [Install and setup](https://github.com/bloodfeast/atlas/wiki/Install-and-setup): install, updates, uninstall, build from source
- [Configuration reference](https://github.com/bloodfeast/atlas/wiki/Configuration-reference): every key of `atlas.json`
- [Projects and multi-repo](https://github.com/bloodfeast/atlas/wiki/Projects-and-multi-repo): scoped projects and repository graphs
- [Token savings and method](https://github.com/bloodfeast/atlas/wiki/Token-savings-and-method): where the tokens go and how it is measured
- [Handles and digests](https://github.com/bloodfeast/atlas/wiki/Handles-and-digests): routing, `recall h:ID`, `atlas run`
- [Tools reference](https://github.com/bloodfeast/atlas/wiki/Tools-reference): every MCP tool and the answer format
- [Code index](https://github.com/bloodfeast/atlas/wiki/Code-index): `symbol`, item ranges and language coverage
- [Semantic search](https://github.com/bloodfeast/atlas/wiki/Semantic-search): the owned embedder and hybrid search
- [Identifiers and freshness](https://github.com/bloodfeast/atlas/wiki/Identifiers-and-freshness): the registry, freshness and misses
- [Memory store and hooks](https://github.com/bloodfeast/atlas/wiki/Memory-store-and-hooks): the store, exports, sync and the hooks
- [Memory tree](https://github.com/bloodfeast/atlas/wiki/Memory-tree): the memory index as a tree
- [Memory and rule files](https://github.com/bloodfeast/atlas/wiki/Memory-and-rule-files): experimental, off by default: what atlas does with your rules and memories once you turn it on, and how to turn it off
- [Orchestration](https://github.com/bloodfeast/atlas/wiki/Orchestration): orchestrated mode: lanes, kinds and caps, starter resources
- [Discussions](https://github.com/bloodfeast/atlas/wiki/Discussions): reviewer threads and the decision queue
- [Generated indices](https://github.com/bloodfeast/atlas/wiki/Generated-indices): indices between markers
- [Cross-vault links](https://github.com/bloodfeast/atlas/wiki/Cross-vault-links): links between vaults
- [Security model](https://github.com/bloodfeast/atlas/wiki/Security-model): threat model and defences
- [SQLite store](https://github.com/bloodfeast/atlas/wiki/SQLite-store): the database and the audit log
- [Testing and coverage](https://github.com/bloodfeast/atlas/wiki/Testing-and-coverage): the suite, adversarial tests, coverage
- [Releasing](https://github.com/bloodfeast/atlas/wiki/Releasing): the changelog rule, release notes and the wiki
- [Changelog](https://github.com/bloodfeast/atlas/wiki/Changelog): every release

## License

Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

© Brandon White · Apache-2.0 · bloodfeast/atlas

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set4

Project sponsors

Companies that keep this analytics open