Repository navigation
Changelog
Every release has a section here, ## vX.Y.Z, written for users: what changed for them, not how the work
was organised. It is the source of the release notes (through scripts/release-notes.md.in) and of the
wiki's Changelog page. A section has these parts, in this order, and leaves out any that would be empty:
-
### Highlights: what a user notices, with measured numbers where there are any. Required. -
### Breaking changesand### Upgrade notes: what a user must do when updating. -
### Features,### Fixes,### Security hardening,### Known limits: everything else.
cargo xtask release refuses to release a version whose section is missing, empty or has no highlights.
Sections are not written here by hand. Each pull request adds a fragment, changes/<pr>.md, naming its bump
and section, and cargo xtask version folds the pending fragments into one section for the next release, in
the order above, and sets the version by replaying them in merge order (changes/README.md).
-
Copilot and other bot reviews no longer end a PR wait, and your own agents' comments no longer wake you.
atlas pr-events servedrops events from bots and comments by the gh user it runs as, while a person's review, yours included, still meets the wait. The newpr_events.ignore_loginskey silences other chosen reviewers. -
An agent that died in a reboot, or with its Claude Code session, is no longer listed as holding a cap
slot in
atlas queue list,atlas queue nextandrecall op=status(worktree gc still waits for its finish orstale_minutes), andatlas queue releasenow takes the slot number shown in the listing, an agent id or a lane.
-
pr_events.ignore_loginssilences chosen reviewers. An optional list of GitHub logins, compared without case, whose reviews, review comments and PR commentsatlas pr-events servedrops: they meet no wait and surface no notice. Empty by default. -
atlas queue releasetakes a slot number or a lane, as well as an agent id. Each launch gets a slot number when its agent starts, and keeps it: the held-slot listing shows it (#2) the same way with or without--lane, and after other agents start or finish.atlas queue release 2(or#2),atlas queue release IDoratlas queue release LANEfrees that slot and prints the agent it released; a row listed released can be named too. A number no held slot carries is refused, and so is a lane held by more than one agent, which lists each of them. With--transcript PATHthe selector is an agent id in that session. An agent launched before this release has no slot number (it shows as--) and is released by its agent id or lane.
-
Bot reviews and comments no longer end a PR wait or wake the orchestrator.
atlas pr-events servenow drops a review, review comment or PR comment whose GitHub user or sender type isBot, so a Copilot review (loginCopilot, no[bot]suffix) no longer meets areview pr#Nwait, and bot review comments and PR comments no longer surface notices. A login ending in[bot]is still dropped. A person's review still meets the wait. -
Your own agents' replies no longer wake you. The listener reads the gh user once at start (
gh api user, asked of each host served, so a GitHub Enterprise repository asks its own host) and drops review comments and PR comments by that user, so builders replying as the same user stay quiet. A review by that user still meets the wait, since the gh user is also the person reviewing. Enterprise Managed User logins (jdoe_acme) are read too. When gh is not logged in it says so at start and only the other rules apply. -
A cap slot held by an agent that died in a reboot, or with its Claude Code session, is no longer listed
as held. Its transcript never ended, so
atlas queue list,atlas queue nextandrecall op=statuscounted it untilstale_minutes. They now count an unfinished agent as released when the machine booted after its last write, or when the process that ran it is gone (the resident server names it asowner:on each launch entry, only when the first process above it, past any shell or launcher, isclaude,nodeorbun). Without such evidence the agent still counts. Worktree gc does not use this evidence: it keeps a dead agent's worktree until its finish is recorded orstale_minutespasses. The listing shows such an agent asreleased: boot after last write(orowning Claude Code process gone), and the jsonheld_slotsrows carryagent,slotandreleased(a released row is notrunning).
-
A quoted
|,$,;or(in a shell command no longer crashes the atlas server. A routed command such asgrep -n "a\|b\|c" filecould overflow the hook thread's stack and take atlas's tools and hooks out of the session; the check now always ends. -
code.roots[].excludekeeps a package out of the code index. A package that hangs its indexer is skipped outright instead of costing the indexer's whole timeout on every reindex. -
An agent launch Claude Code rejects no longer holds its cap slot, and
recall op=statusandatlas queue listshow which agents hold the slots. -
This release also carries everything listed under v0.8.0, which was never published on its own: Jira and
Confluence tracking with queue items from a JQL search,
atlas worktrees gc, a fast and short--token-report, and the owned SQLite build.
-
Leave a package out of the code index with
code.roots[].exclude. Globs relative to a code root name folders and files the index leaves out:["OctoPrint-Slow", "tools/gen"]. Nothing below a match is walked, so a package that is its own unit gets no indexer run at all, instead of costingcode.timeout_son every reindex, and nothing in it is scanned. An indexer that reads a wider folder anyway (rust-analyzer over the Cargo workspace) has its rows for excluded files dropped.
-
A quoted
|,$,;or(in a shell command no longer crashes the atlas server. The hook check for git writes in a routed command (grep -n "a\|b\|c" file,git log --format="%h|%s") recursed forever on the unclosed quote that splitting at those characters leaves. The hook thread overflowed its stack and the server aborted, taking atlas's tools and hooks out of the session. The check now always ends, still finds a git write after such a quote, and the hook thread has a larger stack as a backstop. -
An Agent launch the tool rejected no longer holds its slot under the agent cap. A refused launch kept
counting against its lane until its timeout, so the next launches were refused or numbered past the cap. The
cap now frees a slot as soon as the launch's error answer is in the transcript.
atlas queue listandrecall op=status(text and the jsonheld_slotskey) list the slots still held, so a stuck lane shows why.
-
atlas reads your Jira and Confluence, and turns a JQL search into queue items in one command.
atlas trackreads issues, searches and pages with a token atlas never holds and prints a digest (a Jira issue about 17x smaller than its raw response on the test fixture, 30x on a live site).atlas queue plan --from-jqlmakes one queue item per ticket, and an item can wait on a ticket's status. -
atlas worktrees gccleans up stale worktrees, their build output and atlas's own Docker objects, and never loses work. A dry run with sizes by default. Anything with uncommitted, unpushed or recent work is left alone. -
atlas --token-reportis fast and short. On a 237 MB store a repeat report takes a median 1.71 s, down from 133 s, and the default view is about 15 lines;--verboseprints the full report. -
An owned SQLite binding, behind the
owned-sqlitebuild feature. It builds atlas over the vendored SQLite 3.53.2 with ed25519-compact as its only crate dependency, and gives byte-identical answers to the default build.
-
An owned SQLite binding, behind a build feature.
cargo build --no-default-features --features owned-sqlitebuilds atlas on its own binding over the vendored SQLite 3.53.2 amalgamation, compiled by atlas's own build script with no build dependency: that build's only crate is ed25519-compact. The default build is unchanged (rusqlite, the same SQLite version). The two give byte-identical answers and open each other's databases. A source build with the feature needs a C compiler (MSVC, gcc or clang). -
Project tracking: read Jira and Confluence directly, read-only, with a token atlas never holds. Name the site and the environment variables in
project_tracking.atlassian(Cloud API token or Data Center PAT);atlas track issue|jql|page|cqlprints a digest (a Jira issue about 17x smaller than its raw response on the test fixture, 30x on a live site) and keeps the full response as a handle,atlas track snapshotwrites a queue item's ticket status, andatlas track checkandsmokeconfirm a setup while printing only shapes and sizes. Writes stay with the Atlassian MCP connector. See the Project tracking wiki page, which also lists the pieces not yet verified against a real site (the Confluence write probe, Confluence through the API gateway, Data Centermypermissionsand the Cloud CQL next link). -
ATLAS_UNATTENDEDtells atlas there is no user, whatever client runs it. A wrapper or SDK harness that is not Claude Code can setATLAS_UNATTENDED=1so that no SessionStart offer is asked, or0to say a user is there. It comes before Claude Code's ownCLAUDE_CODE_SESSION_ATTENDEDandCLAUDE_CODE_ENTRYPOINT, covers every offer atlas makes now and any added later, and a value other than0or1is ignored with one line on stderr. See the Configuration reference. -
A JQL search becomes queue items in one command, snapshots refresh, and items can wait on a ticket's status.
atlas queue plan --from-jql QUERY [--kind K --priority P --order-from N --lane-from key|fixed:LANE --limit N]makes one item per issue, with its lane and ticket the issue key, its title the summary and its snapshot taken from the same search, and skips an issue that already has an open item, so a backlog of N tickets takes one command rather than 2N.atlas track snapshot --all [--older-than DUR]fetches every open item's ticket again, once per ticket, and each ticket a waiting item's unmet ticket condition names (a failed fetch keeps the old snapshot and is reported), and snapshots now record the status category. An--afterconditionticket KEY STATUS(a status name, or To Do, In Progress or Done) is met from the ticket's latest snapshot, with noatlas queue met. Every call is a read. -
atlas worktrees gccleans up stale worktrees, their build output and atlas's own Docker objects, and never loses work. A ledger worktree whose branch is merged (or whose PR was merged or closed), with no running agent and no waiting queue item, is removed withgit worktree remove(never--force), with its linked build folder and itsatlas-linux-target-*volume and stoppedatlas-linux-test-*container. A worktree in use is never stale: a running agent or waiting item holds it, the running agents cannot all be read, it has no commits of its own (new, not done, however far main moves), or it or its linked build folder changed withinworktrees.quiet_minutes(2 hours by default; files are walked last, only for a worktree gc would touch, and the hourly notify-only run makes no quiet-period or guard walk; it only sums sizes, up toworktrees.notify_gb); the check runs again before each removal. A worktree holding any work (changed, staged or untracked files, ignored files outside its build folders andworktrees.disposable(defaulttarget/), unpushed commits, an operation under way, a lock, a stash on its branch, or a check git could not answer) is never removed;worktrees.dirtyreports it (the default), deletes only its build output, or commits, pushes and verifies the work before removing it (refused for an untracked file over 10 MB, a denied name or a line that looks secret, in untracked files or added to tracked ones). Every delete goes through one guard that walks what it deletes immediately before (links and junctions never entered) and refuses on a checkout (.git,.hg,.jj,.svnor a bare repository, at any depth), a secret (a denied name,.envrc, a name that is not UTF-8) or a folder it cannot read: a worktree's whole tree (its ignored and build folders included, its tracked files passed over), the in-treetarget/and the linked build folder. The plan makes the same walk only for a worktree it would delete from, and reports a refusal as work. A build folder that lies inside any git checkout (save aCACHEDIR.TAG-tagged one the repository tracks nothing in), or is, holds or lies in a checkout is never deleted, and one run goes at a time (an operating-system file lock). Other Docker containers and volumes are reported with their verified activity, never touched. Without--applyit is a dry run with sizes;worktrees.auto_gcruns it from the hook at most hourly and after a merged PR, and with it off session start says one line once the stale space passesworktrees.notify_gb. -
Agents work lean by default. The
orchestrateskill's brief gains a "Work lean" step that an orchestrator puts in every brief: find with atlas'ssymbol,lookup,grepandsectionbefore reading, small edits, logs read by their tail, images downscaled before reading, briefs read once, shared scratch files prefixed with the lane, andpr:N head:SHAjournaled when a PR opens. Theatlasskill states the atlas side beside its context limits. An agent waiting on its own background job journalswaiting: <job>, and the orchestrator leaves such a parked agent alone until its next notification (#327). -
Review entries take GitHub's words.
journal entry=reviewreadsapproveandapprovedaspass, andrequest_changes,changes_requestedandchangesasrequest changes, in any case, and files the canonical verdict; any other word is still refused with the list (#325). -
No built-in runq folder. The restart point reads runq holders only when
RUNQ_ROOTororchestrate.runq_rootnames runq's state folder; no machine path is assumed. -
The compaction card names the PR each live agent is working on. A new
agents:line lists each live agent withPR #N @head7 (ready|draft). atlas finds the PR without the agent's help. It checks the lane's newestpr:N head:SHAjournal entry of its own since the launch, then the declared worktree's branch, then a PR event filed for its head. As a last step it runs onegh pr listper repo and branch, all within 1.5 s together. A merged or closed PR is not shown. A failed lookup is named on oneprs:line. The line names at most six agents, running ones first, then+N more, after the card's open, owed, rulings and files lines. The PreCompact instructions end with the same list, so the summary can copy exact numbers. -
A parked builder is no longer shown as finished. An agent the host no longer lists stays on the line as
parked (own job running)while its own newest entry is awaiting: <job> (<worktree or branch>)note. On a shared lane an entry is an agent's own only when it names that agent's worktree or branch (#327). On a worktree reused by a later agent, the earlier agent no longer takes the later one's entries, and the worktree is named once.pr:entries are read in theowner/repo#Nandrepo#Nforms too. A PR counts as merged or closed only when that word follows thepr:value (past anyhead:SHAwords, as inpr:N head:SHA -- merged as abc) or is thestate:/verdict:value, so a hand-back saying "Not merged." keeps its PR on the line. The gh lookup never runs past the hook's own time budget. -
A checkpoint journaled to a work lane is found. The card's
model:line now accepts the model's checkpoint entry from an orchestrator's own lane when this session's transcript shows it wrote it, preferring the session lane (#324). -
linux-test uses the CPUs it is given.
cargo xtask linux-test --cpus N, orATLAS_LINUX_TEST_CPUS=Nwhen the flag is not given, sets the container's CPUs and cargo's jobs to N (default 4); nextest runs max(N, 16) test threads, astest-gatedoes, since the tests mostly wait on processes of their own. N is a whole number of 1 or more, lowered with a note to the Docker VM's CPU count when above it; the startup line prints the count and where it came from. A scheduler that grants the run cores should pass the same number (#334). -
atlas --token-reportprints a short summary;--verboseprints the full report. The bare report is about 15 lines: the calibration date and the answers the ratio is measured over, the measured ratio (mean and median), credit / cost / net, the "Where the savings live" rows under short labels (two or more sources under 1% of both the total credit and the total cost folded into one "small sources" row), the answers and ledger ratio of the 7 days to the newest logged day, and a pointer to--verbose. Every line fits 80 columns. Its figures are the full report's, computed once.--token-report --verboseis the report as it was, byte for byte;--tsv,--repeatsand--transcriptsare unchanged. -
Dependencies are built once, locally and in the development checks.
cargo xtask linux-testruns rustc through sccache (pinned, checksum-verified in the image) in its test steps, with its cache on one shared volume,atlas-linux-sccache(capped at 80 MiB, 0.08 GiB, about twice the 0.04 GiB it was seen to hold), so a new worktree reuses the dependencies another checkout already compiled; the run ends with the hit and miss counts per step.--no-cacheorATLAS_LINUX_TEST_NO_CACHEruns without it, and--clean --allremoves the volume. The development repository's pull request check caches dependencies withSwatinem/rust-cache, which helps that pull request's later pushes and re-runs only; the public CI and the release workflow build uncached (#354).
-
The token report prices re-reads on both sides of the ledger. With
--transcripts, atlas's answers, tool output and routed digests stay in context and are re-read, and so would the grep output, files and raw output they replaced. Each credited counterfactual is now carried by the same priced multiplier as its answer, to the next compaction, or earlier where the counterfactual's larger context would have compacted first; a hook hit's from when it was used, and a repeated lookup's Read as Claude Code's "file unchanged" stub. Tool definitions are re-read by every request, through compactions. Routed digests no longer end with a newline, so the ledger logs the bytes the session receives and the report matches them by size (older rows one byte over still match; pairs are taken nearest in time first, so a row one byte over that is nearer than an answer's own row can still win, tracked in #303). The headline net says it counts re-reads on both sides (45.7M on the maintainer's store, against 4.14M when re-reads were priced on the cost side only; the largest overstatement, different lookups reading the same file, up to 30.3M of lookup credit re-read, is unpriced and tracked in #300), keeps the once-only net (17.8M) beside it, names the share of answers with no transcript, and says why it may be too high or too low, each reason sized where it can be, naming the larger side only when the other holds nothing unweighed. -
The restart point and the compaction card name exactly the agents that are live. An agent waiting on its
own background work (a CI monitor) stays in the restart point after its stop, after the interim notification
and after the atlas server restarts mid-session. Its lane and launch key are read from its launch entry when
the server did not see it start. A finish seen only in the agent's task notification is now recorded in the
store, so the next session's offer no longer lists that agent. A session resumed after Claude Code restarts
is offered its own agents that died with the old process. The card's
lanes:line lists the live agents' lanes first and ends with+N morepast its cap instead of dropping lanes silently. - The token report no longer pairs a routed answer with the wrong ledger row. Atlas now records where rows with trimmed digests begin in the ledger. Only rows logged before that point may be one byte over their answer, so a stray row one byte over can no longer take an answer away from its own row.
-
Reviewer and research subagents start lean. In the default
recall.subagent_context = "recall"mode, a reviewer or research start gets no lane view and no recall pointers (the sub-lane line stays). Its kind is read as the agent caps read it: aKind: reviewer,Kind: review,Kind: research,Kind: researcherorKind: designline, else a launch type mapped inorchestrate.typesor built in (Explore,Plan,claude-code-guideandresearchlaunches are research,reviewerlaunches are reviewers). On eight real briefs the reviewer and research starts went from 2313 bytes to none. Any subagent's start also leaves out the records its brief already names (arecall key=, aQueue:key, a Gherkin tag) and their near-duplicates, so the room goes to the next record, and a lane whose every entry the brief names shows no lane view at all (#275). -
Project tracking works with scoped Atlassian Cloud tokens, and its handles are lossless. Confluence can have its own token (
confluence_token_env, since a scoped token holds one product), read only when a Confluence request is made, so Jira reads and ticket snapshots never need it; a Jira gatewaysitewith noconfluence_siterefuses Confluence reads with the fix rather than sending them to Jira's gateway;atlas track checknames theapi.atlassian.comgateway URL when a scoped token is refused on the site URL, says "unknown (auth failed)" for write permissions after a failed login, reports a 200 that the site answered anonymously as a failed login rather than an empty result, and counts any Confluence operation it does not know as a possible write. An issue handle's JSON item now equals the raw response as a JSON value (pretty-printed) with only the auth material redacted (the account email stays), its JSON and its markdown are separate items (item=json,item=description-md),atlas track jql --fields LIST|*allasks for more fields, andatlas slice --out FILEwrites a whole handle past the 8 KB slice cap (saying "replaced" when the file existed). Credential scrubbing also matches unpadded and URL-safe base64. The Project tracking wiki page lists the token scopes to tick for Jira and for Confluence. -
atlas queue nextcounts the agents already running. Run from a shell without--transcript, it used to count no running agents, so it proposed 8 starts while 7 builders ran under a cap of 8. It now finds them from the launch records atlas files at each agent's start (every session with a launch in the lastorchestrate.stale_minutes), keeps the lanes they hold, and says where the count came from.--transcriptstill reads only the session it names (#305). -
The restart point and the card name exactly the agents that are still running. An agent that stops with
background work, a server restarted mid-session, and a resume of the same session after Claude Code restarts no
longer drop a live agent from the point or offer it as crashed; a resumed session is not offered an agent that a
live server's point still lists. The card's
lanes:line names every live agent's lane first and ends with+N morepast six instead of dropping lanes silently (#306, #309). -
The post-compaction card's
intent:names the task, not the compaction. A closing line such as "Please run/compact." or "handoff written" is skipped for the line before it, and an active/goal(one not cleared) is used as the intent. The card and the resume card now read the goal the same way: a/goal clearrun as a local command is honoured, and a later unmet goal check does not bring a cleared goal back. The resume card now shows a goal set by/goal TEXTbefore any goal check, and a goal too long to show names the record it came from. The card's group header now reads "groups (recall a key for its text):", since a recalled group of one piece has no digest; cards saved under the old header still read back. -
A stored output's hint works where it is printed.
atlas slicetakesrecall's selector form as well as its own flags (atlas slice h:ID lines=1-3,grep="a b",item=NAME), so a hint copied from either works;atlas trackprints its hint in the form of where its output goes (atlas slice h:ID --lines A-Bon a terminal, therecallform otherwise); andrecallwith anh:key and a record argument such asquerysays where the selector goes. A new selector,digest-grep=RE(atlas slice --digest-grep RE), returns the matching digest rows of a handle, every issue or hit of a tracker search rather than only those the digest had room for. -
atlas queue nextstops counting the agents of a session that restarted. An agent last written before its session's recorded start died with the old Claude Code process (a crash or a closed terminal); it no longer holds a slot for the wholestalewindow, soqueue nextno longer under-proposes. A session with no recorded start counts its agents as before (#315). -
No atlas hook runs long enough for Claude Code to discard it. Every hook event now answers within a time
budget,
hooks.budget_ms(default 3 s, at most 10 s), counted from when it arrived. A hook that runs out answers with what it has plus one line naming what it skipped, and a store locked by another writer is waited on only until the budget runs out. A session start no longer waits up to 30 s on the memory store's lock, which could hold the prompt queued behind it past Claude Code's 30 s hook limit.ATLAS_HOOK_TIMINGS=1prints each hook's phases and their times. A gate that can refuse a call (the merge gate, the agent caps, the context cap) still refuses it when its check runs out of time: it fails closed, never open (#329). -
A short shell output is never digested into losing its first line. An output of at most 24 lines keeps every
line, each long one cut to 120 characters (a JSON-object line to 80) with the count it dropped, where a few long
lines used to push it over the threshold and leave only its tail; it does so only when that costs at most half the
output, and no generic digest is ever larger than the output it stands for. A longer output shows its first two
lines beside its tail. Lines that are JSON objects are counted as "N JSONL records" and never match
error|fail|panic inside their strings, but one whose top-level
level,severityorlvlis error, err, fatal, panic, critical, crit, alert, emerg or emergency (any case), whoselevelis an integer from 50 to 60 (pino, bunyan), or whoseis_erroris true (or "true"), is a match and is quoted. A match line too long for the quote budget is skipped, never the end of the quotes, so it hides no match after it; when no match fits, the first is quoted cut to the budget's bytes on a character boundary and marked "...". However small a digest must get, it keeps line 1 and, budget allowing, a quoted match, and its header says "N lines match, K shown" when it shows fewer, counting each match the head, the quotes or the tail shows once (#326). - A tool call no longer fails with "database is locked" when many servers write to one store. A writer waiting on the store lock used to sleep longer the longer it had waited, up to 100 ms between tries, so writers that had just arrived took every free moment first. Under load, one could wait out its whole 30 s behind holds of about a tenth of a second. The vault index and the memory store now check again every 2 ms at most, with the same 30 s limit (#343). So do the other writers to the index database (stored output handles, the token ledger and hook log, compaction rows, embeddings and the code index), each keeping its own limit, and the hook log no longer stops writing for the rest of the session when the lock refuses its first write.
-
atlas pr-events serveno longer loses its own refusal to a connection reset. A delivery refused before it was read in full (a body over 5 MB, or a request still trickling in at the deadline) was answered and the connection closed with bytes unread, which reset it and dropped the answer: the sender saw a broken connection in place of the 413 or 408. The listener now ends its side and drains what the sender still sends for up to 500 ms before closing, so any body a local sender delivers within that time gets its answer (#342). -
No server log line is lost when several appenders create the log at once. Two threads that started a
fresh
atlas-server.login the same instant could share a header temporary, and the second could truncate the log the first had just made, dropping a line another appender had written. Each appender now has a temporary of its own and never truncates one in use. -
Worktree gc never costs a prompt its recall, and walks into submodules. The hook's hourly gc check now
runs after recall, in a time budget phase of its own (
worktree_gcin the timings): when the store is busy and the budget is spent, the check is skipped and retried on the next event instead of recall being skipped. The skip shows in the hook timings only, never in the model's context, and the session-start notice of stale space is still shown. An event whose own work fails still runs the check. Before deleting a worktree, gc's guard now also walks every submodule and embedded repository in it: a worktree with a submodule or embedded repository checked out is kept by gc's own guard (its nested.git; git refused it too). The notify-only run's size is documented as an upper bound. -
atlas --token-reportis fast on a large ledger. The hook hit credit re-read and re-judged every transcript an injection landed in on every run (over 99% of a 133 s report on a 237 MB store). A hit verdict is now stored once its transcript has been still for six hours, as the routed Reads' verdicts are, so a repeat report reads only the transcripts still changing, and quote checks look the record's 8-word runs up in a per-transcript index. A stored verdict, a hit's or a routed Read's, is judged again when the judge changes or its transcript is appended to after it settled. On that store the summary takes a median 1.71 s on a repeat run (17.8 to 23.5 s on the first), with the same output. The summary's title names the answers the ratio is over only when there is a ratio, and a source label over 40 columns is cut to fit.
- Context poisoning guard: hidden text cannot reach a session or a release. Every tool answer, tool error and hook injection drops the characters that draw nothing yet can carry text (bidi overrides, zero-width, tag and Hangul filler characters, variation selectors outside a variation sequence Unicode defines, tag runs other than the RGI flags) and shows terminal escapes as text; emoji, Persian and Indic joiners, bidi marks and the England, Scotland and Wales flags are kept, visible text is left exactly as written, and a write whose text held hidden characters says so. Stored bytes are unchanged.
-
The context poisoning guard's
cargo xtask hiddenchecks every tracked file in CI and before each release, namingpath:line:columnand the code point; deliberate cases go inxtask/hidden-allow.txtby line, with a reason.
-
Agents survive a restart, and the first outside contribution. A shutdown, logoff, closed terminal or
scheduled system restart now leaves a restart point (running agents, lanes, launch briefs, worktrees) that the
next session offers, and atlas warns ahead of a pending restart. Every agent's launch brief is kept on its lane,
so an agent killed early can be relaunched from
recall lane=NAME. Agent context is leaner: two tool schemas are deferred, weak injections are dropped, repository lines appear only where they help, and the binding subagent mode now informs agents at least as well as recall at about an eighth of its tokens. This release also carries atlas's first public contribution: podman's secret values file is now denied, thanks to @serkankose (#13).
-
Every agent's launch brief is kept. At each agent's start atlas files its brief, secrets redacted, on the agent's lane, so an agent killed before its first journal entry can be relaunched from
recall lane=NAMEalone. - atlas asks for terse writing. The server instructions, the bundled skill and each agent's first journal or handoff answer carry one style rule: telegraphic, every key, number, path, commit, error line and quoted ruling kept exact. Journal and handoff text comes back as recall answers, the largest share of atlas tokens, so shorter entries cost less on every read. The tool list is unchanged. The rule costs about 60 tokens at every agent start, through the instructions, and about 60 more in each agent's first journal or handoff answer.
- A restart point before the machine shuts down. On Windows, Linux and macOS a shutdown, logoff or closed terminal writes a small restart point (running agents, lanes, launch briefs, worktrees), and the next session offers it; best effort, it never delays the shutdown.
-
Fewer tool schemas and fewer weak injections in every agent's context.
lookupandsymbolare now deferred behind the client's tool search like the write tools, so their 627 bytes of schema leave every agent's first turn (they were called 12 times a week); the server instructions and the skill say how to load them.recall.inject_floornow defaults to 0.60: on 14 days of hook data that drops 3,480 low-cosine pointers, about 37k tokens a week, with the memory eval and its hook replay unchanged (61/70 informed, 52/70 strict).atlas --hook-report --tune-floornow starts its curve and its recommendation at the active floor: the hook logs only what it injected, so the data cannot speak below it. The UserPromptSubmit hook was eval-gated at 0.60; SubagentStart pointers inrecallmode are filtered by the same floor and are not yet gated. -
Repo lines only where they help, and routed Reads credited honestly. A prompt or subagent brief that names a repository now gets its project-graph line only when neither the text nor the working directory already says where the repository is (a path in its checkout, or a cwd in it or in a worktree of it), and the line now carries the checkout's path. A routed Read now logs its session, transcript and file, and the token report credits it the output it replaced less the later Reads of the same file in the same transcript; rows logged before this upgrade are credited 0, and a row's verdict is stored once its transcript has been still for six hours, so the credit stays when Claude Code deletes old transcripts. The report's routing block and "Where the savings live" row say so. Older stores gain the new
token_logcolumns in place, their rows kept. - Warning of a scheduled restart. atlas notices a pending or scheduled system restart and says so while agents run, writing a restart point first.
-
Outside pull requests on the public repository are welcome. Merged there and tested by the public CI, they are
brought into the next release with their author kept and credited in the changelog; see
CONTRIBUTING.md. -
A subagent started with
recall.subagent_context = "binding"now gets what the brief points at. The Binding block lists every record the brief names, key and title (Gherkin tags such as@journal:LANE:0012, pinned@journal:LANE:0012#a1b2c3d4, a scenario's tags under its name, refs, bare keys, and short continuations likejournal:LANE:0004 and 0005or0004 through 0009in the key's sentence), then its lane's handoff and rulings, which keep their room however many records the brief names, then the newest handoff and rulings of each other lane a named record is filed in. A brief with no lane still gets the records it names. On 30 real launches it informs as many needs asrecallfor every kind (builder 3 vs 2, reviewer 11 vs 11, research 4 vs 4) at about 200 tokens a start against recall's 1,679.
-
remember's help says how long a title and a summary may be. A memory's or a rule'stitlepast 120 characters and a memory'ssummarypast 200 are refused, and a model used to learn that from the refused call.atlas://help,notewithop: "help"and the skill's reference now state both limits on the arguments they bound. The listed tools/list schema is unchanged. - Compaction figures count reads of private paths. A read whose path looked secret was stored blank and left out of the post-compaction window figures; it is now stored as its tool and a redacted target, and counted.
- A bug in hook code no longer takes the server down. A panic while answering a hook is caught: that tool call passes through untouched, a miss is recorded, and later hooks and tool calls are answered as before.
- Agents freed after a full disk stay freed correctly. A disk-full error among parallel tool results is recognised, an agent still waiting on its own background work keeps its lane, and atlas's release records live in its store instead of files beside Claude Code's.
-
Chain keys resolve faster on long sessions. A
turn:orcompact:key no longer re-reads and re-parses its part of the transcript each time: the server keeps the last few parsed ranges, checked against the transcript's bytes, and a group asked for again is answered from the reply it already built. A link's digest also stops reading once its reserve is full. The kept ranges hold at most 16 MiB, parse included, and one unused for ten minutes is let go at the next lookup. - An update check or installed update is never forgotten without a word. When several atlas processes record an update check at once, each waits its turn, and one that still cannot record it within five seconds says so on stderr instead of dropping it silently.
-
The token report says where the savings live. The rulebook brief is now measured from pre-atlas reads (1.68k tokens per agent over 65 pre-atlas subagent transcripts), with the file size kept as "if read whole"; hook injections are split into main sessions per prompt and subagents per agent;
read_noteis marked 1x by design, withsectionthe cheaper read; and a new "Where the savings live" block shows credit, cost and net per source, with Net now counting the measured rulebook saving in place of the SubagentStart hit credit, less what recall by key or lane already credits, since both may read the same records; other lookups that open the rulebook may still overlap it, and the report bounds that overlap by the rulebook row's credit. On a store with a memory store this can lower Net, since the measured rulebook is smaller than the hit credit it replaces.
-
podman's secret values are never read.
secretsdata.json, where podman's file secret driver keeps every secret's value in plain JSON, joins the deny-list besidesecrets.json, so atlas never reads, indexes or keeps a handle of it. Thanks to @serkankose (#13).
- The macOS shutdown path is checked, not run. Its signal code is shared with Linux and tested there; on macOS it is compile-checked only.
-
The first published 0.6 release. v0.6.0 was not published, so v0.6.1 brings everything in its section below:
semantic search that reads the whole of a long section, a rules template for projects that have none, PR file
reads that hide far context behind a marker you can open, and a main session that is told when to ask for
/compact. It adds two fixes: a routed grep that matches nothing can no longer crash the atlas server, and the worktree ledger now finds worktrees on macOS and Windows, where temp and home paths go through a symlink or a short name.
-
A release's version now takes the largest pending bump, once.
cargo xtask versionused to raise the version one step per changelog fragment, so the v0.6 batch would have reached 0.19.0; it now raises it by the largest bump among the pending fragments (breaking over feature over patch), so 0.6.0 with patch, patch, feature, patch is 0.7.0. The changelog check refuses contradictory fragments:section: fixandsection: securityneedbump: patch, an upgrade note takes no bump of its own (bump: noneor none written), and a set of only upgrade notes is nothing to release. -
Onboarding is clearer from the first session. The server instructions say to load the bundled
atlasskill before your first journal or handoff, and to write a handoff before your final answer whenever work is left for later, not only before you stop (also in the skill and the rules template). The resume card now shows the title and next step of the handoff its question asks about, within a 1,155-byte budget (605 tokens on the test's card full of keys). The install page says that a local-folder marketplace runs the plugin from the clone, so the binary goes in the clone'sbin/folder before the first session, and thatatlas doctornames Claude Code's 15-minute wait if the server fails to start. -
journal_statuslists only the lanes that are active. A lane with an open question, a queued entry or a record in the last 14 days is listed. The rest are counted as idle lanes, andall: truelists every lane. - Recall puts rules first when you ask about one. A query with rule, always, never, should or "supposed to" and no kind filter returns rules and memories before other records.
- The journal tool's description names its arguments. It names lane, entry and text, and the meta lines a review entry needs.
-
The README is up to date for v0.6. Its figures are measured again and stamped at v0.6.0: a lookup returns
6.4x fewer tokens than grep and file reads in all (10.9x median, over 7,067 answers), an agent's start injects
108.4x fewer tokens than reading the rulebook, and the memory evaluation answers 100/100 questions at a median 506
tokens. It names Java, Kotlin, Maven and Gradle, drops a stale "more languages are planned", and lists the major
features since v0.3.
cargo xtask release checkandrelease shipnow refuse a README whose stamped figures are more than one minor behind the release, naming each line.
- Semantic search reads the whole of a long section. A section longer than the encoder's 510 tokens was embedded by its head only; it is now embedded as overlapping windows (510 tokens, a stride of 384) and scores by its best window, so a question answered deep in a long section can find it. On 30 held-out questions answered past token 620 of a long section, semantic hit@5 rose from 7 to 18 and hybrid from 18 to 24; on the 15 held-out control questions semantic went from 13 to 14 and hybrid from 14 to 15, and the memory eval is unchanged.
-
A rules template for projects that have none.
atlas --setupnow offers, for the folder it runs in, a starterCLAUDE.mdand.claude/atlas-rules.md: the token-saving rules (compaction summaries as keys, recall before asking, lean briefs, fewer and larger shell calls, no sleep polling, a fresh agent at each handoff), the journal, handoff and multiple-choice habits, and agent, build and safety rules. Each rule is one line and a one-line why.atlas settings rules-template [DIR] [--yes]offers the same for any folder. Where a folder already has rules, nothing is asked or written; a file is never overwritten, andatlas settings undoremoves the files atlas wrote while they are unedited. -
PR file reads hide far context behind a marker you can open. In a
gh pr difffile read, a run of context more than one line from a change is now one line,= N hidden lines=A-B, andrecall h:F lines=A-Breads those lines back exactly as stored. On held-out PR reviews the digest now saves a median 1.47x (up from 1.27x and 1.29x), 1.38x and 1.45x on first rounds, and never less than 1.16x.
-
The first search after upgrading embeds the windows of long sections in the background. On the
maintainers' store that is about 2,390 window vectors (about 1.22M tokens) beside the 8,521 section vectors
already there, which are kept. Until it is done, answers note
windows pending: N windows, M sections not yet splitand each section scores by the windows it has. On a 7,315-section store, 1,970 windows took 408 s on 8 encoder threads. The store's version does not change: an older atlas on the same store keeps working and never deletes the new window vectors. -
The memory store moves to schema 3 the first time this build opens it. The migration only adds the worktree
ledger's table, index and triggers, and changes no existing row. Before it migrates it writes a copy of the
schema 2 store to
memory.sqlite.v2.bakbeside it; if the copy fails, nothing migrates. An older atlas refuses a schema 3 store ("Update atlas"), so install this build for every session at once.
-
A pull request review wakes the session that waits for it (
atlas pr-events serve). A queued item that waits onreview pr#Nis met when GitHub delivers the review, and the waiting session is told at its next turn.serveruns a listener on127.0.0.1that accepts only deliveries signed with a secret it generated (HMAC-SHA256, a new secret for each forwarder start, held only in memory), and onegh webhook forwardper repository in the project'sreposlist, restarted with backoff. A review by the pull request's own author or by a bot meets no wait. Each connection has one 10 s deadline and bodies are capped at 5 MB. -
Hook cleanup deletes only the hooks atlas proved it made. A
clihook is recorded only once a delivery signed with that start's secret names it, and the recorded ids persist in the store, so the next start sweeps what a crashed run left. Another tool's hooks are reported and never deleted. Oneserveper store forwards (a lease with a 15 s heartbeat, taken over after 60 s); others serve the listener only. Remotes on a GitHub Enterprise host are carried through to everyghcall. On Windows the forwarders end with atlas even when it is killed; on Linux gh does, and the extension process it started may outlive it until the next start sweeps its hook. -
atlas keeps a ledger of which lane owns which worktree (
atlas worktrees). When an orchestrated launch is let through and its brief declaresUses: worktree:NAME, the hook records the worktree's owning lane in the memory store: the same lane bumps its row, another lane closes the old span and opens a new one. The ledger is append-only (SQL triggers refuse a delete or a rewrite).atlas worktrees listshows the open rows and stamps the ones whose folder is gone,history PATHshows one path's spans, andbackfilladds a row for each linked worktree that has none. Nothing removes a worktree, branch or folder.orchestrate.worktree_rootsnames the folders a worktree name resolves under. -
What a subagent is given at its start is a setting (experimental;
recall.subagent_context)."recall"(the default) is today's lane views and pointers."binding"gives only the Binding block of the lane the brief declares (itsLane:line, or an exact upper-case id after "lane"), compiled when the launch is let through and matched to the agent by its launch's tool use id, at most 9,000 characters."off"gives nothing from the store. The block is compiled bybinding::compile(#189); the server warns at setup if none is set.recall.main_lane_bytes(default 0, off) caps a main-session prompt to one lane view and a head line for each other lane it names. -
The main session is steered to compact, and a
/clearleaves a checkpoint.cap.main_sessionis on by default and advice only: past its compact point the main session is told to ask for/compact, and once the context after the newest compaction is at or abovecompact.clear_floor(80k) it recommends/clearinstead. Before Claude Code's automatic compaction (its point is computed from the model's window), the session is asked once to write its checkpoint, and a compaction that arrives first waits once for it.atlas settings auto-compactsetsCLAUDE_CODE_AUTO_COMPACT_WINDOWso Claude Code compacts at atlas's hard limit. A newSessionEndhook (matcherclear) writescheckpoint (clear)from the ending transcript, and the next session start injects its card. A subagent past its handoff point under an enforced limit is not compacted: it hands off. -
atlas tells you about updates. One line at session start, once per version, shown to you and not added
to the model's context: a newer release when you are pinned or have updates off, or the release you were
moved to with its signed highlights. When the installed plugin is older than the release that last changed
its hooks or skills (
plugin_changed_inin the signed manifest), the line says to run/plugin. Each running server tells its own session once when a newer atlas is on disk, so you know to reconnect. Many servers on an old version download and swap in the release once between them.atlas settingsoffers an update badge for your status line (atlas --statusline): it becomes the status line when you have none, and follows your own command's output when you have one;atlas settings off statuslineputs your command back, and each session start keeps the badge pointed at the atlas/plugininstalled. -
recallreads a stored output by its handle.recall key=h:IDgives the output's first page, and one oflines(A-B),item,failures,grep(withcontext),head,tail,pageordigestgives that slice, asatlas slicedoes in a terminal;key=h:lists the newest handles. Every digest, capped slice and PR digest now names this form (recall h:ID item=NAME | lines=A-B | grep=RE), notatlas slice, which a model could not run when the binary is not on its shell's PATH. The selectors are refused on any other key.atlas runandatlas sliceprint theatlas slice h:ID --lines A-Bform instead when their output is a terminal. A line over the slice cap is cut to it with a note naming its size (grep=REshows the part around a match), and under projects a handle stored by another project's hook is found in that project's store. -
A Read is now digested only when it opens a tool's saved output (
lean.route_read, defaultoutputs). After a routed Read, agents fetched the same file again within 10 calls 92% of the time (1,045 routed Reads over 11.5 days), so the outline cost more turns than it saved; only saved tool and task output (a path undertool-results/, or a.outputfile undertasks/) came out ahead. Any other file passes whole. A ranged Read, and a whole Read of a file the session already holds a read handle for, now always pass."route_read": "all"keeps the old behaviour,"tuned"digests files from 32 KB (lean.route_read_min_kb), and"off"none; the boolean form maps true totunedand false tooff. A routed Read is still logged in the token ledger but no longer credited with a saving, because the ledger cannot see the follow-up reads. -
A fresh install teaches Claude how to use atlas. The server's instructions, sent in every session, now
carry a short paragraph after the served vaults: what atlas is, the habits (recall before asking, journal
decisions and measurements, write a handoff before stopping, name work by its queue key, put a
Lane:line in every brief) and where the guide is, within a 200-token budget a test enforces. The plugin bundles anatlasskill with the full guide: lanes and sub-lanes, journal entry kinds, the work queue and handoffs, context limits and compaction, and the memory-fidelity bar for changes to atlas. Itsreference.md(every tool, op, argument, journal entry kind, queue command and setting, and theatlas://helptext) is generated bycargo xtask skill; a test fails when it drifts from the code or when the guide names something that no longer exists. No user rules are injected. -
The token report now shows what atlas costs, and the net.
atlas --token-reportmeasures atlas's own context cost from bytes: the tool list and instructions at every session start, the hook injections as sent and re-read until the next compaction, and every tool's output. It nets that cost against the credited savings, by tool and in aNetblock after the headline, and gives the cost per turn and per subagent. With--transcripts DIRit reads Claude Code's transcripts (read only) for tool search loads and re-reads, and prices each re-read by its request's real mix of cache reads, cache writes and uncached input. Without them, the net line says it counts only the costs atlas can see. On one store, cost was 21.6M tokens against 47.7M credited, a net of 26.1M; re-reads of injected text were over half the cost.
- A subagent that starts before its meta file is written no longer takes another launch's brief. Claude Code writes the meta file after SubagentStart answers, so a start almost never knows its launch. Before, it took the oldest launch still waiting, which could be one refused at the permission prompt, with that launch's brief recall and sub-lane. Now a start takes a launch only when exactly one is waiting, or exactly one waiting launch has the agent's type; a refusal seen in the session transcript drops that launch. The agent's first tool call checks the launch against its meta file and, if the start guessed wrong, says so and gives the right context and sub-lane. An ambiguous start is answered at that first tool call. A launch held at the permission prompt for more than two minutes keeps its brief, Binding block and sub-lane.
-
atlas queue met ES1-1981works.show,drop,doneandmettake the lane keyatlas queueshows as well as the fulljournal:LANE:NNNNkey: a lane with one waiting item resolves to it (fordoneandmet, one item waiting or started and not yet done), a lane with several lists their full keys, and a key that resolves to nothing suggests the keys that contain it.--helpprints the usage instead of being read as a key. -
Reviews name repo-qualified PRs. A
reviewentry'spr:takesrepo#Nandowner/repo#N(or arepo:line beside a bare number), and the merge gate matches reviews by repo and number, so PR 784 in one repo no longer counts as reviewed by a review of PR 784 in another. Reviews filed before still count for their number, and filing a review with a bare number warns. Repos are compared as lowercaseowner/repowhatever the form (github.com/o/api, a URL,.git). A refused review says which line was wrong. -
An agent with nothing to classify it by counts as
other. A subagent with no agent type and an empty brief getsorchestrate.other's limits instead of the default kind's. -
A subagent's automatic compaction is judged against its own model's window. atlas blocks a subagent's
compaction past its handoff point only when its hard limit comes before Claude Code's own limit, and it now
reads that window from the subagent's model: its transcript's last real
message.model, else its meta file'smodelalias. Haiku is 200,000; opus, sonnet and fable are 1,000,000 (200,000 withCLAUDE_CODE_DISABLE_1M_CONTEXT). A haiku subagent is no longer held to a 1M window. The newcompact.model_windowssetting maps a model id, or a family alias such ashaiku, to its window; ids and keys match case-insensitively with a[1m]suffix ignored, and an exact id beats an alias. -
An agent that died on a full disk no longer holds its lane for six hours. When the disk fills, Claude Code
never marks the agent finished, and atlas used to keep counting it against its lane, cap slot and resources
until
orchestrate.stale_minutes(360) passed. Now a SubagentStop counts as a finish (an interim stop, while the agent waits on its own background work, does not).atlas queue release AGENTfrees a dead agent at once; it refuses one that wrote in the last 5 minutes unless you pass--force, and it never edits Claude Code's files. An agent whose last transcript message is a disk-full tool error (ENOSPC, "no space left", or Windows' "not enough space on the disk" / "os error 112") stops counting afterorchestrate.disk_full_minutes(default 10; 0 turns it off). -
--token-report --repeatscounts only lookups as repeats. A write after a compaction (journal, remember, note, edit, handoff and the other write tools) is no longer counted as a lookup or a repeat, the unstamped total uses the same 40-call window as the lookup and repeat counts, andrecall {query}lookups carry a stamp so a repeat of an unchanged target is told apart from a needed re-read. On one store, repeats fell from 41 of 122 lookups (33.6%) to 3 of 84 (3.6%). - The token report no longer overstates what lookups saved. Each search, grep, lookup, section and symbol answer is now credited at most the 90th-percentile pre-atlas lookup episode measured from your own history (none when there is no pre-atlas baseline, and the report says so), grep output counts at most 250 lines, and symbol's counterfactual matches whole, case-sensitive identifiers and reads only the files that define the name. Live tool answers do not change. On one store since 2026-11-08, symbol fell from 4359x to 17.2x and search from 45.9x to 2.7x.
-
Routed shell output is credited only what Claude Code would have shown. A routed Bash, PowerShell or
gh proutput now counts at most its first 30,000 characters in the token report, as Claude Code shows no more, and routed reads count no saving, since the reads that follow them are not visible to the ledger. On one store since 2026-11-08, route:Bash fell from 97.5x to 21.8x and route:Read from 24.2x to 0. -
Hook injections earn token-report credit only when they were used. A recall hook's injection is now
credited only when
--hook-reportjudges it a hit, and the report says how many injections were hits. Because that verdict reads memory as it is when the report runs, the hook credit can move as memory changes. The context-selection line drops its "saved" percentage, which compared against a whole-lane injection nobody would send, and keeps the bytes. On one store since 2026-11-08, PreToolUse fell from 76.0x to 7.4x and hook credit from 59.2M to 18.4M tokens. -
The token report headlines the measured mean, and no longer calls its ledger an upper bound. The
headline is now the measured ratio of sums (pre-atlas episode bytes over atlas answer bytes), with the median
beside it marked not additive. The old "upper bound" line is the "ledger ratio (rule-based, not a bound)",
with the per-answer ledger median beside it, in the human report,
--tsv,--calibrateand the wiki. On one store the headline reads 6.4x, and the whole ledger since 2026-11-08 reads 7.0x where it read 26.0x before this release's fixes. - PR digests pair a change block's lines in order, and show a word diff only when it is shorter. A line inserted or removed inside a block no longer unpairs every line after it, and a pair is shown as a word diff only when that is shorter than its two lines. On a held-out set of 16 review rounds from three public repos, the lossless digest's median ratio rose from 1.276x to 1.287x, and no round got longer.
-
The token report's brief and hook injection rows now count the same thing: agents. The "brief without
atlas" row counted every
SubagentStart, and Claude Code fires that again each time an agent resumes, so a resumed agent was charged the rulebook again; the injection row counted agents. Both rows now count each agent once (the brief at the rulebook of its first start, with the resumes named beside the raw start count), and a newbrief vs injectionsline compares the two on the agents both tables hold.
-
Release binaries carry build provenance, and signing checks it. Each binary of a release is attested by
the public release workflow as it is built, and the owner's sign step refuses any binary that was not built
by that workflow, from the public repository, on
mainat the release commit, on a GitHub-hosted runner, so binaries swapped into a draft release after the build are never signed. The published release notes are made again at signing from the changelog at the release commit, so a draft's notes edited after the build are never published. A changelog fragment can no longer cut the release notes short: a## vor###line inside a fenced block (backticks or tildes, indented up to three spaces) neither ends nor starts a section, and a fragment is refused when it leaves a fence unclosed, indents a line of a fenced block less than its opening fence (which ends the block on GitHub), starts a line outside a fence with<(which GitHub reads as HTML that can hide what follows), comments included, puts a#heading after an indent or a list marker or a setext underline (===or---) outside a fence, or holds a control character other than a tab or a line ending (GitHub reads a lone carriage return as a line break). The release refuses a changelog section by the same rules, so the released notes carry no HTML block, no stray heading and no control character.
-
atlas backlogcombs the backlog for ruled work that fell out of the queue. It reads the queue, its marks, briefs, commits, rulings and the user's own words from the memory store, and lists the placed items that are not live (no brief or commit within 7 days, no running agent) and not done: aging items (asked again, their written-order turn came, or placed over 14 days ago, shown with their days), then waiting items, each with its reason and the ruling keys behind it. It only proposes: the written order is never changed.--as-of TIMEreplays any past day,--jsonprints rows,--alladds ruled IDs never placed, andatlas backlog dismiss ID --because KEYsilences a false flag for good. -
The prompt hook points to less, and never to the same record twice in a session. A record pointed to once
is not pointed to again in that session, now also after a server restart or a compaction and under a command
hook (one process per event): the session's earlier injections are read back from the
hook_injectlog. A main-session prompt gets at most 2 pointers (recall.prompt_pointers), the rest counted on the+N moreline, and a subagent whose brief names its own lane gets that lane's journal and no pointers beside it. On the memory eval's 70 hook questions the injected tokens fall 22% at floor 0 (6,369 to 4,958) and 17% at 0.663 (5,654 to 4,693), for 2 informed passes and 1 strict pass fewer at floor 0 (61 and 52 of 70) and 1 informed fewer at 0.663; recall through the tool is unchanged (100/100, facts 176/176)."recall": {"prompt_pointers": 0}removes the cap.
-
A fresh install now recalls within 600 tokens at a 0.53 cosine floor. A configuration with no
recall.budget_tokensorrecall.cos_floornow gets 600 tokens and 0.53 (was 150 and 0.57), the lowest floor that passes the cos_floor sweep on the off-topic set and the 303-prompt hook replay (same frozen store), both arms withrecall.prompt_pointersat 2, the shipped cap. On the replay that is 1 more strict pass (179 against 178), 1 more informed (200 against 199) and 50.3 injected tokens per prompt against 49.9; recall through the tool is unchanged. On the 30 off-topic prompts, 2 of 30 (6.7%) get a record, 3 records in all, the same as 0.57 at 150 tokens, and lane off-topic is 0.03 per prompt on both. Off-topic passing is measured only on that 30-prompt set."recall": {"budget_tokens": 150, "cos_floor": 0.57}keeps the old behaviour. -
The compaction features are on by default (
compact.enabledwas false). Before Claude Code compacts, the PreCompact hook checkpoints the segment and returns instructions for the summary (cite atlas keys, write deltas), which steers every compaction summary; after it, SessionStart injects a card of about 400 tokens naming the segment's parts by key, andrecallaccepts the card's chain keys. Nothing is written into your project's files (theCLAUDE.mdblock stays an explicitatlas settings compact-md). Measured on a 117 MB recorded session: PreCompact 179 ms and the card 56 ms median per compaction (15 ms each with compaction off), and about 8 KB of store per checkpoint (16 checkpoints on a fresh store). It also records which lookups are repeated after a compaction (compact_miss, redacted targets and shell signatures), at onestatper Read, Grep and Glob in PreToolUse: a median of about 40 us per call in-process (p95 under 65 us), against under 1 us with it off. What a user with noCLAUDE.mdblock and a bare/compactgets from the steering has not been measured live.atlas settings off compact, or"compact": {"enabled": false}, turns it off. -
Building from source needs Rust 1.99.0 (was the latest stable).
rust-toolchain.tomlpins it, and rustup installs it on the firstcargocall. -
memory.rules: falseis now the same as unset. Before,falsealso stopped the sync and query recall of the memory folders and rule files your configuration names by hand (memory_dir,intent); now they keep syncing and are recalled as with the key unset. To keep the old behaviour, set"memory": {"rules": "off"}(or runatlas settings set memory-rules off): the store is kept either way.atlas settings off memory-rulesstill removes the key.
-
A task judge for agent launches (experimental, off by default; #156, #161). The
judge_tasktool (note opjudge) gives the model and effort pick for a launch prompt from a cells file, as aJudge:line to paste. Withorchestrate.judge.enabledthe PreToolUse hook adds the same pick as one advisory context line at an admitted Agent launch, andorchestrate.judge.classifier.enabledadds a work classifier's pick. It is advisory only: it never denies or rewrites a launch. Both switches default to false; every key is underorchestrate.judge.*(see the wiki's Configuration reference). -
A new orchestrated install declares starter resources and agent caps (#148). On yes, setup (
atlas --setup,atlas settings orchestrate,--yes) writes the keys you did not answer and the configuration does not set, derived from the machine:orchestrate.resources.compilemax(1, hardware threads / 16), at most 4;orchestrate.resources.gpu1 (a lock, no device is assigned or probed); builders the compile slots (at least 1), reviewers the builders, research max(1, builders / 2), each clamped to Claude Code's own limit (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, 20 by default). New--compileand--gpuflags and settings itemsresources-compileandresources-gpu(0 never serializes) are asked first, so the caps follow them. The handoff point and hard limit are not written. An install that never ran setup keeps the code defaults (gpu 1, compile 1, caps 2, 2 and 1). With orchestrated mode on, a builder launched with noLane:line is let through with one context line asking to declare its lane. See the wiki's Orchestration page. -
A brief writer is its own kind with its own cap, uncapped by default.
Kind: brief-writer(orbrief writer) and the agent typebrief-writernow classify a launch, so writing briefs no longer falls back to a builder and takes a builder slot.orchestrate.kinds.brief-writer.maxcaps it; with none set only Claude Code's own limit applies, and setup writes no starter for it.
-
Only real limits on a
Uses:line hold a launch back (#150). Before, every word on the line was a one-holder lock, so builders that named the same repositories ran one at a time, each in its own worktree. Now onlygpu,compile,worktree:NAMEand the resources your configuration lists can deny or queue a launch; any other word lets it through with a note naming what it shares.sqlport 15126is read as one resource,sqlport:15126, so asqlportentry in the configuration limits each port on its own. -
A queued launch leaves the queue when its lane starts under a reworded brief (#150). A launch with the same
Lane:and kind takes the oldest such waiting launch off the queue and names it, soatlas queue nextstops proposing work that already runs. -
A brief that mentions screenshots no longer claims the gpu (#150). The bare words capture, screenshot,
bench, benchmark and bake now infer gpu only in a project whose
atlas.project.jsonsets"orchestrate": {"bare_gpu_words": true}. Phrases that always mean the gpu (a GPU lock or timing, a frame capture, CUDA, Vulkan) still count everywhere. -
A prompt after a store write no longer reloads every record vector. Any commit (a journal entry from another
agent, the background embedder) made the next prompt re-read all record vectors; now only records whose current
version changed, or that have no vector yet, are read. No record vector is re-read after a commit that changes no
record: on a 1,604-record store, a prompt after a journal entry reads none of the 1,604 (
cargo xtask hook-bench). - Every atlas server now loads the record vectors at start. The background warm-up, which loaded the model, now also reads every record vector, so the first prompt does not. Every server pays it, one that never gets a hook included: the CPU time of one full vector read, and dim x 4 x N bytes resident (2,463,744 bytes for 1,604 records at 384 dimensions).
-
A command hook on a recalling event is said once a session.
atlas doctorsays when UserPromptSubmit or SubagentStart is a command hook (atlas --hook): each prompt then starts a new process that reloads the model and record vectors. A session hears it once: at its first prompt when UserPromptSubmit is the mcp_tool hook, otherwise at SessionStart (a new or cleared session), since with a command hook every prompt is a new process. -
A subagent's report no longer pulls in whole lane views. A prompt carrying an
<agent-messageframe (a hand-back or another session's message) was recalled like a question you typed: every lane it named got its full view, with the handoff, decisions and measurements, plus recall pointers. Now each lane the report itself names (not the harness's frame around it) gets one line,lane X: N entries, handoff NNN <title>, K open; recall lane=X, and a report that names no lane gets nothing; a task notification is unchanged. On a real hand-back that named one lane, the hook's added context fell from 10,496 bytes to 122. - The report backstop sends back only reports over 28,000 bytes, and without a draft (0045). It fired past 14,000 bytes and attached atlas's mechanical draft, which the agent then had in its context as well as its own report. Now a report up to twice the 14,000-byte bound passes, and the one sent back gets the rewrite instruction alone (the report is still filed whole first).
-
The report digest keeps a section's options and stays within its budget (0045). A short line ending in a
colon (
Options:) inside a## Questionssection ended the section, so the options under it could be dropped; now only a Markdown or bold heading does. Lines the classifier does not recognise were never kept; they now fill whatever room is left. The gap marks and closing line now count toward the budget. -
Calibration counts fewer non-lookups (0045). A folder above a project root counts as harmless only as a
cdtarget;grep -r x R:/work notes.mdno longer counts as a lookup. A Grep glob counts as Markdown-only when every alternative of its braces ends in.md(*.{md}yes;*.mdxand*.{md,rs}no).cargo xtask calibrate-baselineneeds--projectfor a configuration with projects, instead of choosing by the folder it is run from. The lookup rules are now version 3, so atlas recalibrates itself once on the new rules. -
An agent of type
builder,reviewerorresearchcounts as that kind. A launch with one of these subagent_types and noKind:line fell to the worktree rule ororchestrate.default_kind(builder); the built-in agent-type map now gives each its kind. AKind:line and your ownorchestrate.typesstill win.
- The aging marker is shown with its days only; it is not a call to pull work forward (only 2 of 21 (10%) read as overdue; 18 read as waiting behind a written order or ruling).
-
atlas calibrates itself. The measured ratio in
atlas --token-reportdivides by a baseline taken from your own Claude Code transcripts: what agents read on rule and handoff lookups before atlas. The installed binary now takes it by itself, in the background at the server's first start (and after an upgrade that changes the lookup rules or a configuration change to the vaults, sources or skips), never on a hook's path; no repository or cargo needed. It finds its own inputs: the cutoff is the earlier of the store's first atlas answer and the first atlas call in the project's transcripts; the transcripts are those whose session ran in one of the project's folders; temporary, scratch, eval and replay folders below the project's roots are skipped (calibrate.skip), andatlas --calibratenames each folder and transcript a skip left out.atlas --calibrateruns it by hand with progress. - No made-up ratio. With fewer than 30 lookup episodes from 5 transcripts before atlas, the report prints the upper bound alone and says why and when it will measure again. Otherwise it says when the baseline was taken, from how many episodes and transcripts, and with which version of the lookup rules.
-
gh pr diffandgh pr viewoutput is now a PR digest by default;lean.pr_digest: falsekeepsgh proutput as before. - A baseline saved before this release has no rules version, so the first server start after the update measures it again. The new measurement counts a call that several transcripts hold (an eval replay, a resumed or forked session) once, and skips eval and replay folders, so on a machine that replayed sessions the measured ratio changes, by a large factor where many replays were counted. The old rows stay in the store; the report reads the newest. A baseline measured by a newer atlas on the same store (with newer lookup rules) is left alone, so an older and a newer binary sharing a store do not recalibrate in turn.
- The first run reads every transcript that started before the cutoff once (a transcript that starts after it is closed after its first line), and keeps what the lookup rules read of each earlier call in the store (tool, the input keys the rules read, folder, result size; never the result's text), so a later recalibration does not lose history Claude Code has deleted since.
-
cargo xtask calibrate-baselinestays for development, with explicit inputs; it now drops copies too (--keep-duplicateskeeps them, to reproduce an older run). - A store that a newer atlas has moved to a newer format is refused, by name, and never written. Before, an older binary opening it
downgraded or rebuilt it, so two versions sharing a store undid each other on every other open. Now the MCP
server still starts and says so: with a newer index store every tool answers with the refusal, and with a newer
memory store the memory tools do, while the vault tools keep working. The CLI and
atlas doctorprintstore too newand exit 1. Every message says to update atlas. v0.3.0 and older binaries do not refuse, so update every atlas binary that shares a store together: the plugin install and any build from source.
-
PR review digests (on by default,
lean.pr_digest). Agh pr diffover the routing threshold becomes one row per file with its own handle and each hunk's line range, lock, generated and vendored files one row each;gh pr viewbecomes one row per body, comment and review with a handle to its text. Each diff is a round of its PR, kept locally with no network call, so a later round, by the same reviewer or another, lists only the files that changed and names the rest as unchanged since round N. See the wiki's Handles and digests page.- A file read (
atlas slice h:F) is the diff as stored, without line numbers or the header lines its row already gives, paged between hunks with anext pageline;--lines A-Breads lines as stored. - An edited line shows once, as a word diff:
~with[-old-]and{+new+}. - A deleted file is one
deletedrow; its body stays behind its handle. - On a later round, a changed file shows only the hunks no earlier round showed, with the whole file one handle away.
- A file is also generated when its first 12 lines in the working tree carry a generated marker (read only when the working directory is the PR's repository); an added marker counts only in the file's first 12 lines.
- Nothing is lost: every line of the diff is in a read or behind a handle the digest names, and the reads decode back to the stored output byte for byte.
On 12 held-out public PRs (18 review rounds), what a review pulls through the generic digest is 1.24x what it pulls through the PR digest at the median (1.31x in tokens), 1.22x on first rounds, and at least 1.17x on every round. A 1.5x saving stays a later goal.
lean.pr_digest: falseturns it off. - A file read (
-
A cap refusal says where the launch's kind came from. The kind is read from the Agent launch prompt's first
40 lines, never from a brief file the prompt names, so a reviewer whose prompt only named a builder's brief was
refused as a builder and told to fix the brief. The refusal now names what decided the kind (a
Kind:line, the agent type,isolation: "worktree"ororchestrate.default_kind) and, when noKind:line did, where one goes. A relaunch that adds aKind:line can name its queue entry withQueue: KEY, so the entry leaves the queue when the agent starts. - A PR digest file read has one bound. All the edited lines of one read share one word-diff step budget; once it is spent, the rest are shown as stored, so a large read stays quick and still exact.
- Every store write checks the store's version under its lock. Each write to the memory store and the index store, side tables and background writers included, now checks the store's version under its write lock, so once a newer atlas has upgraded a store, an older atlas (v0.4.0 or later) that opened it earlier stops writing to it instead of writing in the old format. Memory exports hold the lock across their file writes.
-
Releases are made by one command, with a typed answer per public act.
cargo xtask release ship vX.Y.Z, run twice by the maintainer at a terminal, opens the release pull request from the exact commit it checked, merges it only once he approved its head commit and every check passed (pinned to that head, never with the admin bypass), and publishes behind one more prompt; the signing key's path is checked last and only openssl opens it. The old direct-push release is gone. See the wiki's Releasing page. Whenmainmoves on after the pull request opened, the next run exports the new commit to the same pull request, behind a newopenanswer, and a fresh approval of its new head is needed; a closed release pull request gives way to a new one once its branch is deleted.
- The rules version is checked by a test that hashes the lookup rules' code and
glob.rs; a change elsewhere that alters a result (the JSON or regex engine, the transcript reader) needs a new version by hand. - Without
projectsin the configuration every transcript is read; the vault and source roots decide what counts.
-
Orchestrator mode. An
orchestrateskill teaches the main session to delegate: lanes, lean briefs that name their rulings instead of pasting them, aKind:line, handoffs at a context limit, a fresh agent after every handoff, and verify-then-merge. In orchestrated mode the PreToolUse hook caps how many agents of each kind run at once (2 builders, 2 reviewers, 1 research agent by default, adjustable, clamped to Claude Code's own limit) and denies a launch past its cap with a reason to queue it. It never allows a call. -
Orchestrated mode is asked, not defaulted.
atlas --setupand the first session ask whether you want to work in orchestrated mode, and on yes ask its options: the caps per kind, how context limits apply (enforced, advisory or off), the handoff point and hard limit, and whether a fresh agent after a handoff starts on its own or asks you first. The answers go into atlas's configuration in one change thatatlas settings undoreverts.atlas settings orchestrateasks again at any time, and--yeswith flags or--noanswers without a terminal. -
Context limits per agent kind. Each kind has its own handoff point and hard limit, scaled to the context
window, with
enforced,advisoryoroffmodes. A SendMessage to an agent past its hard limit is refused, and a finished agent that passed its handoff point is followed by a fresh one.
- In orchestrated mode the default context limits are 285,000 (handoff point) and 450,000 (hard limit) on a 1M
window, scaled to the window, per agent kind; a configuration that sets
cap.warn_tokensorcap.block_tokenskeeps its values for every kind without its own. With orchestrated mode off (the default) nothing changes from v0.2: the cap iscap.warn_tokensandcap.block_tokens(450,000 and 500,000), enforced, for every agent, and a SendMessage is never gated. -
journal_statusno longer counts a retired question as open, and the checkpoint card counts a question answered from another lane as closed: both now share the resume card's open-question test, and so doesrecall lane=X. - One title rule for every record: a title is at most 120 characters, cut at a sentence or clause end. A first
line past that (a journal entry, a handoff, a decision,
atlas queue plan --title) stays whole at the top of the body, so nothing is lost; before, journal and handoff titles were cut at 200 characters mid-word and other titles lost their tail. A memory's or a rule's owntitle(or a memory'ssummary, past 200) is refused rather than cut.journalwithamend: KEYnow also amends areviewentry, and a queued launch'sbrief_shafollows its amended brief. - The config lock is atlas against atlas: Claude Code writes
settings.jsonitself and takes no lock, so a change it makes in the same moment as an atlas one can still lose. The offer state file has the same read and write with no lock; its worst case is a question asked twice. - The shell deny-list check catches named files only, since a shell command can hide a path (
F=.e; cat ${F}nv, a link reached aftercd). It over-matches on purpose:grep credentials srcgets no handle, at the cost of one digest. Handles stored before this release stay until they expire, up to 7 days; nothing purges them. - The README's lookup figure, 2.2x (288 tokens per atlas answer against 624 per grep-and-read episode, medians), is
the v0.1.0 measurement on the maintainer's transcripts. The measured ratio that
atlas --token-reportprints is a different measure: your own store's answers against a baseline thatcargo xtask calibrate-baselinetakes from your own transcripts. Its lookup rules changed in this release (stricter about what counts as a lookup, with--project,--skipand--audit), so a baseline saved before gives a different ratio until it is taken again. No figure for it is published here.
-
A resume card for a new or cleared session. SessionStart with
source: startuporclearinjects where the work stands, as keys, in at most 1,160 bytes (612 tokens on the test's card full of keys, at 1,119 bytes, by a public vocabulary times a fitted factor, not real tokens): the live lanes (each with its open questions and newest handoff), their open questions for you, after a/clearthe agents still running, the work queue's head and the batch that can start now, handoffs from the last seven days, and the previous session's goal when it was not met, never cut: a goal too long for the card is named by where it is in the transcript. Claude then asks you, as one multiple-choice question, whether to resume, change the plan, or do something more pressing first. An empty store gives no card;memory.resume_card: falseturns it off. -
A queue for refused launches. A launch the agent cap refuses is filed as a
queuedjournal entry in its lane, with its brief, and the deny reason names the key. When an agent finishes, the notification lists what waits; launching it again with the same description and brief takes it off the queue.atlas queuelists the queue,atlas queue show KEYprints one, andatlas queue drop KEYremoves one. -
Work queue lanes. Every queued item has a lane, a priority (
urgent,normal,background, with aging so nothing starves) and the shared resources it uses (gpu,compile, a worktree, any name you configure), each read fromLane:,Priority:andUses:lines in the brief or inferred from it; a declaration always wins. Items on the same lane run one at a time unless declaredUses: read-only, and a resource serializes across lanes. When an agent finishes, atlas proposes the batch that can start together and says why the rest wait;atlas queue nextshows it on demand andatlas queue addfiles planned work. A launch that conflicts with running work is queued when both sides declared the conflict, and warned about when atlas inferred it. Planned work waits on other items (after: KEY, met when KEY is marked done) and leaves the queue when a launch names it withQueue: KEY. An agent files planned work over MCP with thejournaltool'squeuedentry, checked asatlas queue planchecks it. -
Required reviews before merge. With
orchestrate.reviewsnaming roles (["simplicity", "cost"]), agh pr mergewaits until each role has a passing review of the PR's current head, read fromgh pr view. Reviews arereviewjournal entries (role:,pr:,head:,verdict:,report:); notes withreview:meta count too. A request for changes blocks its role until a newer head passes. Enforced mode denies the merge, advisory (the default) warns, and no roles leaves the gate off. - Digest-form reports. The orchestrate skill asks agents to hand back the outcome first, then the numbers, the open questions under one heading and the risks, with longer notes filed in the journal and cited by key. In orchestrated mode a report over 14,000 bytes is sent back once, at the agent's stop: atlas files it whole in the lane journal and asks for the digest form, with its own draft attached.
-
Experimental, off by default: chain keys on the compaction card. With
compact.enabled, the card names every part of the segment by a key onerecallresolves from the transcript.memory.transcriptsalso letsrecallresolve them. Not yet scored live.atlas --compact-reportno longer lists atools:line, so its card size and coverage lines change and do not describe the live card. -
Experimental, off by default: memory rules. Nothing asks about it.
atlas settings set memory-rules truehas atlas find a project's Claude Code memory folder and rootCLAUDE.md, and a query that hits a replaced ruling answers with the one that holds.atlas settings off memory-rulesgoes back to unset. On a test set, not a promise: the ruling that holds came first more often (hook 19 to 33 of 46, query 23 to 43), but the 1.5x token bar was missed (hook 1.027x, query 0.921x, so a query costs more),memory-evalstrict pass fell from 98 to 82, tokens per question rose 13%, and the labels are circular, 21 of 46 not reviewed by the maintainer. The known limits are on the wiki's Memory and rule files page. -
Experimental, off by default: idea capture. With
memory.ideas.enabled, a person's standalone statements that propose, decide or constrain something are filed as pendingideajournal entries in their exact words, redacted, so an idea said in passing is not lost;atlas ideaslists, files, dismisses and converts them. The detector is a linear score with no model; its weights come from one author's labelled prompts and are untested on anyone else. Asking you about an unsure capture is built but unproven in a live session, somemory.ideas.asks_per_daydefaults to 0 and nothing asks. Off, it reads and writes nothing. -
Compact instructions are no longer offered. Neither SessionStart nor
atlas settings offerraises the block, which costs about 380 tokens per session and agent and inCLAUDE.mdalone showed no reliable effect on the summary.atlas settings compact-mdis the only way in, and its prompt now says what was measured. -
Experimental, off by default: the PreCompact hook returns the Compact instructions. With
compact.enabled, a compaction's summarizer gets the instructions (336 tokens) without aCLAUDE.mdblock or a/compactargument. The route steered the summary in one manual run each by command hook, stub and the real atlas tool on Claude Code 2.1.318, with no plain control on that version; the automatic trigger is untested. On a manual/compactthe text also lands in the conversation aslocal-command-stdout, about 340 tokens on each later request until the next compaction; the automatic path is unread. A project with the block gets the text twice and should drop it.
-
The agent cap no longer counts a started or finished agent twice. A launch's pending record now ends at
the agent's SubagentStart (or once its meta file is seen, running or finished). Before, with a hook input
that carried no
tool_use_id, every agent counted twice for two minutes ("3 of 2 reviewer slots ... 2 launched moments ago" with one reviewer running), and an agent that finished inside two minutes kept its slot. -
Reviews wait only for a reviewer slot. A
Kind: reviewerlaunch no longer holds or conflicts on a lane, so both reviews of one PR run together beside the lane's builder.atlas queuelists waiting reviews as their own queue. -
A fractional queue order is read.
order: 9.5read as no order, so it listed bare and after every whole number of its priority, and a proposal ignored it. An order is now an exact decimal, compared digit by digit and printed as written (#9.5), andatlas queue plan --orderand thejournaltool file one. -
atlas doctorchecks the atlas hooks in Claude Code'ssettings.jsonagainst the plugin'shooks/hooks.json: each event with no atlas hook, and any missing or extra input field per event. A session's first prompt says so too. -
Concurrent config changes no longer lose a write or fail on the backup. Every
atlas settingschange,atlas grammar acceptandatlas settings on|off updatenow holds a lock from before its read through its write, and takes a backup name no other process can hold: two sessions adding a project at once both keep their source, and each change has its own undo. A change waits up to 30 s for another one, saying so once, then stops with an error naming the lock file; a process that dies releases its lock. Questions are asked before the lock, and a question's answer is applied to the file as it is afterwards.atlas settings undorefuses when a newer change came after the one it showed. -
A second project no longer makes your home folder a project root. Following "One repository" then "A folder
of repositories" gave the first project a root of the home folder, because the starter vault under atlas's
configuration folder counted towards it, so no folder under home was ever asked about. A moved setup's root now
leaves that folder out, and no root is ever the home folder, a folder holding it, or a drive root: each folder
gets its own root instead.
add-project --newrefuses those folders and says what to do. With projects, a folder in no project and holding no repositories is now asked about once, as on a fresh install; before, only folders of repositories were. It still readsdefault_project, which is unchanged. A configuration that already holds such a root is not rewritten:atlas doctornames it. -
--memory-checkno longer reports corruption because another session is writing. It reportedcopy:,disk:andround trip:problems on about 6 in 10 runs beside two writing sessions, and none once they stopped. Chains, copy and round trip now read one snapshot of the store; a file that differs from its export is taken again under the store's write lock, for up to 6 s, since an export is written just after its commit. A real fault is still reported, by the same prefixes and exit code, while writers run. A real disk mismatch makes the check take those 6 s. -
A handoff is no longer refused when two sessions hand off on one lane. The lane's active handoff is read
under the write lock. Before, about 1 handoff in 200 under load failed with
already superseded, and two on an empty lane could both stay active. -
atlas doctorsays what it checked. With nosettings.json, or{brokenin it, it said the hooks match, and a plugin install always got that answer. No file, no atlas hooks in it, a malformed file and a plugin install now each have their own line, and "match" is only said of real hooks that match. A malformed or unreadable file now exits 1. It also names a project root at or above the home folder, or a project file there, without changing it; that is not a failure. -
A large secret read through the shell is not kept as a handle. The Read tool's path was denied; Bash,
PowerShell,
atlas runand Grep were not, socat .env.bigover the threshold sat in plain text understate/handlesfor up to 7 days. Output is no longer kept when the command names a deny-listed file, however it is quoted or chained, or a word in it is a link to one. The command still runs and its output still shows. -
The README and wiki name what
atlas settings offeroffers. They still listed an early compaction point, which is no longer offered; it offers the 1-hour subagent cache and goal check-ins. - The security page says what holds for prompt-shaped notes. It said note text comes back only as a JSON string; by default it comes back as plain text, as written, and nothing marks it as data. The README's memory evaluation row now says it is from v0.2.0.
- Figures with no source are gone. The README's 236 KB and 87 KB rows, the about -20% lane cost in the settings text and the 48 ms a clause in the wiki had nothing behind them a reader could check. The wiki keeps the first run's figures, marked as one unpublished run.
-
--helpwrites nothing.atlas settings --helpwrote the first-run configuration before reading its arguments, and failed on a malformedsettings.json;queue,ideas,rulesandrulingopened a store first, andrulesandgrammarhad no help. Help on any subcommand now touches nothing.atlas --helpalso listsideasand the queue'sdone,metandplan. -
A Grep of one file no longer reads as no matches. Over the threshold, a search of a single file prints
12:textwith no path, and its digest said0 hits in 0 files, which a model took at its word. The digest now counts those lines and quotes them. Bashgrepwithout file names reads as a plain log, with its line count. A file whose name starts with digits (0001-init.sql:5:x) is named as a file. -
A filtered
recallfinds what matches and says when it cut.scopeandkindwere applied after the search's window, so records elsewhere could use it up: five matching records could read asno records match, and a list cut short had no+more. The search now reads on until the list is full or the matches run out, andlimit: 0says when its 8 rows cut anything. A filter also keeps all the query's words, up to 48: over 12 known words, the search kept the rarest in the whole store, and a scope's only record could hold just the others and read asno records match. Past 48 the answer says how many went unsearched. -
memory.rules: falseandtrueno longer answer a false "none". Underfalse, the hidden rules and memories were dropped after the limit, so eight of them at the top read asno records matchwith a journal entry ranked ninth, and the hook injected nothing the same way. Undertrue, a replaced record whose successor is gone held a row of the limit and showed nothing. Both are now decided before the limit. Unset is unchanged. -
A word with diacritics is found. The search folds them and the check for known words did not, so
recallforMülleransweredno records matchover a record holding it, and the hook passed it over. -
The first-session question comes back until it is answered. It was marked asked when the line was made, and
Claude relayed it in about 4 of 9 test sessions, so it was often never asked at all. A new session now asks until
you answer, and no is recorded with
atlas settings add-project --no DIR,atlas settings orchestrate --nooratlas settings offer --no. The Claude Code settings question is one of these now, at most 60 tokens a session; a yes or a no to it is no answer to the orchestrated question. The "on by default" notice is shown once. Ignoring it means hearing it again at each new session; a resume or a compaction does not repeat it. Folders already marked as asked stay that way. A session with no user (claude -p, the SDK) asks nothing, so its stdout stays yours, and spends no question: atlas readsCLAUDE_CODE_SESSION_ATTENDED, elseCLAUDE_CODE_ENTRYPOINT, which Claude Code sets for its hooks but does not document; with neither it asks. A state file that cannot be written means no question at all, rather than one that returns forever with a--nothat fails. A yes counts once it lands: not when the write failed, at a terminal or with--yes, and not when the setting needs a newer Claude Code (the command then exits 1, and the question stays at each new session, at a terminal's answers too, until the upgrade or--no).offer --yesnames what to turn on: bare it is refused, and an atlas switch named there answers nothing. -
atlas doctornames Claude Code's 15-minute wait. After one failed start of the server, Claude Code does not start it again for 15 minutes, even with the cause fixed unless the fix changed its command, which reads as the fix not working. atlas cannot change that; the wiki now says so, and the doctor names the wait when it can see it. - Compaction's summary is not filed as an agent's report. Its summariser fires SubagentStop, so in orchestrated mode a long summary hit the report backstop, was blocked, and was filed whole as a report. It is now left alone.
-
Test digests name more failures. A
cargo test --nocapturefailure with no---- NAME stdout ----block is named from libtest's closing list with its panic; nextest's currentstdoutandstderrblocks are a failure's block, anderror: test run failedis not a build error; a check log's summary keeps the line naming its detail log; aNAME: FAILEDverdict is kept likeNAME: FAIL; and overlapping--failuresitems are shown once. -
Compaction hooks no longer read the whole transcript. The checkpoint and PreCompact hooks read only the part
since the newest compaction, so their time no longer grows with the session's history. A checkpoint's turn refs
now carry a byte offset (
turn:...:b<offset>@hash); line refs written before still resolve. -
recall {query}says what it left out. Records scoring near zero were dropped with no word, which in a small store can be real matches (4 records held the words; 2 came back), and the limit cut silently too. The answer now ends with+N more scoring near zeroand+more (limit=L).
-
--memory-exportrun beside servers that are writing can make a write answerexport refused: ... present and never exported by atlasfor a while; the write itself is stored, and a later export clears it. Seen only under heavy load with exports and side commands running. - Under heavy writes
--memory-snapshotmay printsnapshot skipped ... run it again. Nothing is lost; run it again when the store is quieter. - The first
add-projectdiff can mark unchanged template lines as changed. The change itself is what it says.
A patch release with two fixes for the hooks.
-
Every hook call is accepted again. Claude Code sends
tool_use_id(and, on SubagentStop,last_assistant_messageandstop_hook_active) to thehooktool, which did not declare them, so every PreToolUse hook call failed its schema check. The schema now declares every inputhooks/hooks.jsonsends, and a test checks each one throughtools/call. -
Git writes are no longer routed. The routing hook sent any command starting with
gitthrough its digest, so a failinggit pushorgit commitcame back as a tail with exit 0 and the failure was easy to miss (bloodfeast/atlas#3). Only read-only git subcommands (status,log,diff,showand the like) are routed now; a write anywhere in the command (after&&,;,sudo,env, inside$( ), backticks orbash -c) runs unrouted. A routed command that fails says so in the context with its exit code.
- A read behind a quoted
-Cvalue (git -C "$(git rev-parse --show-toplevel)" log) also runs unrouted: the safe direction, losing only the digest.
The code index reaches past Rust to six more languages, the tools and hooks cost fewer tokens for the same answers, a new project gets its own vault, and the memory store holds up under several sessions at once. The full list is under Features and Fixes below; the upgrade notes say what an update re-indexes and what changed in the tool list.
-
Go, TypeScript and JavaScript, C#, Python, Java and Kotlin are indexed.
symbol, Read notes and Grep annotations work for them out of the box: through each language's SCIP indexer when it is installed (atlas never installs one), and through an owned scanner otherwise, which finds 98.8% to 99.8% of the indexer's definitions on the measured projects. A prebuiltindex.scip, written by CI or in WSL, is read too. -
symbolfollows gRPC and crosses repositories. A.protorpc answers with its generated stubs in every language above, the calls made through them and the server types that implement it; a library's definition answers with the call sites in the code roots that use it as a package. -
Test digests for more runners:
go test(plain and-json), pytest, Maven and Gradle,dotnet test, jest and vitest, each with its totals and each failing test with its message and location. -
A quarter of the tool list.
tools/listis 14 tools and about 1,480 tokens (it was 47 tools and 5,930), with every op described in theatlas://helpresource, and every answer is plain text unless you ask forformat: "json". The v0.1 tool names still work in this release. -
The hooks inject less for the same answers. Context selection (on by default) sends a record that
restates one already injected as a one-line pointer and trims each pointer to the clause that matches the
prompt: injected tokens 6,744 -> 6,369 on the memory evaluation at equal or better pass rates, lane briefs
17,709 -> 14,308. A repeated read answers
unchanged since your call #N, and the recall hooks can be given a per-session budget. -
Exact references. Refs are content-addressed (
key@hash,src:path:a-b@hash), sorecallreturns the exact text a ref named or says it changed;read_notetakes line ranges and a token budget. -
A project gets its own vault. The first session in a folder atlas does not index offers to create one,
and
atlas settings add-project --newworks on a fresh install: it moves the current setup into a project itself, shown first and reversed with the new project by one undo. add-project writes into the right project's entry of a multi-repository configuration. -
atlas settings undoshows what it reverts and asks first (without a terminal it needs--yes). -
The deny-list holds everywhere.
.env*, key and credential files are never indexed, read or written through a vault,atlas digestandatlas croprefuse them, and a denied file is never kept as a handle. -
The memory store under several sessions. Two sessions writing at once no longer get errors for
committed writes, a session killed mid-write no longer leaves
--memory-checkfailing, and a note being replaced by another program no longer reads as missing. -
Experimental, off by default: compaction support and session transcripts as a source. Nothing of it runs
unless you turn it on (
compact.enabled,memory.transcripts); see Features.
-
atlas settings add-projectwith no folder named (and no--yes) now only shows what it would do for the current folder, and writes nothing; it used to add the current folder. Name the folder (atlas settings add-project .) or pass--yesto write. - The 47 tool names of v0.1 (
read_note,list_notes,create_note,decision_queue,ids,supersede,journal_statusand the rest) still work as tool names in this release but are no longer listed; v0.3.0 removes them. Calls that read a JSON answer fromread_note, a write tool or a discussion tool addformat: "json". A permission allowlist naming the old tools (mcp__atlas__read_note) needs the new ones (mcp__atlas__note,mcp__atlas__edit,mcp__atlas__discuss,mcp__atlas__miss). - The code index schema is
code-7, with newcode_unitsandcode_packagestables. A v0.1 database is migrated in place on first use: its rows stay and answer at once, and every code root is re-indexed once in the background, to record its packages. - A code root holding Go files is re-indexed once after the update (its Go files are now indexed as Go); a root of Go alone no longer reports a Rust unit.
- A code root holding TypeScript or JavaScript files is re-indexed once after the update, and its
symbolanswers name the new units in their note. Units in test-input folders (fixtures,testdataand their kin) are indexed but not named there. - A code root holding Python files, or an
index.scipfile in a unit's folder, is re-indexed once after the update; such a file is now read as that unit's index (code.roots[].scip: falseturns this off). - A code root holding C# files is re-indexed once after the update. A C# explicit interface member is now
stored under its own name (
GetEnumerator), not its interface-qualified one. - A code root holding Java or Kotlin files is re-indexed once after the update.
- A code root holding
.protofiles or generated gRPC code is re-indexed once after the update; its rpc call sites in comments and strings are gone, and calls through generated stubs are of kindrpc.
-
Refs are content-addressed. A ref names exact text:
key@hash(a record version) orsrc:path:a-b@hash(lines of a vault or source file).recall {key: "key@hash"}returns that version verbatim, or says it changed or dangles, andrecallresolvessrc:path:a-b@hashlines refs. -
Experimental, off by default: compaction support. Not yet tested live, so none of it runs unless you add
"compact": {"enabled": true}to atlas's configuration (atlas.json); existing setups get nothing new. With it on:- PreCompact writes a checkpoint (journal entry kind
checkpointin lanesession:<id>): the active lanes and their current step, open questions, owednextentries and new rulings askey@hashrefs, plus the in-task state a mid-task compaction would cut (files touched, the last tool calls withturn:result refs, a pending call, the last visible line of intent). Only visible content is read; thinking is never read or stored, and every transcript-derived line passes secret redaction. The card lists lanes and rulings only from the active project's own store; with no project it keeps to the session's own lane. A transcript Claude Code has not written yet is waited for briefly, then read from the session it was forked from, and a checkpoint that still has none saystranscript unreadrather than "0 context tokens". - After the compaction the SessionStart hook injects the checkpoint as a card (
compact.card_tokens, default 400), checks every ref in Claude Code's summary and reports changed or dangling ones. Each compaction is logged with its ratio, a lookup repeated after a compaction is logged as a post-compaction miss, and--token-reportends with the compaction line. -
atlas settings compact-mdoffers, once per project, a Compact instructions block for the project'sCLAUDE.md(nothing written without a yes;atlas settings undoremoves just the block). With compaction off it changes nothing and says how to turn it on. -
compact.defer(off by default even then) holds a proactive automatic compaction until the running tool chain ends, never past a hard ceiling. - The offline measurement works either way:
atlas --compact-report --transcripts DIRreplays recorded sessions (numbers only) with the card's size and coverage, the hooks' latency and--sweep T,T,...(the token side of each compaction point, plain and atlas paired per threshold);cargo xtask memory-evalgains (g), answers that survive a simulated compaction as refs;cargo xtask compact-livestages the live head-to-head (it spends Claude usage, so it is run by hand). Design:docs/design/compaction.md.
- PreCompact writes a checkpoint (journal entry kind
-
Session transcripts as an opt-in source. With
memory.transcriptson (off by default), each compaction indexes the session transcript's visible turns (never thinking), secret lines redacted and a secret file's read result kept out whole.recall {key: "turn:<session8>:<line>@hash"}returns the exact earlier turn andrecall {query, kind: "turn"}searches turns; both see the asking project's turns only. Withcompact.enabled, the ref check after a compaction resolvesturn:refs too. Threat note:docs/design/compaction.md, section 9. -
The tool list is a quarter of its size.
tools/list, sent every time a client loads the tools, is 14 tools and about 1,480 tokens (it was 47 tools and 5,930). The note, write, discussion and misses tools sit behind four tools with anopargument (note,edit,discuss,miss);lookupwithout an id lists identifiers,rememberwitholdsupersedes, andrecalltakesop: "status"andop: "log". Listed schemas name only the common arguments; every tool, op and argument is described in one fetched text, the MCP resourceatlas://help(ornote {op: "help"}). Measured on the 100-question memory evaluation: the same answers, every fact found. -
Every answer is text by default.
read_noteand the other tools that answered only in JSON now answer in plain text, andformat: "json"gives the JSON on any tool.read_noteis onevault:path sha256=...line then the note as written, without the parsed frontmatter repeated beside it. Lists keep every item: the work-queue tools are never cut. -
The recall hooks have a session budget, and a weekly misses pass.
recall.session_budget_tokenscaps what one session's (or one subagent's) recall injections may use in all; past it the hooks inject nothing more andrecall {query}still answers. It sits beside the per-promptrecall.budget_tokensand the confidence thresholdrecall.inject_floor; the defaults leave injection as it was (no session cap, floor 0) until both are tuned on hit data.--token-reportprints ahook injectionsline beside the "brief without atlas" row, to judge the pointers against the brief they replace, andatlas --misses-week [--since TIME]lists the ten open misses seen most in the last seven days and the ten injected keys that cost the most. -
The hooks inject less for the same answers (context selection,
recall.select, on by default). A record that restates one already injected (the rule kept in INTENT and in a memory file) is sent as- KEY: near-duplicate of OTHER, judged by both the records' cosine and their words, one way, so a record that adds something is never hidden. A pointer carries the clause of its record that matches the prompt in place of its first line, and a lane brief keeps its handoff, brief, open questions and next step whole while older entries are cut to their matching clauses. Every excerpt is an exact substring of its record. Measured on the memory evaluation's hook replay against the same replay with selection off: injected tokens 6,744 -> 6,369 (floor 0) and 6,049 -> 5,654 (floor 0.663) at equal or better pass rates (informed 62 -> 63, strict 52 -> 53 at floor 0), and lane briefs 17,709 -> 14,308 with every lane question still answered from the injection alone.--token-reportgains acontext selectionline with what trim and collapse saved. -
A repeated read is one line. A read tool called again with the same arguments answers
unchanged since your call #N, or only the lines that changed, and the reply namesfresh: true, which gives the whole answer. With the hooks on, the PreToolUse hook names the agent and repeats are per agent, and a compaction forgets the session's answers; without them, repeats are per server process, so a subagent asking what its parent asked follows thefresh: truethe reply names (measured: every fact reached). The work-queue tools and lane journals always answer whole. Measured on the memory evaluation's 100 first calls made twice by one agent: the repeats cost a fraction of the first pass, with every fact the first pass found. -
Line ranges.
read_notetakeslines(A-B) orbudget_tokens(whole lines up to about that many tokens, then a+N more lines (lines=A-B)line). A recordrecall {key}reads names the line of its source file it came from (@L1234, or@path:linewhen the key does not name the file).read_notealso reads a source's files, andrecall.pointer_anchors(off by default, as measured) puts@src:path:lineon everyrecall {query}pointer. -
symbolfor Go, TypeScript, C# and any other language with a SCIP indexer.atlas --code-index NAME --scip FILEnow reads an index from scip-go, scip-typescript, scip-python, scip-java, scip-dotnet or any other SCIP indexer, not only rust-analyzer's: definitions with their kinds and ranges, references with their callers, and impl edges from the index's implementation relationships (Shape for Square). Indexes without kinds or enclosing ranges (scip-dotnet, scip-python) get kinds from the definition's line and ranges from the brace matcher. Rust results are unchanged: the same rows, byte for byte, on atlas's own source. -
Go is indexed out of the box. A code root's Go modules (each
go.mod) are indexed by scip-go when it is installed (found onPATH,GOBIN,GOPATH/binor~/go/bin; atlas never installs it), in the background the way rust-analyzer runs, and by an owned scanner otherwise: definitions, kinds, containers and item ranges, sosymbol, Read notes and Grep annotations work for Go with nothing installed. An edited Go file has its ranges right again at once. Measured on gin (98 files, 24k lines) against scip-go 0.2.9: the scanner finds 99.7% of scip-go's definitions with no false ones and agrees on 100% of item end lines; the scip-go rows hold everyfunc,type,varandconsta grep finds in the files scip-go indexes, and the scanner covers the files behind build tags it skips. -
go testdigests.go testoutput (plain or-v) gets a digest likecargo test's: totals by test and package, each failing test or subtest with itsfile_test.go:LINEmessage, a panic with its first frame outside the runtime, andatlas slice --failuresover the failing tests' output. - Newer SCIP files decode. The typed ranges that scip-go 0.2.9 and other newer indexers write instead of the deprecated packed ones are read; before, such a file failed with "occurrence range is not 3 or 4 values".
-
TypeScript and JavaScript are indexed out of the box. Each package of a code root (the shallowest
tsconfig.jsonorpackage.json, with its workspace members) is indexed by scip-typescript when it is installed (found beside its shim onPATHor undernpm root -g; atlas never installs it and never runs a package manager), and by the owned scanner otherwise. A package whose dependencies are not installed is still indexed by scip-typescript from its own sources, unless atsconfig.jsonof it extends a package (scan only: no node_modules: run npm install, said too when such a run fails). A JavaScript package without atsconfig.jsongets one inferred into atlas's own folder, so nothing is written into the project. Measured on got (92 files, 67k lines) against scip-typescript 0.5.2: the scanner finds 98.8% of its definitions (every type, function and method) and agrees on 99.8% of item end lines; the scip-typescript rows hold every top-level declaration a grep finds in the files it loads. On microservices-demo's currencyservice and on express (JavaScript, 142 files, 22k lines, indexed withoutnode_modules): 100% on all three. -
C# is indexed out of the box. Each solution of a code root (a
*.slnor*.slnxclaims its folder's projects; a*.csprojoutside every solution is its own unit) is indexed by scip-dotnet when it is installed (found onPATHor in~/.dotnet/tools; atlas never installs it), and by the owned scanner otherwise. scip-dotnet restores the solution's packages and runs a design-time build itself, so generated code such as gRPC stubs is indexed; a failed run names the .NET SDK theglobal.jsonasks for. scip-dotnet writes no kinds and no ranges: kinds come from the definition's line and item ranges from the brace matcher or the scanner, and code an#ifleft out of the build is filled in by the scanner. Measured on serilog (217 files, 25k lines) against scip-dotnet 0.2.16: the scanner finds 99.8% of its definitions (every type and callable) and agrees with the brace matcher on 98.3% of item end lines (the rest are the matcher's mistakes at base lists andwhereclauses); every type and access-modified member a grep finds in the files scip-dotnet loads is in the index, 1,711 from scip-dotnet and 20 from the scanner in inactive#ifbranches. -
Python is indexed, and prebuilt indexes are read. Each Python project of a code root (a
pyproject.toml,setup.pyorsetup.cfg, else arequirements*.txt) is indexed by scip-python when it is installed (found beside its shim onPATHor undernpm root -g; atlas never installs it) on Linux and macOS, and by the owned scanner otherwise, which now reads indentation blocks: classes, methods, constructors, attributes set throughself, nested functions, module attributes, with item ranges. scip-python does not run on Windows, so there a unit's note says to write itsindex.scipwith scip-python in WSL or Docker. Any unit of any language may be indexed from such a prebuilt file (anindex.scipin its folder, or the filecode.roots[].scipnames), written by CI or by you: it is read when the unit has no indexer, when it is newer than the indexer's last run and than the unit's sources, or when the run fails; a source file newer than the prebuilt file is scanned instead, so a stale index gives scanner rows at the right lines, never wrong ones. Measured on flask (83 files, 18k lines) against scip-python 0.6.8: the scanner finds 99.7% of its definitions (every class and function) and agrees on 100% of item end lines; everydefandclassa grep finds is in the index, 1,584 from scip-python and 38 from the scanner (overloads and property setters that scip-python leaves without a definition). Withsrc/flask/app.pyedited after the prebuilt index was written, its 41 definitions came from the scanner at their new lines and none was missing. -
Java and Kotlin are indexed. Each Maven or Gradle build of a code root (a Gradle settings file claims its
builds, a parent
pom.xmlits modules) is indexed by scip-java when it is installed (found onPATHor in Coursier's folder; atlas never installs it) on Linux and macOS, and by the owned scanner otherwise: types, members, enum constants, records, and the local and anonymous classes in method bodies, with item ranges. scip-java does not run on Windows, so there a unit's note says to write itsindex.scipwith scip-java in WSL or Docker, and atlas reads it as a prebuilt index. Kotlin is indexed by the scanner (classes, objects, functions, properties, enum entries, type aliases, with item ranges): scip-java's Kotlin plugin does not load in Kotlin 2, so a unit of Kotlin alone is never run through scip-java. Measured on gson (264 files, 57k lines) against scip-java: the scanner finds 99.0% of its definitions and agrees on 99.9% of item end lines; every type and access-modified member a grep finds in the files scip-java's build compiled is in the index, 3,749 from scip-java and 268 from the scanner (members of anonymous classes, which scip-java keeps local). On kotlinpoet (131 files, 40k lines) the scanner finds 99.5% of the declarations a grep finds. -
gRPC across languages:
symbolof an rpc names its stubs, its callers and its implementations. A.protorpc is linked to the stubs generated for it in Go, TypeScript, JavaScript, C#, Python, Java and Kotlin (*.pb.go,*_pb2_grpc.py,*Grpc.cs,*Grpc.javaand the like: generated-file patterns and stub naming are data in each language's row), to the calls made through those stubs (exact, from the SCIP index, with their callers,getCartandGetCartAsyncstored underGetCarttoo) and to the server types that implement it (a method of a type that extends, implements or embeds the generated server type, through hand-written base classes). Word matches stay only where no index resolved the call (a.protoloaded at run time), and never in comments, strings, definitions' names or generated code. The.protodefinition answers first and generated code last. Measured on microservices-demo (Go, C#, Python, Java and Node services around oneprotosfolder): all 15 rpcs, 216 stub links, 32 exact call sites for 14 of them, 13 implementations of 12 (the other three are Node services that load the.protoat run time), and thecall (mention)rows down from 1,017 to 7. -
symbolacross repositories: a library's definition with its users' callers. When one code root uses another's code as a package (a Go module, an npm package, a Maven artifact, a Rust crate), its references into it are stored with their callers, sosymbol Meananswers the library root's definition and the service root's call sites, and a call into generated gRPC stubs that live in a shared root is an rpc call site. Packages compare by name, never by version (a sibling folder, a commit and a release tag are one package). Each root is still indexed on its own; one whose packages change marks its users for re-indexing. Measured on a Go library and service (17 of 17 references), microservices-demo's Go services with their generated code in a shared module (372 of 372, the same 19 rpc call sites as with the code in each service) and a TypeScript package used through afile:dependency (22 of 22), with no false links. C# is not linked (scip-dotnet writes no package name for a project's own code). -
pytest digests. pytest's own totals, each failing test's report by the name its header gives, with its
first
Eline, a+ whereline and the location; passes and skips are items with-v. -
Maven and Gradle test digests.
mvn(Surefire) andgradletest output gets the totals (Maven's from every module'sTests run:line; Gradle's from the line a failing test task prints) and each failing test with its exception and the first frame in the project; a passing Gradle run prints no count, and its digest says so. -
dotnet testdigests. Each failing test with its message, the first stack frame with a source file and xUnit'sExpectedandActuallines; the totals of every test assembly of a solution's run are summed. -
jest, vitest and
go test -jsondigests. jest and vitest output gets the runner's own totals and each failing test by its full name, with the first stack frame in the project and its message (jest'sExpectedandReceivedtoo), read through the colour codes these runners write on Windows.go test -jsongets thego testdigest, each package's output read whole though packages interleave. -
The first session offers the project a vault. Opening Claude Code in a folder atlas does not index
asks once, in one line: create a vault for this project at
<path>? yes / other folder / no, yes by default. Yes adds the project as a source (and a code root) as before and creates an Obsidian-compatible vault for its notes invaults/beside atlas's configuration, registered undervaults; other folder registers a folder you name (an existing vault is used as it is).atlas settings add-project --vaultand--vault-at FOLDERdo the same by hand, andatlas --setupasks it in the terminal. Oneatlas settings undoreverts the whole answer and removes the vault folder only when atlas made it and it holds nothing but atlas's note. -
A new multi-repo project gets its vault too. In a configuration with
projects, the new project here answer (andatlas settings add-project --new) also creates the project's vault atvaults/<name>-notesbeside atlas's configuration, never inside a repository, and registers it in that project's entry, so only that project sees it.--vault-at FOLDERputs it elsewhere and--no-vaultleaves it out; the same one undo removes the project file, the registration and a vault folder atlas made. -
code.indexersin the configuration:falseruns no language indexer (every unit is scanned), or an object names each one's binary ({"scip-go": "/opt/bin/scip-go", "scip-typescript": false}), ascode.rust_analyzerdoes for rust-analyzer. -
code.roots[].scip: prebuilt SCIP indexes for a root's units:true(the default) reads anindex.scipin a unit's folder,falsenone, a path the root folder's file, or an object from unit folder to a path orfalse. -
atlas settings add-projectwrites the source and the code root in one configuration change, so oneatlas settings undoreverts a project (it took two when the project held code). - On Windows, a file changed just after the watcher started is no longer missed: the watcher arms its first directory read before it reports itself started (under load the gap reached seconds).
- In Claude Code's auto mode, routing no longer adds its exit tail (
|| echo atlas-exit-nonzero) to a read or search command. The auto-mode classifier judged the command as written and refused the changed one, so every routed read was sent twice. Successful reads are still digested; a failing read arrives as Claude Code's own error text. Other permission modes are unchanged. The PreToolUse hook now passespermission_mode; a plugin installed before this release picks it up on update. -
atlas settings add-project --dry-runshows the change, the file it would go to and the project it would go into, and writes nothing. - atlas's own fixed patterns (links, tags, dates, discussion posts, index markers, output digests, the
--recall-checkground truth) are hand-written scanners instead of regular expressions, with the same results: 1.7x to 25x faster per line, and the recall-check ground-truth scan about 14x faster on one thread and about 140x faster across 16. The regex engine remains for what you write:search mode=regex,grep, and identifier and hook patterns.
- A repository folder whose name is over 32 characters no longer breaks every atlas run. Its default name
(and the source made from it) is cut to 32 characters, with
-2,-3added when two cut names meet, and a longer name listed by hand is cut the same way for its source. A vault, source oridsname over 32 characters written by hand is refused when the configuration is read, and the message names the file and the key (.../atlas.project.json: project.sources[0].name must be 1 to 32 characters ...). -
atlas settings add-projectin a configuration withprojectswrites into the project's own entry (projects[].sources,projects[].code.roots,projects[].vaults): the project named with--project, else the folder's own, elsedefault_project; for a folder in no project a terminal lists the projects (and cancel) to pick from, and without a terminal or with--dry-runit is refused. It wrote the top-level lists, which every project reads, so one project's folder was indexed in all of them. A generated name is free against every project's names. Every check runs on the text that would be written before anything is written: a refused add-project leaves the configuration byte for byte as it was (it used to write and then fail withat least one --vault NAME=PATH is required, naming a flag that was never passed). - A folder a project covers (a project root, its project file's folder, a listed repository) counts as
indexed: the first-session question,
atlas --setup("This folder is not indexed") and add-project's "already indexed" check no longer treat it as new. - Without a terminal,
atlas --setupandatlas settings offersay plainly that nothing went wrong: no setting was changed because there was no terminal to answer in, and which command to run. - The end-of-agent check ("agent X finished with no journal entry for lane Y") no longer fires when a subagent
only paused while its own background work runs; it checks real finishes only. Its lane is the one the agent
itself wrote under (its own
journalandhandoffcalls), else the one its brief assigns ("Journal lane: X", "You are LANE X"), never a neighbouring lane the brief also mentions; when no single lane resolves it says nothing (#79). -
handoffwithout atitletakes the text's first line as the title, as journal entries do, so the handoff is filed and shows injournal_statusandrecall lane; a text with no first line is refused with "title is required" (#80). - Two sessions writing memory at once no longer get errors for writes that were committed. The automatic snapshot compared its copy with a live record count taken outside the copy, so the other session's commit failed the check, the write came back as an error, and a copy was left behind on every later write. The count is now compared only when no other session committed during the copy; a copy that raced a commit is removed and retried, and skipped until the next write if it keeps racing. A snapshot or export that still cannot be made is reported in the answer, never as an error, since the write is already committed.
- Two sessions opening a new memory store at once no longer fail with "database is locked" (the switch to WAL is retried, and the schema is made once, under the write lock).
- Exports are rendered and written under the store's write lock, so after two sessions write at once the
export files show the newest commit (
--memory-checkcould findMEMORY.mdone record behind). -
atlas settings add-project --newworks on a fresh install. It said "no projects yet: run migrate-projects NAME first"; it now moves the current setup into a project itself (the change shown, backed up, and reversed with the new project by oneatlas settings undo). It asks for that project's name in a terminal; without one, and on--dry-run, it takes the name of the folder holdingatlas.json, made a valid project name, with-2on a clash with the new project. The first session in a folder of repositories offers that new project, where it used to ask the single-repository vault question. - A memory session killed mid-write no longer leaves
--memory-checkfailing for good. The.jsonlcopy was appended after the commit, so a kill in between left it a batch short; it is now appended under the write lock before the commit, the store records where the committed lines end, and the next write cuts off anything a crash left past that point. (A copy already left short by an earlier version still reports the gap.) Each line past that point is judged against the store: a fresh store records the point when it is opened, so its first write killed before the commit is cut too, and a line an older atlas committed is never cut. An uncommitted line with committed lines after it is overwritten in place by avoidline of the same length on the next write, and--memory-checkreports it as a warning until then. - A rule remembered without a leading
-no longer breaks the rules export (rules: 3 records render to 2 pieces): it is written as one list item,- DATE AUTHOR: text, with later lines indented; a body with a blank line or a second item is refused.--memory-checkon a fresh store no longer reports exports that were never written (and would hold no records) as missing. -
atlas --hook(the command hook) no longer loses its token-ledger rows: the thread that writes them is waited for before the process exits, so--token-reportcounts command-hook answers, and a first SessionStart no longer leaves an emptyatlas.sqlitebeside a hot journal. -
atlas --setupandatlas settings offerwithout a terminal no longer record every setting as offered, so a later run in a terminal still asks about each one. -
atlas ruling --by NAME --defines ID "text", the documented form, works: it said "the text is empty" because the--defineslist took the text too. A list now ends at a word with a space, and a list that runs to the end leaves its last word as the text;-- TEXTworks as before. -
atlas settings undoshows what it would revert (when, which command, and per file what goes back, with line counts) and asks first; without a terminal it needs--yes. After a command that changed nothing it used to restore an older, unrelated backup without a word. -
rememberaccepts the 16-digit sha its ok line prints asexpected_sha(any prefix of 12 or more hex digits, any case); it took only the full 64. A stale one says to recall the record, not to "read the note again". -
journal,handoffandrememberrefuse an empty or blanklane, journaltextorbody(they were stored, asjournal::0001for an empty lane). -
format: "json"works on the memory tools, as the Tools reference says it does on every tool:recall {key}andrecall {op: "status"}answer as fields, every other memory answer as{"text": ...}. They answered text whatever was asked. - The README gave the recall hook's budget as 600 tokens; it is 150 (
recall.budget_tokens). -
symbolsaysROOT: indexinguntil a root's first walk since atlas started has finished, instead ofstale ROOT: changed, reindex pending. Its coverage notes (definitions only (scan only: ...), about nine lines in a three-repository project) come with a session's firstsymbolanswer only; state lines still come every time. Its description lists the languages it indexes, not "a Rust or WGSL name". - The
hooktool is no longer annotated read-only (it writes journal entries). -
atlas --helplists every mode, subcommand and flag;--code-indexprints its row and write counts as words and exit codes as numbers, not Rust debug structures. -
atlas slice --lines 5-1is refused (the range runs backwards) instead of exiting 0 with nothing selected. -
grepcuts a matched line over 400 bytes to a window around the match and names the line's length. -
recallno longer prints a title made from the body (a decision's) above the body that starts with it, lists no 0.0-score pointers, and with no match says when the store holds no records yet (and does not point a setup without exports at its exports). -
searchinsubstring,regexorftsmode reads vault notes only; an empty answer now says so and points at modesectionsandgrepfor the sources. - The server instructions begin "Markdown vaults served" (Obsidian is not needed).
- On a build from source, the settings offer no longer lists updates as on (a source build never updates itself); the update pin example names 0.2.0.
- Paths read from the environment use one separator on Windows (
Z:\home\atlas.json, notZ:/home\atlas.json), andmigrate-projectswrites the defaultdbwith/. - The README's "any language" means any programming language; ranked search (
fts,sections,recall) splits words on spaces and punctuation, so text written without spaces (Chinese, Japanese, Thai) is found withsearchin substring mode orgrep. The Memory store page says thatatlas --hook, one process per event, injects no subagent lane recall atSubagentStart(the brief is held by the MCP server). - A note being replaced by another program (an editor saving by rename, another atlas session's write) no longer reads as missing for a moment. On Windows the note's name can vanish mid-replace for as long as the writer is held up inside the rename (up to about 32 ms measured on a heavily loaded machine), and a read that landed there said "note not found"; atlas now looks again for up to 100 ms before it says so.
- The deny-list (
.env*, keys, keystores, credential files) now holds everywhere, as the README promised: a vault note such ascredentials.mdis no longer indexed, searched, read or written,atlas digestandatlas croprefuse such files, and a denied file Claude Code reads is never kept as aslicehandle.
- Compaction support and the transcript source are experimental and not yet tested in live sessions; both are off unless turned on.
- scip-python and scip-java do not run on Windows: there their projects are scanned, or read from an
index.scipwritten in WSL or Docker. - C# code is not linked across code roots (scip-dotnet writes no package name for a project's own code).
A fix release.
-
Each file is indexed once in a multi-repository project. A repository whose folder is already
configured as a source or a code root no longer gets a second one, and its Markdown source leaves out the
files another source already indexes (a
docssource inside it, the project'sINTENT.md). Search answers no longer list the same section twice, and recall still puts records about the active repository first. -
atlas --config PATH settings ...works.--configand--projectbefore a subcommand (settings,run,slice,grammar,ruling,entry) now apply to it; before,atlas --config PATH settings migrate-projects NAMEfailed with "expected on or off". -
Plain paths in output.
atlas --memory-treeand thelist_sourcestool print Windows paths asC:\..., without the\\?\prefix.
-
cargo xtask release --pushchecks that openssl is on PATH and thatATLAS_SIGN_KEYnames a readable file before it runs the tests and builds, so a publish that cannot sign fails in seconds, not at the end.
The first public release.
- Large tool output stays out of the context. A Bash, PowerShell, Read, Grep or Glob result over the threshold is kept on disk under a short handle, and the model gets a digest: test totals and failures, compiler errors by lint, grep hits by file, a file's outline. In the first measured sessions, 236 KB of such output entered the context as 8.2 KB of digests, and an 87 KB source file became a 3.7 KB outline plus the four windows the model asked for. It is on by default and fails open.
-
Exact code ranges.
symbolanswers with each definition's line range (src/store.rs:2089-2113), and the hooks add the enclosing item and its range to ordinary Grep, Read and shell-read output, so the model reads an item whole instead of guessing windows. -
Answers half the size of grep. On real transcripts, an atlas lookup answer has a median of 288 tokens
against 624 for the grep-and-read episode it replaces: 2.2 times smaller per answer, measured with
cargo xtask calibrate-baselineandtoken-use, not estimated. - Memory recalled by relevance, not loaded whole. An append-only memory store with lane journals, handoffs and relevance-gated recall. On a 100-question evaluation answered from tool output alone, it answered all 100 for an agent that follows a result to its source and 99 for a strict agent that reads only the first result, finding all 176 facts at a median of 504 tokens per question, with no recall misses and no drift between the store and its files.
-
Projects. One install serves several projects, each with its own index and memory store, including
multi-repository projects described by a committed
atlas.project.json. - Local only. One MCP server over stdio. No network at query time; the only downloads are the embedding model at setup and signed updates.
-
The plugin. Install with
/plugin marketplace add bloodfeast/atlasand/plugin install atlas@atlas. Prebuilt binaries for Windows x86_64, Linux x86_64 and aarch64, and macOS (Apple Silicon and Intel). -
Setup.
atlas --setupwrites a starter configuration and downloads the embedding model, resuming an interrupted download and checking its SHA-256 before use. Until the model is in place, search'shybridmode and recall are lexical. The first session in a folder asks once whether to add it as a source (its Markdown, plus a code root when it holds Rust or WGSL);atlas settings add-project [DIR]adds one any time. -
Updates. At session start atlas installs a newer signed release: checked at most hourly, capped at
10 s, and failing open.
atlas settings off updateorupdate.pinturns it off. A newer version is never replaced by an older one. -
Settings.
atlas settingsoffers the Claude Code settings that cut cost (the 1-hour subagent prompt cache, an early compaction point), each with what it does and costs. Nothing is written without a yes; every write is backed up andatlas settings undoreverts the newest. -
Handles and digests.
atlas slice h:ID --item NAME | --failures | --lines A-B | --grep REpulls exactly what the model needs from a stored output.atlas run -- CMDdoes the same for a command and exits with its exit code.atlas settings off routingturns routing off;ATLAS_RAW=1passes one command through. -
Code index. Rust from rust-analyzer's SCIP output (build scripts and proc macros off: nothing is
compiled), WGSL and Protocol Buffers from owned scanners. Definitions, references with their callers,
and impl edges, each with its line range. A file changed by Edit, Write or MultiEdit is re-indexed at once.
Across a project's repositories,
symbolof an rpc names who defines it and who calls it. -
Identifiers and sections. An identifier registry and section-level full-text search over vaults and
read-only Markdown sources. Every answer states its freshness; a misses log records what search did not
find, and
atlas --recall-checkcompares the index with a plain scan. -
Core verbs always loaded.
lookup,search,recall,section,grepandsymbolare in context from the first turn; the other tools stay deferred until searched for. Answers are compact text with small default limits (lookup3 mentions,search5 sections). - Semantic and hybrid search with an owned int8 sentence-embedding encoder (AVX2, AVX-512 VNNI and NEON kernels, tested bit-identical against a scalar reference).
-
Memory store. Append-only and hash-chained, enforced by SQLite triggers. A reversal is a supersede;
snapshots roll up into an archive, and
--memory-as-of KEY TIMEanswers what a record said at any time. Lane journals, handoffs, andatlas rulingandatlas entryfor rulings and log entries with explicit fields.recall {query}returns the best record whole and the rest as one-line pointers. -
Memory stays in sync with its files. While the rules file and the memory folder stay hand-written,
every rescan re-imports what changed: a changed item is superseded, a removed one retired, and history is
never overwritten.
--recall-checkreports drift between the store and its source files. -
The memory index as a tree. Claude Code cuts
MEMORY.mdat 200 lines;memory.treeturns it into a short root over topic hubs, with every memory at most three reads from the root and pinned memories in the root. Rebuilds are stable. On a hand-labelled set of 227 memories, automatic placement agreed with the labels on all but 20, which were judgement calls. -
Hooks. Relevance-gated recall on each prompt and subagent start, pre-compaction handoffs, and a
context-cap guard for subagents.
atlas --hook-reportprints each hook's hit rate and tunes the relevance floor from that data. -
Projects. A project is a named set of roots with its own database and memory store; recall, the hooks,
lanes and the decision queue see only the active one. A shared user layer is imported into every project.
atlas.project.jsonlists a project's repositories by path or by remote, with optionalroleandtalks_to: a prompt that names a repository gets one line from that graph, and recall puts records about the active repository and its neighbours first. The first session in a folder of repositories offers to make it a project;atlas settings migrate-projects NAMEmoves an existing setup into one. - Discussions. Reviewer threads in Markdown with immutable, hash-chained posts, computed status, and an unresolved queue for human decisions.
- Vault writes. Additive or exact, atomic, serialised across processes, and audited with a required reason. No delete or rename tool exists.
-
The token ledger. Every answer is logged against its grep-and-read equivalent;
atlas --token-reportleads with the measured ratio, the upper bound beside it. -
File tools.
atlas digest FILEcuts a long check log to its totals, failures and verdicts;atlas cropcuts frames or a region out of a picture strip into a small PNG. Neither needs a configuration. - Platforms. Windows, Linux and macOS, with native change notification on each. Two dependencies: SQLite (compiled in) and an ed25519 signature check.
- Every vault path is confined lexically and again after canonicalisation; dot folders, device names
(including
COM¹,CONIN$and the like), alternate data streams and links that leave a vault are refused. - A fixed deny-list keeps
.env*, keys and credential files unread whatever the configuration says. - Updates are verified against an ed25519 key built into atlas, and each binary against the signed
SHA-256. Download URLs must be
https, orhttpto a real loopback address. - Regular expressions run on an owned bounded backtracker: no pattern takes more than program length times text length steps, and the memory for that bound is capped at 32 MiB per search. A search past it is refused with what to narrow.
- Recalled records are framed so a line inside a record's body cannot pass for the header of another record.
- Glob matching and JSON parsing are linear time on hostile input; image, model and protocol parsers refuse corrupt or oversized input instead of panicking.
- An adversarial test suite covers every surface atlas reads: protocol frames over the real binary, every tool argument with hostile values, paths, queries, parsers, hooks, the store and updates.
- Releases are checked against a private leak denylist after Unicode normalisation (case, confusable letters, invisible characters, line breaks and UTF-16), so nothing private ships.
- The before-and-after cost of whole sessions is measured during the release's first live week; the numbers above are per answer and per tool result.
- A PowerShell command that exits nonzero is routed only for
cargobuilds and tests on Windows. Claude Code offers no read-only PowerShell tail that keeps the exit code, so other failing PowerShell commands reach the model raw. - The code index covers Rust, WGSL and Protocol Buffers. Other languages are seen only as rpc call sites.
-
make_linkwritesobsidian://openlinks between vaults, which open only in Obsidian. - Only the latest release gets fixes.
- First install: nothing to migrate. Your notes stay the source of truth; atlas builds its index from the files on first start.
- To move an existing single configuration into a project, run
atlas settings migrate-projects NAME. It takes a backup first, and every session resolves as before.
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