Token Saver

Token Saver

Token Saver cuts the tokens an agent spends re-reading things nobody needs in full: long test runs, git log, whole files it has already seen. It changes what agents read. It never changes what people read: questions to you, specs, pull-request descriptions, finish_card summaries and design output stay complete. It is per project and on by default.

Overview

For every Claude launch the runner makes, with the project's setting on:

Lever	What it does
Command output is shortened	A covered command (a test run, git log, a build…) runs through the runner's filter, which keeps the lines that matter and hides the rest.
Only allowed MCP servers load	Every other server's tool schemas cost no tokens. See the MCP allowlist.
History compacts at about 150k tokens	On every model. On a 1M window a session used to grow to about 600k before compacting, and every turn re-reads what it holds.
Reads are guarded	A whole read of a big file, or a repeated read of an unchanged range, is refused once with a hint.
Broad searches go to a cheaper helper	A haiku scout subagent does wide codebase searches.
Prompts are cache-stable	Every runner prompt puts its static part first and per-run data last, so Anthropic prompt caching reuses the prefix across runs.

Token Saver also switches on Context Handoff: there is no separate switch for it.

How it works

flowchart LR
  A["Agent runs a Bash command"] --> B{"filter-hook:<br/>safe to rewrite?"}
  B -- "no" --> C["Command runs as written"]
  B -- "yes" --> D["nautelle-runner filter -- cmd"]
  D --> E["Full output saved to<br/>&lt;run dir&gt;/raw/&lt;n&gt;.log"]
  D --> F{"Shorter, and every<br/>error line kept?"}
  F -- "yes" --> G["Agent sees the compressed output<br/>+ a footer with the raw path"]
  F -- "no" --> H["Agent sees the original output"]

Loading

1. The runner launches Claude with a PreToolUse hook (nautelle-runner filter-hook).
2. When the agent calls Bash, the hook decides whether the call can be rewritten without changing what the session is allowed to run (see When the filter does not apply).
3. A rewritten call runs through nautelle-runner filter. The command's complete output is saved byte for byte; a filter family for that command compresses it.
4. The engine checks the result. If any error, failure, warning or stack-frame line is missing, or the result is not shorter, the agent gets the original output.
5. The agent sees a footer such as [nautelle filter: 412 lines hidden · full output: <path> · NAUTELLE_RAW=1 to bypass] and can read the raw file when it needs a hidden line.

What is never hidden

• The exit code is the command's own.
• Errors, failures, warnings and stack frames are never removed. If the filter cannot tell what a line is, or the result would not be shorter, the agent gets the output unchanged.
• A command no filter covers runs as written.
• The raw output file stays on the runner's machine. The control plane never reads it.

Note

Filtered output is also redacted for GitHub, OpenAI, Slack and AWS token shapes and private-key blocks before the agent reads it. The raw file keeps every byte.

When the filter does not apply

The filter rewrites a Bash call only when:

• the session runs in bypassPermissions, auto (Board card sessions do) or plan (planner and design runs do); and
• no deny or ask permission rule matches the command; and
• the call is made of simple commands joined by |, &&, || or ; — no redirect other than 2>&1, no subshell, heredoc or substitution — and it is not in the background.

In a pipeline only the first command is filtered: bun run test 2>&1 | tail -50 filters bun run test, and tail reads the filtered output. In a list, each covered command is filtered on its own. A dev server or a watch mode runs as written.

When nothing was filtered, the dashboard says why:

Label	Means
Compound command (not filtered)	a redirect, subshell, heredoc, substitution or background &
No filter for this command	no filter family covers the first command of any pipeline
Not filtered in this permission mode	the session is not in bypassPermissions, auto or plan

The read guard

The runner guards Claude's Read tool itself, whatever plugins the profile has:

• A whole read of a file over 64 KB or 1,500 lines is refused once with a hint: read a range with offset/limit, find the line with Grep, or ask the scout agent.
• A repeated read of an unchanged range is refused once with a reminder.
• Repeating the same call reads the file.

Bypass: NAUTELLE_RAW=1

To run one command with no filtering, put the variable in front of it:

NAUTELLE_RAW=1 bun run test

The worker prompt tells agents about it, and you can tell an agent to re-run something that way. Bypassed commands are counted: a high bypass rate on the dashboard means the filter is getting in the way.

The MCP allowlist

Project › Settings › Token saver › MCP servers agents load has one checkbox per server the runner reports for the project's profiles.

• nautelle is always loaded and is not in the list.
• An empty list means nautelle only. A card that needs Playwright or GlitchTip needs its checkbox ticked.
• A name that no profile reports any more stays visible and marked, so saving never drops it silently.
• Only a project administrator can save.

Tip

If an agent reports a missing tool after you turned Token Saver on, a server was left unticked. Tick it and save — the bypass rate does not show this.

Where the savings show

Filter figures are estimates, marked ≈: hidden bytes ÷ 4 is the tokens, priced at the session model's input price. "Before" and "after" compare runs of the same kind launched without and with Token Saver.

Where	What it shows
Board card	saved ≈ $x next to the cost; the card sheet lists the round's filters
Usage › Token saver	saved, commands, bypass rate, "returned the original" rate, cost per run before and after by run kind, top filters
Project › Token saver	savings over time, by filter and by run kind, the bypass rate, and the filters that most often returned the original

Manual sessions and /cs-eco

/cs-eco is the Code Sentinel plugin's token saver for sessions the runner did not launch: your own terminal, the orchestrator's session and fleet workers. It runs the same nautelle-runner filter-hook. The runner picks up its stats for sessions whose working directory is inside a watched project root, and the dashboard shows them as Manual session. A session outside every watched root is never reported.

Settings

Setting	Where	Who
Token saver on / off	Project › Settings › Token saver	project administrator
MCP servers agents load	same page	project administrator

Off launches every agent exactly as before the feature.

Description incomplete

A card worker may not finish without a pull-request description that has Closes #n (when the card has an issue), ## What changed and why, ## Acceptance criteria and a summary of at least two sentences. The first two rejections send the worker back to rewrite it; the third attempt in the round is accepted, and the card carries Description incomplete so you know to read it before you accept.

See also

• Context Handoff · Steward · Claude Code Integration
• User guide: docs/guides/token-saver.md
• For filter authors: docs/guides/token-saver-filter.md

Decisions: ADR-0039 · Spec: #445, #475, #610, #612, #614, #616, #626