Skip to content

Handles and digests

Brandon White edited this page Nov 20, 2026 · 5 revisions

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.

Routing

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.

PR reviews

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.

Code ranges

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

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).

File tools

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 PNG

A 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).

Clone this wiki locally