Repository navigation
Install and setup
atlas is a Claude Code plugin. The plugin carries prebuilt binaries for Windows x86_64, Linux x86_64 and aarch64, and macOS (Apple Silicon and Intel), as the release notes list them; a platform a release lacks builds from source (below).
Claude Code version: no minimum is established. The measurements these pages cite were taken on Claude Code
2.1.316 and 2.1.318; the hooks other than SessionStart are mcp_tool hooks, and the always-loaded tool schemas need 2.1.285 or later.
An older Claude Code is untested.
-
Add the marketplace and install the plugin, in Claude Code:
/plugin marketplace add bloodfeast/atlas /plugin install atlas@atlas -
Restart Claude Code. On its first start the server:
- writes a starter configuration,
atlas.json, in your configuration folder, with one empty vaultnotesbeside it; - keeps its database and memory store in your data folder;
- downloads the embedding model (about 35 MB) in the background, resuming if interrupted, and checks it
against the SHA-256 pinned in the configuration. Until it is in place, search's
hybridmode answers lexically and the recall hook is lexical; both pick the model up when it lands, without a restart.
OS Configuration folder Data folder (database, memory store, models) Windows %APPDATA%\atlas%LOCALAPPDATA%\atlasmacOS ~/Library/Application Support/atlasthe same folder Linux $XDG_CONFIG_HOME/atlas(~/.config/atlas)$XDG_DATA_HOME/atlas(~/.local/share/atlas)ATLAS_HOME, when set, is both folders. The plugin's own folder is never used for state: Claude Code replaces it on every update. - writes a starter configuration,
-
Optionally, run the setup in the foreground to see each step (the plugin's
binfolder is on the Bash tool'sPATH, so Claude can run it for you):atlas --setup
It writes the configuration if there is none, creates the data folder, downloads or re-verifies every model file, and prints where everything is. Run it again after an interrupted download to resume. It needs
curl, which ships with Windows 10 and later, macOS and practically every Linux distribution.A new session in a folder atlas does not index asks, through Claude, in one line: create a vault for this project at
<path>? yes / other folder / no, yes being the default.atlas --setupasks the same in the terminal for the folder it runs in ([Y]es / [o]ther folder / [n]o; Enter is yes). Yes runsatlas settings add-project --vault, which adds the folder's Markdown as a source (**/*.md, withouttargetandnode_modules) and, when it holds code, the folder as a code root, then creates the project's vault and registers it undervaults, and indexes the source; the code root is indexed when the server next starts. The vault goes tovaults/<name>-notesbeside atlas's configuration file (where the first run'snotesvault is), so atlas's notes and discussion threads never land in the project's repository. It starts with oneREADME.mdnote; open the folder in Obsidian with Open folder as vault. Other folder runsatlas settings add-project --vault-at FOLDERinstead: an existing folder (an Obsidian vault you already have) is registered as it is, nothing written into it, and a folder inside the project is left out of the project's source so no note is indexed twice. No runsatlas settings add-project --no DIR, which records the answer and changes nothing else. A folder is asked until it is answered: nothing is recorded when the question is put, because Claude does not always relay it, and a session with no user runs nothing. So someone who never answers hears it at each new session (a start or/clear, not a resume or a compaction) in that folder, and the orchestrated mode question at each new session in any folder.atlas settings add-project [--vault | --vault-at FOLDER] DIRadds one any time (.for the current folder), and--vaulton an indexed project adds its vault alone.--dry-runshows the change, the file and the project it would go into, and writes nothing; so doesadd-projectwith no folder named (pass.or--yesto write). A folder a project already covers (a project root, its project file's folder, a repository) counts as indexed, so it is not asked about. Without a terminal,atlas --setuponly prints the command and records nothing, and says so: nothing went wrong, there was no terminal to ask in. In auto mode, Claude Code's classifier may blockatlas --setupandatlas settingscommands that Claude runs (the reason reads "No reason provided") until you tell Claude you allow them.Claude Code permissions. Nothing in Claude Code's own permissions marks atlas's tools as allowed, so in auto mode its classifier judges every atlas tool call like any other, and can block a plain read (a
sectionorsearchwhose path looks like a file a brief told agents not to open, for example). Allow the server once, in the project's.claude/settings.json(shared) or your own~/.claude/settings.json:{ "permissions": { "allow": ["mcp__plugin_atlas_atlas"] } }That is the rule for the plugin install above, whose tools Claude Code names
mcp__plugin_atlas_atlas__<tool>. A server you added yourself under the nameatlas(in.mcp.jsonor withclaude mcp add) has tools namedmcp__atlas__<tool>, so its rule is"mcp__atlas";/mcpshows which you have. The server-wide rule allows all of atlas's tools, the ones that read and the ones that write to the store, and any tool a later release adds. To allow fewer, list tools one by one ("mcp__plugin_atlas_atlas__recall", and so on). Project rules apply once you have accepted the folder's trust prompt. Subagents run under the permissions of the session that starts them, so one rule covers an orchestrated session's agents too.In a configuration with
projects, add-project writes into the project the folder belongs to (itsprojects[]entry:sources,code.roots,vaults), never the top level, whose lists every project reads;atlas --project NAME settings add-project DIRpicks the project, else the folder's own, elsedefault_project. For a folder in no project, with none named, a terminal lists the configured projects (even one) and cancel, and writes into the one picked; without a terminal, or with--dry-run, it is refused before anything is written. Every check runs on the text that would be written before it is written: a refused add-project leaves the configuration byte for byte as it was.The source, the code root and the vault are one configuration change, backed up, and
atlas settings undoreverts the newest change whole. Undo unregisters the vault and says what it did with the folder: a folder atlas created that still holds only itsREADME.mdis removed; a folder holding anything else, or one that was there before, is kept. Notes are never deleted. Backups of atlas's configuration go toatlas-backupsbeside the configuration file; backups of Claude Code'ssettings.jsongo toatlas-backupsin Claude Code's folder. Undo finds each in its own place. A change holdsatlas.json.lockbeside the configuration file, orsettings.json.lockin Claude Code's folder, so two sessions cannot lose each other's write; both are empty and stay there. Undo first shows what it would revert (when the change was made, which command made it, and for each file what goes back, with line counts) and asks; without a terminal it reverts only with--yes, so a command that changed nothing (and made no backup) never leads undo to revert an older change unseen. A folder that holds several git repositories is offered as a multi-repository project instead; see Projects and multi-repo.Setup also asks whether you want to work in orchestrated mode, for sessions that delegate their work to subagents: atlas caps how many agents of each kind run at once and tells each agent to hand off near its context limit (see the
orchestrateskill and Memory store and hooks). Nothing is on until you say yes. On yes it asks each option, with the value in effect in brackets (Enter keeps it):Question Stored as Default Compile slots (heavy compiles at once) orchestrate.resources.compilemax(1, hardware threads / 16), at most 4 GPU slots (GPU runs at once) orchestrate.resources.gpu1 Builders at once orchestrate.kinds.builder.maxthe compile slots Reviewers at once orchestrate.kinds.reviewer.maxthe builders Research and design agents at once orchestrate.kinds.research.maxmax(1, builders / 2) Context limits: enforced, advisory or off orchestrate.modeenforced Handoff point, in context tokens cap.warn_tokens, only when you type a number285,000 on a 1M window, scaled to the window Hard limit, in context tokens cap.block_tokens, only when you type a number450,000 on a 1M window, scaled to the window After a handoff, start the fresh agent: auto, or ask you first orchestrate.freshauto The defaults of the first five are starters: compile from this machine's threads, gpu 1, and the caps from the compile slots; a value already in the configuration is kept, and the caps are clamped to Claude Code's subagent limit. See Orchestration for the rules and for declaring lanes. The handoff point and the hard limit are skipped when context limits are off. The answers are one configuration change, backed up, which
atlas settings undoreverts. The first Claude Code session asks the same once, through Claude, unless the configuration already setsorchestrate.enabled. To answer again at any time:atlas settings orchestrate # asks in a terminal; without one, lists the options atlas settings orchestrate --yes --compile 2 --builders 3 --mode advisory # answers without a terminal atlas settings orchestrate --no # declines (and turns the caps off if they are on)
Setup never asks about Memory and rule files, which is experimental and off by default. Turning it on is a deliberate
atlas settings set memory-rules true. For atlas as Claude's memory, Reference configuration has a complete configuration and the checks that it works.Last, when the folder setup runs in has no rules (no
CLAUDE.md,.claude/CLAUDE.md,CLAUDE.local.mdup to its repository's root, no.claude/atlas-rules.mdand no intent file), setup offers atlas's rules template: a starterCLAUDE.mdand.claude/atlas-rules.mdwith the token-saving rules and the agent, build and safety rules ([y/N]; only yes writes). Where the folder has rules it prints one line naming them and asks nothing; it never overwrites a file.atlas settings rules-template [DIR] [--yes]offers the same any time. See The rules template.--yestakes--builders N,--reviewers N,--research N,--mode enforced|advisory|off,--handoff TOKENS,--limit TOKENSand--fresh auto|ask; an option left out keeps the value in effect, and a handoff point above the hard limit is refused. A no writes nothing to the configuration. -
Updates are on. At each session start atlas asks whether a newer release exists (at most once an hour), checks the release manifest's ed25519 signature against the public key built into atlas, downloads the binary for your platform, checks its SHA-256 against the signed manifest and swaps it in, then starts it. The check waits at most 10 s; past that the installed version starts and the check finishes in the background for the next start. Offline, or on any error, the installed version starts and the reason is logged as a miss. A newer version is never replaced by an older one. To turn updates off:
atlas settings off update
(
atlas settings on updateturns them back on), or pin a version inatlas.jsonwith"update": {"pin": "0.5.0"}. A binary you build from source never updates itself.A session can keep one atlas server for days, so a running server checks again every hour and stages a newer release on disk (one download however many sessions run); it keeps serving the old one until you run
/mcpand reconnect atlas, and tells you so once, on your next prompt. atlas also tells you about updates with one line at session start (shown to you, not added to the model's context, once per version): a newer release when you are pinned or have updates off, or the release you were moved to with its highlights. When the installed plugin is older than the release that last changed the plugin's hooks or skills, the line says to run/pluginto update the plugin. For a status line badge while an update is pending (a newer release, or this session's server older than the atlas on disk),atlas settingsoffers to addatlas --statuslineto your status line: it becomes the status line when you have none, and follows your own status line command's output when you have one (atlas settings off statuslineputs your command back). The command it writes names atlas by its absolute path, which/pluginmoves to a new version folder; each session start points atlas's own badge at the atlas now installed, changing that path and nothing else insettings.json(with a backupatlas settings undorestores). The status line is run throughsh, as Claude Code runs it (Git Bash on Windows). By hand:"statusLine": {"type": "command", "command": "<plugin folder>/bin/atlas --statusline"}; it reads local files only and prints nothing when there is no news."update": {"notify": false}turns the notice off.The reconnect line on your next prompt is the
systemMessageof atlas'sUserPromptSubmithook, anmcp_toolhook, whose answer Claude Code reads as the same JSON a command hook prints. That it shows in the transcript has not been checked in a live session yet; the status line badge carries the same news. -
Point atlas at your notes: edit
atlas.json(see Configuration reference) to add vaults (folders atlas may add to) and read-only sources (folders it only indexes), then run/mcpand reconnect atlas, or restart Claude Code. To keep the model download off entirely, set"models": {"auto_download": false, ...}; recall then stays lexical.
- Install the plugin (above) and restart Claude Code. Optionally run
atlas --setupfirst (step 3 above). 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. - Open a session in your project. Claude asks you about atlas: create a vault for this project at
<path>? yes / other folder / no, and, unlessatlas --setupasked 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 Orchestration). 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 undoreverts 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 .andatlas settings orchestratedo the same from a terminal. The vault question is per folder. - 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=NAMEorfailures=true. Grep and Read results name the enclosing item and its line range. - 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.53recall.cos_floor) were chosen by a sweep that measured off-topic records as well as on-topic recall. - Optionally,
atlas settings offerproposes the Claude Code settings that cut cost (the 1-hour subagent cache, fewer goal check-ins). Nothing is written without a yes, andatlas settings undoreverts (it shows the change and asks first;--yeswithout a terminal). With the compaction features on (the default;"compact": {"enabled": false}oratlas settings off compactturns them off),atlas settings compact-mdoffers a Compact instructions block for a project'sCLAUDE.mdthe same way. For a project with no rules,atlas --setupandatlas settings rules-templateoffer a starterCLAUDE.mdand.claude/atlas-rules.md(see Memory and rule files).
To build from source instead (any platform with a Rust toolchain):
cargo build --release --lockedand copy target/release/atlas (atlas.exe on Windows) into the plugin's bin folder as
atlas-<arch>-<os> (for example atlas-aarch64-unknown-linux-gnu), or as atlas.exe on Windows.
Build it last, after any test run: cargo test --release (or cargo build --all-targets) rebuilds that same
target/release/atlas with the tests' test-seams feature on, so if you ran the tests, run the plain
cargo build --release --locked again before you copy.
On macOS, remove the old binary before you copy the new one (rm bin/atlas-aarch64-apple-darwin, then cp):
macOS kills a signed binary that was overwritten in place, so a copy over the old file fails at launch with exit
137.
With a local-folder (directory) marketplace, Claude Code runs the plugin from the clone itself, not from its
plugin cache, so the binary goes into the clone's bin/ folder; a copy in the plugin cache is not found and the
server fails to start (seen on Claude Code 2.1.325). Put the binary in place before the first session: a start
without it begins Claude Code's 15-minute hold on the server (see As a Claude Code plugin).
- In Claude Code:
/plugin uninstall atlas@atlas, then/plugin marketplace remove atlas. - atlas's own folders are kept on purpose (the memory store is yours). To remove them too, delete the
configuration folder and the data folder from the table above. In Claude Code's folder atlas leaves only
what the settings commands wrote there:
atlas-backupsandsettings.json.lock.
CARGO_TARGET_DIR=<target dir> cargo test -j 4
CARGO_TARGET_DIR=<target dir> cargo xtask test-gate # contributors: the gate before a pull request (needs cargo-nextest)
CARGO_TARGET_DIR=<target dir> cargo install -j 4 --path . --root . --locked # -> bin/atlas(.exe)Run the installed copy in bin/, not the one in the target folder, so a rebuild never fights a running
server for the locked executable.
atlas --config atlas.json # serve MCP on stdio
atlas --config atlas.json --rescan # bring the index up to date, print stats, exit
atlas --config atlas.json --recall-check # compare the index with a plain scan of the same files
atlas --config atlas.json --code-index # index the code roots now (runs rust-analyzer; see the Code index page)
atlas --config atlas.json --embed 8 # embed every section for semantic search on 8 threads
atlas --vault NAME=PATH [--vault ...] [--db PATH] # the original flags still work, with or without --configThe measuring modes (--bench, --judge, --symbol-bench, --recall-scores and the --runs, --modes,
--queries and --before options only they read) are built only with the dev cargo feature, which is off by
default and in release builds; a release binary does not know them. Build a development binary for them:
CARGO_TARGET_DIR=<target dir> cargo build --release --features dev
<target dir>/release/atlas --config atlas.json --bench 500 # print the timings belowWithout --config and without --vault, the binary reads the config named by ATLAS_CONFIG, else
atlas.json in the folder above the binary, else atlas.json in the user's configuration folder (see
Install), which the first run writes from config/atlas.template.json when it does not exist. --db
overrides the config's db; with neither, the database is state/atlas.sqlite in the user's data folder.
Two file tools, atlas digest and atlas crop, need no configuration; see Handles and digests.
.claude-plugin/plugin.json names the plugin, .claude-plugin/marketplace.json makes the repository its own
marketplace, and .mcp.json launches ${CLAUDE_PLUGIN_ROOT}/bin/atlas with no arguments, so it finds its
configuration through ATLAS_CONFIG, atlas.json at the plugin root (gitignored), or the user's configuration
folder. In a release, bin/ holds atlas.exe (Windows resolves bin/atlas to it) and, for macOS and Linux, a
small sh launcher named atlas that starts atlas-<arch>-<os> beside it. cargo xtask release builds them
(see Releasing).
atlas doctor says what it can check: whether the atlas hooks in Claude Code's settings.json match the plugin's
hooks/hooks.json, or that there is no such file, no atlas hook in it, or that it could not be read (exit 1). A plugin
install keeps its hooks in the plugin, so it gets its own line and those hooks are not checked. It also names a project
root at or above your home folder, without changing it. It writes nothing.
If the server fails to start once (a missing binary, an invalid atlas.json), Claude Code does not try it again for
15 minutes, even after you fix the cause, unless the fix changes the server's command: the next sessions show it as
failed, and its hooks report it as not connected.
This is Claude Code's behaviour, measured at 14.9 minutes still failing and 15.2 connected, and atlas cannot change it.
A session works without atlas in that time: routing, recall and agent caps are off. atlas doctor names the wait
when it can see Claude Code's record of it (mcp-needs-auth-cache.json).
If the server fails to start, run atlas doctor: it names the wait and how long is left. It does not end the wait.
atlas is licensed under the Apache License 2.0. This wiki is generated from the repository's wiki/ folder at each release; edits made here are replaced by the next release. Report vulnerabilities privately, as SECURITY.md describes.
Getting started
What it saves
Reference
- Tools reference
- Code index
- Semantic search
- Identifiers and freshness
- Memory store and hooks
- Memory tree
- Memory and rule files
- Orchestration
- Discussions
- Project tracking
- Generated indices
- Cross-vault links
Internals