Nano Mode: We Cut the Harness to 2K Tokens and the Tasks Still Passed

Executive Summary

Coding-agent harnesses have been growing. More tools, longer system prompts, richer per-turn injections — each addition defensible on its own, and collectively a fixed tax on every single request you make. ClawCodex's default harness sends about 17,000 tokens before your prompt does any work.

clawcodex --nano is the experiment that asks what happens if you refuse to pay it: six tools, a ~300-token system prompt, one-to-three-sentence tool docs, a byte-stable request prefix, and no per-turn injections — a ≈2,000-token fixed payload. In a matched A/B on terminal-bench 2.1, both tasks passed in both modes, with nano at $0.0042 versus $0.0186 — 4.4× cheaper, and faster.

Where the Idea Came From

Nano is shaped after the pi coding agent, which has been making an unfashionable argument: that a small, sharp harness beats a maximal one, because every token of scaffolding is a token of budget and attention spent on something that is not your problem. On Databricks' real-PR benchmark, pi matched or beat maximal harnesses while sending roughly 3× less context per turn.

That is a claim you can test rather than argue about, so we built the profile into ClawCodex behind a flag and ran the A/B.

What Nano Actually Sends

The per-turn injection row matters more than its size suggests. Injections that vary between turns don't just cost their own tokens — they relocate the tail of your prompt, which is how you quietly invalidate a provider's prefix cache and get re-billed for context you already paid for. A byte-stable history is what makes the small payload stay small across a long session.

The Measured A/B

Two terminal-bench 2.1 tasks, run through the Harbor adapter on deepseek-v4-flash, from an identical wheel with only --ak nano=1 differing between arms. Single pass, no retries beyond the benchmark's own rate-limit handling.

Aggregate: 2/2 pass in both modes, $0.0042 versus $0.0186 — 4.4× cheaper at equal quality. Nano's fix-git trajectory was ten focused Bash calls with zero tool errors, which is the qualitative result behind the quantitative one: fewer tools did not mean more flailing.

A trivial live A/B outside Harbor, on deepseek-v4-pro with a write-and-verify task, showed the same shape — both solved in four turns, at 3,439 versus 27,173 fresh input tokens.

What Nano Does Differently

Skills are listed, not tooled

The system prompt carries name/description/location triples and the Read tool is the loader — pi's progressive disclosure. You keep your skills; you stop paying for their full definitions on every request.

Edit is a ladder

Several {old_string, new_string} pairs in one call, all matched against the original file, with near-miss whitespace and Unicode rescued by a normalized fuzzy match that still preserves untouched lines byte-for-byte. CRLF and BOM round-trip. The read-first staleness gate stays.

A truncation guard

Tool calls carried by a max_tokens-cut response are failed with "re-issue with complete arguments" rather than executed with possibly-truncated arguments — the failure mode where a smaller output budget turns into a corrupted file.

Compaction keeps the working set

Every auto or manual compaction summary ends with cumulative read-files and modified-files path ledgers, and the summarizer is told to update the previous checkpoint rather than discard it. A long session compacts without forgetting which files it is working on.

Context-file precedence

CLAWCODEX.md as usual; when none exists, nano falls back to AGENTS.override.md, then AGENTS.md, then CLAUDE.md at the workspace root.

What It Costs You

Nano is a real trade, not a free win, and the things it gives up are the point rather than an oversight:

• No MCP servers, plugin or user tools, subagents, or task tools on the nano surface. When you need them, use default mode — that is what it is for.
• No advisor, structurally. Even with advisor_enabled in settings, a nano session never activates a reviewer model: the schema and instructions would break the fixed-payload and byte-stability contracts, and a two-model loop is not what a nano benchmark measures.
• Nano is process-global, following the /eco contract. On the TUI's stdio transport that is exactly one session; on a multi-session agent-server, --nano applies to every session that process hosts.
• --allowed-tools and --disallowed-tools still filter the six, so you can go smaller but not sideways.

It is default-off and consulted at a handful of chokepoints. Without the flag, nothing about your setup changes.

Running It

clawcodex --nano -p "fix the failing test in src/parser.py"   # headless
clawcodex --nano                                              # interactive TUI

In the TUI the flag is forwarded to the spawned backend, which builds the nano registry and prompt before the first turn. Permission prompts, mode cycling, and slash commands work as usual — nano changes what the model sees, not the UI. The status line shows a nano chip beside the model name. To reproduce the benchmark, the Harbor adapter forwards it with a single agent kwarg:

PYTHONPATH=$PWD/eval/harbor harbor run \
  --dataset terminal-bench/terminal-bench-2-1 \
  --agent clawcodex_agent:Clawcodex \
  --model deepseek/deepseek-v4-flash \
  --jobs-dir eval/harbor/jobs-nano \
  --n-concurrent 4 \
  --ak nano=1

The baseline arm is the same command without --ak nano=1, pointed at a different jobs directory. Both are in the open-source repo.

How Much to Believe

Two tasks at k=1 on one model is a small sample, and we would rather say so than round it up. What we think the run does and does not establish:

Solid

The payload reduction itself. ≈2,000 versus ≈17,000 fixed tokens is a property of what the harness constructs, not a sampled measurement — it is the same on every request you make.

Solid

The direction of the cost effect. A 5× reduction in input tokens on a task that still passes is far outside anything run-to-run variance produces.

Soft

The 4.4× multiplier. It is the ratio of two two-task totals; a different task mix moves it. Tasks whose cost is dominated by output tokens or long tool transcripts will show less, because nano shrinks the fixed prefix rather than the work.

Untested

Whether quality holds across the full 89-task suite, on other models, and on tasks that genuinely want the tools nano removes. Two passes are not evidence of no regression — they are evidence of no regression on two tasks.

The honest summary is that nano is a promising default for the large class of work that is really "read some files, run some commands, edit some code" — and the wrong choice the moment you want subagents, MCP, or a reviewer model. The flag exists so you can pick per run rather than per install.

Conclusion

The industry's instinct has been to make agent harnesses bigger. Nano is a measured argument for the opposite: on the tasks we ran, cutting the fixed payload by 8× cost nothing in quality and saved 4.4× in money. That is two tasks — but the mechanism is not mysterious, and every part of it is in the open-source repo for you to run against your own work.

References

• docs/nano.md — the mode's reference documentation
• eval/harbor/RUN_NANO_TB21.md — full A/B instructions and result tables
• pi — the minimal-harness coding agent nano is shaped after