
atlas
A local index and memory store for agents: identifier lookup, section search, a code index, append-only memory, relevance-gated recall and a context-cap hook.
- GitHub stars
- 118
Install
/plugin install atlas@atlasRun it inside Claude Code after adding the marketplace with /plugin marketplace add bloodfeast/atlas.
Contents
Discovered from sourceSkills 2
Working with atlas
atlas is the project's memory: rulings, decisions, lane journals, handoffs and the work queue, kept in a local store across sessions, agents and compactions, beside an index of the project's notes, docs and code. Nothing in it is lost when an agent ends; what an agent did not write down is.
This guide is the habits and the workflow. reference.md beside it lists every tool, op, argument, journal
entry kind, queue command and setting, generated from the same code as the tool schemas and atlas://help
(also note op=help). Delegating large work is the orchestrate skill. recall, search, section and
grep are loaded from the start; lookup (where an identifier is defined) and symbol (code definitions,
references and callers) are deferred like the write tools: load them by a tool search before the first call.
The habits
- Recall before you ask. Before asking the user something that may have been decided, and before
starting work in a lane, ask atlas:
recall query=<words>for rulings and decisions,recall lane=<id>for a lane's journal and handoff,recall key=<key>for one record whole. The hooks also inject what clears the relevance gate, so read what arrived before calling again. - Journal as you go. A decision, a measurement, a commit or an open question goes into your lane with
journalwhen it happens, not at the end. One entry per fact, the headline on the first line. - Hand off whenever work is left for later. Write a
handofffor your lane before your final answer whenever work is left for later, and from your handoff point on at the next clean stopping point. It is the only write allowed past the hard limit. - Name work by its queue key. Planned work is a
queuedentry with a key (journal:LANE:NNNN). Say the key, start it with aQueue:line in the brief, and mark it done; never describe it from memory. - Put a
Lane:line in every brief, withKind:, so the agent's start gets its lane's recall and its kind's limits. Declare each record the agent needs as a Gherkin tag, the full key every time (@journal:LANE:0012, pinned@journal:LANE:0012#a1b2c3d4), above Feature or above the Scenario or Spike it serves: the start lists each by key and title. Not0012, 0013after a key, nor0140 onward: name the few that bind. - Write terse. Journal, handoff and brief text comes back later as recall answers, so every word costs again on each read. Style for what you write into atlas and your replies: telegraphic, keys kept. Drop filler, preamble and restatement; fragments are fine. Keep every key, number, path, commit, error line and quoted ruling exact; a key stands in for its text.
atlas injects no rules of its own. The user's rules stay in their CLAUDE.md and memory files, which atlas indexes and recalls like any other source.
Lanes and sub-lanes
-
A lane is one stream of work with an id, for example
PARSER-2. It has no record of its own: it exists once ajournalorhandoffentry is written under it. -
Each agent works in exactly one lane. The next agent in the lane starts from
recall lane=<id>, which gives the lane's journal and its newest handoff. -
A sub-lane (
PARSER-2/2) is given when a second launch goes into a lane that running work holds. The agent is told so at its start; it journals and hands off under the sub-lane, and its records show in the parent lane's view too. -
Declare a lane before its first launch with a
briefentry carrying the launch lines:Kind: builder Lane: PARSER-2 Priority: normal Uses: compile, worktree:parser-2atlas reads these lines from the first 40 lines of a launch prompt. It schedules on declared lines and only warns on what it infers from a prompt's words.
Journal entries
journal takes a lane, an entry kind and the text (first line the headline); meta holds <key>: <value>
lines and refs holds record keys. The kinds:
brief: the lane's work order and launch lines.decision: what was decided and by whom, in their words where a user ruled.measurement: a number with the machine state and the command that made it.commit: a commit, merge or PR, by hash or number.question: an open question;answeredcloses one, withanswers:<key>inrefs.next: a step owed. A checkpoint lists thenextentries nocommithas followed.note: anything else worth keeping.queued: planned work (see the queue below).review: a review for the merge gate, with metarole:,pr:,head:,verdict:andreport:.cap,checkpointandideaare written by atlas: a context-cap warning, a compaction or clear checkpoint, and an idea captured from the user's own words.
To correct an entry, amend its key with expected_sha (its sha, as recall shows it); the old version
stays readable. Durable facts that are not lane work (a user's preference, a standing rule) go to
remember with kind memory, rule or decision; old supersedes earlier records.
The work queue and handoffs
- Plan with
atlas queue plan --lane L --title T(or aqueuedentry over MCP, with meta lineskind:,priority:,uses:,after:andorder:).after:lists conditions: a queue key, met when that item is done, or free text, met only when marked withatlas queue met KEY CONDITION. - List with
atlas queue list;atlas queue nextproposes what can start now. An item with an unmet condition is never proposed. - Start an item by launching its agent with
Queue: <key>in the brief; that takes it off the queue. A launch refused at its kind's cap is queued too, and the refusal names its key: launch it again later with the same brief (recall key=<key>reads it) rather than retrying at once. - Finish with
atlas queue done KEY, oratlas queue drop KEYfor work no longer wanted. - A handoff holds everything the next agent needs: the state, the commits, where the evidence is, the corrected commands, the steps left in order and the open questions. The agent that wrote it hands back only the line naming its key; the next one starts fresh from it. Never resume an agent past its handoff.
Context limits and compaction
- atlas reads each agent's real context from its transcript. The defaults on a 1M window are a handoff point
at 285k and a hard limit at 450k, scaled to the model's window. Past the handoff point the agent is told to
wrap up; past the hard limit (enforced mode) every tool but
handoffis denied. Under an enforced limit a subagent past its handoff point is not compacted: atlas blocks its compaction, and it hands off. - The main session is told when it passes its compact point to ask the user for
/compact, and to recommend/clearinstead when the last compaction left the session atcompact.clear_flooror more.atlas settings auto-compactmakes Claude Code's own automatic compaction fire at atlas's hard limit. - Before a compaction, atlas asks once for a checkpoint and writes a
checkpointentry in the session's lane: lines of refs (lanes, open questions, owed steps, rulings), never restated text. A/clearwrites one from the ending transcript. The next start injects its card. - Refs name exact text:
key@hash(a record version),src:path:a-b@hash(lines of a file) and theturn:...@hashandcompact:...@hashkeys the compaction card names (transcript turns and older segments; they resolve whilecompact.enabled, on by default, ormemory.transcriptsis on).recall key=<ref>returns that exact text. After a compaction atlas checks every ref in the summary and reports the changed and dangling ones. - Write a compaction summary as keys and deltas: a ruling as one line with its key, the state with its journal key, commit or file and line, and only the few exact lines the next step needs. Never restate what one recall returns.
Changing atlas itself
atlas's first job is memory. A change that cuts tokens (an answer's size, a hook floor, trimming,
compaction) ships only after the memory fidelity eval, before and after: cargo xtask memory-eval with
recall-check misses at 0, no fact lost on the question set and the work-queue checks matching, and
cargo xtask rules-eval for which ruling comes first. A change of behaviour updates this guide's prose;
cargo xtask skill regenerates reference.md, and a test fails when either drifts from the code.
Orchestrating with atlas
The main session plans, delegates, verifies and merges. Subagents do the work. atlas holds the state between them: lane journals, handoffs and recall. No agent has to carry another agent's context.
Lanes
-
A lane is one stream of work with an id, for example
PARSER-2. Each agent works in exactly one lane, and journals under it with the atlasjournaltool: its brief, its decisions, its measurements, its commits, any questions, and what is next. -
An agent that stops writes a handoff for its lane with the atlas
handofftool. The next agent starts fromrecall lane=<id>, so nothing is lost when an agent ends. -
Never resume an agent past its handoff. Start a fresh one from the handoff. A short reply to an agent that is mid-task and below its handoff point is fine.
-
Declare a lane before its first launch: a
briefjournal entry in the lane with Kind, Lane, Priority and Uses lines, the same lines the launch prompt carries (see the brief, step 2). For example:Kind: builder Lane: FEATURE-1 Priority: normal Uses: compile, worktree:feature-1Kind stays a property of each launch: the same lane later runs reviewers with
Kind: reviewerandUses: read-only. A builder launched with noLane:line is let through, and atlas reminds you to declare its lane.
Kinds and caps
Every agent has a kind:
- builder writes and compiles code;
- reviewer reads and reviews, and does not build;
- research researches or designs, and does not build.
With agent caps on (atlas settings orchestrate asks for them), atlas denies a launch past its kind's cap. Setup
derives the caps from the machine unless you answer them: compile slots of one per 16 hardware threads (at least
1, at most 4) and 1 gpu slot, then builders equal to the compile slots, as many reviewers, and half as many
research agents (at least 1). A configured value always wins. When a launch is denied, do not retry it: atlas queues it (the
reason names its key), and a task-notification lists what waits when an agent finishes. Then launch the next one
whose kind has a free slot, with the same description and brief (recall KEY reads it); that removes it from
the queue. atlas queue lists the queue, and atlas queue drop KEY removes a launch you no longer want.
The kind comes from a Kind: line in the first 40 lines of the Agent launch prompt itself; a brief file the
prompt names is not read. Without one, Explore and Plan agents count as research, an agent in its own worktree
counts as a builder, and anything else gets the configured default kind (builder). So write the line.
The brief
Keep it lean. A brief is a work order, not a copy of the rulebook.
- Who and what: the lane id, the goal in one or two sentences, and the deliverable (a branch, a PR, or a report).
Kind: builder(orreviewer, orresearch), and the work queue's lines:Lane: <id>,Priority: urgent,normalorbackground, andUses:with the exclusive resources it needs (gpu,compile,worktree:<name>, one port or database such assqlport 15126) orread-onlyfor an agent that shares its lane. Never list repositories: each agent works in its own worktree. Onlygpu,compile,worktree:*and the resources the configuration lists can hold a launch back; any other word (blender, unless it is configured) only adds a note when a running agent uses it too. atlas schedules on declared lines; it only warns on what it infers. A planned item's brief addsQueue: <key>so its launch takes it off the queue.- The rulings that apply, named by their recall key, a heading or a line hint, never pasted whole. "Read
the whole rulebook" costs tens of thousands of tokens before any work starts. The agent pulls exactly what it
needs with
recall,lookuporsearch. Write the brief as compact Gherkin: a Context line, Given lines with the facts, a Scenario per acceptance criterion (its Then lines each a test that fails first), a Spike per research question (its Then names the answer: a table, a verdict against a bar, a number with its unit), one Rules line. Declare each key as a tag, in full every time (@journal:LANE:0012, pinned@journal:LANE:0012#a1b2c3d4), above Feature or above the scenario it serves; the agent's start lists each by key and title. Not0012, 0013after a key, nor0140 onward. - Scope: the files or modules it owns, what it must not touch, and what it is safe to do without asking.
- Verification: the exact command that proves the work, and the numbers it must match.
- Journal and limits: "Journal to lane
<id>. From your handoff point, wrap up at the next clean stopping point and write your handoff; you must hand off by your hard limit." - The report: hand back the digest form. Lead with the outcome (PR, branch, merge, verdict) in the
first lines, then the numbers, every open question under a
## Questionsheading, and every risk (a denied action, an unverified claim, a failure left open). File anything longer (the full notes, tables, logs) as a journal entry and cite its key. The report stays in the orchestrator's context for every later turn, so a line that changes nothing it does is a cost. A report over 28,000 bytes is sent back once: atlas files it whole and asks for the digest form.
Context limits
atlas reads each agent's real context size from its transcript and applies its kind's limits. The defaults on a 1M window are a handoff point at 285k and a hard limit at 450k, and both scale with the window.
- Past the handoff point, the agent is told to wrap up: finish the step, commit, push, and write the handoff.
- Past the hard limit (in enforced mode), every tool except
handoffis denied, and so is a SendMessage to that agent.
When such an agent finishes, atlas tells you to start a fresh agent from its handoff. Depending on the
fresh setting, it tells you to start it or to ask the user first. The fresh agent's brief names the lane and
says to start from recall lane=<id>.
The main session follows the same rule. Near your own limit, journal and hand off, and offer the user a compaction point.
Verify, then merge
- Do not take a report's word for a result. Run the verification yourself, or read its output: test counts, eval lines, the diff.
- Review independently when it matters. Give the reviewer the code and the claim, not your conclusion. Name reviewers by job (simplicity, cost), never by person.
- File each review as a
journalentryreviewwith metarole:,pr:,head:(the sha it read),verdict:andreport:. Withorchestrate.reviewsset,gh pr mergewaits for every role's review of the PR's current head. - Merge only what passed. Then record the merge commit in the lane journal.
Finish cleanly
When a lane completes:
- remove its worktree and its build target;
- close the lane with its handoff;
- say what moved, which questions wait on the user, and what is next.
Ask the user design questions as multiple choice, with the recommended option first.
Hooks 9
MCP servers 1
Sponsors
Details
- Marketplace
- bloodfeast/atlas
- Category
- Productivity
- License
- Apache-2.0