Repository navigation
Handles and digests
A large tool result costs its size on every later turn of the session, because every turn re-reads the whole context. atlas keeps such results on disk and gives the model a digest, by hook, not by the model's choice. Why this matters, and what it saves, is on Token savings and method.
A Bash, PowerShell, Read, Grep or Glob result over a threshold (12 KB, or 3 KB for cargo build and test
output) is stored whole under a handle such as h:3f9a2c1b0e. The model gets a digest instead: test totals
and each failure's location and message, compiler errors and warnings by lint, grep hits by file, or a file's
outline with line ranges. Test digests know cargo test, cargo nextest, go test (plain, -v and -json: each
failing test or subtest with its file_test.go:LINE message, a panic with its first frame outside the
runtime, and package totals), jest and vitest (the runner's own totals, each failing test by its full name
with the first stack frame in the project and its message, jest's Expected and Received lines, and file
totals; colour codes are read through), and dotnet test (each failing test with its Error Message, the
first stack frame with a source file, xUnit's Expected and Actual lines, and the totals of every test
assembly of a solution's run summed), and pytest (its own totals line, each failing test's report under
FAILURES by the name its header gives, with the first E line, a + where line, and the location after
them; passes and skips are items with -v), Maven with Surefire (mvn, mvnw or mvnd running test,
verify or install: the totals of every module's Tests run: line, with Failures and Errors both counted
as failed and passed derived from them; each failing test, <<< FAILURE! or <<< ERROR!, with its exception
and the first frame outside the assertion library; test classes as groups; Surefire lists failures only), and
Gradle (gradle or gradlew: each Class > method() FAILED with its exception and location, in the short or
the full exception format, test tasks as groups, and totals from the N tests completed, M failed line a
failing task prints; a passing run prints no count, so its digest says (Gradle lists failures only), and
passes and skips are items when the build's test logging prints them); other runners are rows of the same table in src/digest.rs
(RUNNERS). A go test -json digest reads each package's output whole, though packages interleave their
JSON lines, and its items point at the JSON lines. The
model pulls exactly what it needs with the recall tool, the handle as its key and one selector (the
digest's last line names them as recall h:ID item=NAME | lines=A-B | ...):
recall key=h:ID item=NAME # one item of the digest: a test, a file, a function
recall key=h:ID failures=true # every failure whole
recall key=h:ID lines=A-B # a line range
recall key=h:ID grep=RE # matching lines (context=N around each)
recall key=h: # the newest handles
In a terminal, atlas slice h:ID --item NAME (and --failures, --lines A-B, --grep RE, --list) gives
the same slices, and atlas run and atlas slice write their hints in that form when their output is a
terminal (the recall form when it goes to a model). atlas slice takes both forms, so a hint copied from
either works in a shell: atlas slice h:ID lines=A-B and atlas slice h:ID grep="a b" are --lines A-B and
--grep "a b". digest-grep=RE (--digest-grep RE) answers the digest's rows that match instead of the
output's lines; for a tracker search that is every issue or hit, not only the rows the digest had room for. A
recall with an h: key takes its selector in the key (h:ID grep=RE) or as the lines, grep, item
... arguments, never query or budget_tokens. A line over the 8 KB slice cap is cut to it, with a
note naming its size; grep=RE shows the part of a long line around its match.
A Read is the exception. Agents read a file to read it: after an outline, most fetched the file again within
a few calls, which cost more than the outline saved. So by default (lean.route_read: outputs) a Read is
digested only when it opens a tool's or a background task's saved output (a path under tool-results/, or a
.output file under tasks/); any other file passes whole. tuned digests files from 32 KB
(lean.route_read_min_kb), all digests every file over the threshold, and off none. A ranged Read, and a
second whole Read of a file the session already holds a read handle for, always pass whole. A routed Read is
logged in the token ledger with no saving credited, because the ledger cannot see the follow-up reads.
Routing is a PostToolUse swap: the tool runs as written, so no permission rule changes, and the result is
replaced by the digest before the model sees it. It is on by default and fails open: any error passes the
call through untouched and is logged as a miss. atlas settings off routing (or lean.routing: false)
turns it off, and ATLAS_RAW=1 passes one command through.
One limit: a PowerShell command that exits nonzero is routed only for cargo builds and tests on Windows.
Claude Code offers no read-only PowerShell tail that keeps the exit code, so any other failing PowerShell
command reaches the model raw.
In auto mode atlas leaves the command as written. Elsewhere it appends a read-only || echo atlas-exit-nonzero so a failing read is still digested, but the auto-mode safety classifier judges the
command the model wrote and refused the changed one, which cost a resend per read. So in auto mode a
successful read is digested as usual and a failing one arrives as Claude Code's own error text. Atlas never
approves a call on the classifier's behalf.
A handle id is a pure function of the bytes, the kind and the command, so the same output stored twice is the
same handle. Every slice is capped (8 KB) and says how many lines it cut. The store keeps 512 MB, least
recently used first out, and drops handles unused for 7 days. Each limit is a lean key on
Configuration reference.
On by default (lean.pr_digest: false turns it off), a gh pr diff over the threshold becomes one row per
file: status, +/- lines, the file's own handle and each hunk's line range inside it, so a review pulls a
file with recall h:F and a hunk with recall h:F lines=A-B (in a terminal, atlas slice h:F --lines A-B).
Lock files and generated files are one row each, by the repository's .gitattributes linguist-generated, by name such as *.min.js or
*.pb.go, or by a marker in the file's first 12 lines (@generated, DO NOT EDIT, Code generated by, or
a phrase such as "this file is auto-generated"): an added line there, or the file's head as it is in the
working tree, unless the PR removes a marker there and adds none. The head is read only
when the working directory is the PR's repository, and it is the checkout's head, which is not always the
PR's base or head. A vendored tree (vendor/, third_party/, node_modules/, or linguist-vendored) is
one row with a handle of its own, and a deleted file is a deleted row whose body stays behind its handle.
--patch output also lists each commit.
A file read is diff-native: the stored lines with no line numbers, without the diff --git, --- and
+++ lines the row already gives (a vendored tree's read, and an unchanged entry's that is not a plain
modification, keep them, since no row gives them back). In a change block (a run of - lines then a run of
+ lines), the k-th - line and the k-th + line are paired by position; a pair similar enough is shown
once, as ~ then the common text with [-old-] and {+new+} segments (a literal \, ~, [-, -],
{+ or +} is escaped with \). A block with a word diff shows, position by position, the ~ line, or
the - line then the + line of a position that is not paired; to decode it, take every position's old
line in order, then every new line. Lines over 2,000 bytes are never paired, and every line outside such a
block is as stored. In a file read, = N hidden lines=A-B stands for N context lines more than one line from a
change, read back as stored with recall h:F lines=A-B. A read over the 8 KB cap breaks between hunks and ends
with one next page: recall h:F page=K line; lines=A-B reads lines as stored, with a next page
of its own. On a later round, a changed file whose hunks an earlier round already showed gets a row N of M hunks new with a handle to the new hunks alone and whole file h:F for the rest. Every line of the diff is
in a read or behind a handle the digest names: decoded, the reads are the stored output byte for byte. gh pr view (the text view, --comments, and --json with body,
comments or reviews) becomes the short fields and one row per body, comment and review: author, state,
size, first line and a handle to the full text. Other --json fields, --name-only, --jq, --template, a
pipe or a redirect take the ordinary route, and so does a failing command.
Each diff is a round of its PR, keyed by repository and PR number (or branch). The hook makes no network call:
the repository comes from -R, a PR URL, or the working directory's git remotes, read locally (as gh
picks them: gh-resolved, then upstream, github, origin); when it cannot tell, the output takes the
ordinary route. A later round with a different output says per file: unchanged since round N (the same
handle, no row; one that is not a plain modification is named by a handle whose read keeps its header), unchanged but moved (only the @@ offsets and index lines differ, as after a rebase),
changed, new, or removed. A merge of the base branch that changes a file's patch shows it as changed. The same
output seen again, by another reviewer or a re-run, is the same round. A diff under the threshold passes whole
and is still recorded, so the next round can say what changed. Rounds and handles are shared by everyone who
uses the same index database, not across projects. A head sha is recorded when one is seen (the last commit of
a --patch, or headRefOid in gh pr view --json), never asked for.
The parts' handles, read in order, are the stored output byte for byte; the whole output is a handle too.
Whitespace-only hunks, -w and move detection are not handled. Routing logs these as route:gh-pr in the token ledger.
Results small enough to pass whole are annotated from the code index instead: Grep lines get their enclosing item and its range, and a Read window that cuts an item is told where it ends. See Code index.
atlas run [--digest test|build|grep|listing|source|summary|generic] [--timeout S] [--label TEXT] -- CMD [ARGS...]Runs a command without a shell, keeps its whole output under a handle and prints the digest and the handle
(or the output itself when it is under the threshold), then exits with the command's exit code. A pipeline
goes through atlas run -- sh -c '...' (or cmd /C).
Two file tools need no configuration (no config is looked for or written):
atlas digest check.log # a long check log: its totals tables, failures, panics and PASS/FAIL verdicts only
atlas digest --as test out.txt # any saved output, digested as atlas run would (test, build, grep, ...)
atlas crop strip.png out.png --frames 2-3 --of 6 --max 640 # frames 2 and 3 of a 6-frame strip, at most 640 wide
atlas crop shot.bmp out.png --rect 100,80,320,200 # a region of a PNG or BMP, written as a small PNGA check log is recognised by its per-package totals table (package passed failed ... down to total);
atlas run --digest summary gives the same digest for a command. crop splits a strip into equal frames
along its longer side (or --axis x|y), then applies --rect, then shrinks by the smallest integer factor
that fits --max W[xH]; PNG and BMP are decoded and PNG written by atlas itself (src/picture.rs).
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