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@atlas

Run it inside Claude Code after adding the marketplace with /plugin marketplace add bloodfeast/atlas.

Contents

Discovered from source

Skills 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

  1. 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.
  2. Journal as you go. A decision, a measurement, a commit or an open question goes into your lane with journal when it happens, not at the end. One entry per fact, the headline on the first line.
  3. Hand off whenever work is left for later. Write a handoff for 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.
  4. Name work by its queue key. Planned work is a queued entry with a key (journal:LANE:NNNN). Say the key, start it with a Queue: line in the brief, and mark it done; never describe it from memory.
  5. Put a Lane: line in every brief, with Kind:, 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. Not 0012, 0013 after a key, nor 0140 onward: name the few that bind.
  6. 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 a journal or handoff entry 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 brief entry carrying the launch lines:

    Kind: builder
    Lane: PARSER-2
    Priority: normal
    Uses: compile, worktree:parser-2
    

    atlas 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; answered closes one, with answers:<key> in refs.
  • next: a step owed. A checkpoint lists the next entries no commit has followed.
  • note: anything else worth keeping.
  • queued: planned work (see the queue below).
  • review: a review for the merge gate, with meta role:, pr:, head:, verdict: and report:.
  • cap, checkpoint and idea are 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 a queued entry over MCP, with meta lines kind:, priority:, uses:, after: and order:). after: lists conditions: a queue key, met when that item is done, or free text, met only when marked with atlas queue met KEY CONDITION.
  • List with atlas queue list; atlas queue next proposes 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, or atlas queue drop KEY for 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 handoff is 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 /clear instead when the last compaction left the session at compact.clear_floor or more. atlas settings auto-compact makes Claude Code's own automatic compaction fire at atlas's hard limit.
  • Before a compaction, atlas asks once for a checkpoint and writes a checkpoint entry in the session's lane: lines of refs (lanes, open questions, owed steps, rulings), never restated text. A /clear writes 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 the turn:...@hash and compact:...@hash keys the compaction card names (transcript turns and older segments; they resolve while compact.enabled, on by default, or memory.transcripts is 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 atlas journal tool: 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 handoff tool. The next agent starts from recall 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 brief journal 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-1
    

    Kind stays a property of each launch: the same lane later runs reviewers with Kind: reviewer and Uses: read-only. A builder launched with no Lane: 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.

  1. Who and what: the lane id, the goal in one or two sentences, and the deliverable (a branch, a PR, or a report).
  2. Kind: builder (or reviewer, or research), and the work queue's lines: Lane: <id>, Priority: urgent, normal or background, and Uses: with the exclusive resources it needs (gpu, compile, worktree:<name>, one port or database such as sqlport 15126) or read-only for an agent that shares its lane. Never list repositories: each agent works in its own worktree. Only gpu, 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 adds Queue: <key> so its launch takes it off the queue.
  3. 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, lookup or search. 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. Not 0012, 0013 after a key, nor 0140 onward.
  4. Scope: the files or modules it owns, what it must not touch, and what it is safe to do without asking.
  5. Verification: the exact command that proves the work, and the numbers it must match.
  6. 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."
  7. 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 ## Questions heading, 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 handoff is 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 journal entry review with meta role:, pr:, head: (the sha it read), verdict: and report:. With orchestrate.reviews set, gh pr merge waits 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.

MCP servers 1

Sponsors

Details

Marketplace
bloodfeast/atlas
Category
Productivity
License
Apache-2.0