Low-token mode

ZO is built around a Lead Orchestrator (Opus by default) plus an autonomous experiment loop that can iterate up to ten times in Phase 4. That’s the right shape for an API user with budget headroom, and the wrong shape for a Pro-plan subscriber whose daily message cap is finite. Low-token mode swaps several knobs in unison so ZO fits inside a Pro budget without forcing you to learn five flags.

Activate it

CLI flag
Plan field

zo build plans/my-project.md --low-token

Per-invocation. Today’s run only.

---
project_name: "my-project"
version: "1.0"
created: "2026-04-26"
last_modified: "2026-04-26"
status: active
owner: "Sam"
low_token: true
---

Persists per project. Every run uses the preset until you remove the field.

The banner shows a [low-token] badge whenever the preset is active so you have constant visual confirmation.

What the preset flips

Knob	Default	Low-token	Why
Lead model	`opus`	`sonnet`	~5× cheaper input/output. Biggest single line item.
Sub-agent routing	per `.md` (mostly Sonnet)	two-tier: Haiku for `code-reviewer` / `test-engineer` / `oracle-qa`; Sonnet for reasoning (data-engineer, model-builder, xai, domain-eval, ml-engineer, customs)	Pattern-matching tasks don’t need Sonnet’s lift. Haiku is ~3× cheaper and SWE-bench-competitive on code.
Phase 1 agents	full reviewer set	data-engineer only	Reviews + tests deferred to Gate 5 final pass. Phase 1 was ~45% of the first bench’s cost.
Phase 5 agents	model-builder + oracle-qa + xai-agent + domain-evaluator	model-builder + oracle-qa only	Lead writes single-shot analysis summary instead of dedicated explainability/domain pass.
Phase-4 `max_iterations`	`10`	`2`	Phase 4 is the dominant cost; iteration count is the multiplier.
Phase-4 `stop_on_tier`	`must_pass`	`could_pass`	Stops at the weakest acceptable oracle tier instead of pushing for the strongest.
Cross-cutting `research-scout`	on every phase	dropped	Saves ~6 spawns and their contracts.
End-of-session Haiku summary	1 call per run	disabled	~$0.0002 per run. The previous per-60-second ticker (~60 small calls/hour) was removed unconditionally; only the one-shot wrap-up remains, and `--low-token` skips even that.
Default gate mode	`supervised`	`full-auto`	No human-loop overhead. You can still pass `--gate-mode supervised` to override.
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	unset (Claude Code default ~83%)	`60`	Auto-compacts conversation context earlier, prevents performance degradation near the window limit.

Measured savings

First measured bench (MNIST, 2026-04-27) landed at $7.75 vs. the historical default-mode reference of ~$11, a ~30% reduction. That bench used the lead-only swap. The preset has since added two structural levers, Haiku routing for review/test/oracle agents and per-phase agent trims (Phase 1 + Phase 5), that target a ~50-60% ceiling. A second bench post-update is needed to confirm the new measured number. The honest reason the original 70-80% projection was off: in default mode, sub-agents are already on Sonnet via their .md frontmatter. Only the Lead Orchestrator is Opus. So a lead-only swap only affects the lead’s ~30-40% cost share. At ~5× cheaper per token, that’s a ceiling of ~25-30% on the total, exactly what the first bench measured. The path past that ceiling is right-sizing pattern-matching agents (Haiku) and trimming non-essential reviewers per phase, both of which the preset now does. For a path past 50-60%, see Cost benchmark → What would push savings higher: prompt caching via SDK refactor, Batch API for parallel evaluation, Files API for repeated context. The 30% (or post-update 50-60%) headline depends on plan shape. Plans that hit the iteration cap on default mode (harder problems, multiple Phase 4 retries) see more, max_iterations 10 → 2 starts to bite. Plans with no Phase 4 (data-only, feature-engineering-only) see less, only the lead-model swap and headline disable matter (~15-20%).

Override individual knobs

The preset is a starting point, not a ceiling. Override flags compose with --low-token:

# Keep Opus lead but everything else low-token
zo build plans/my-project.md --low-token --lead-model opus

# Allow 5 iterations instead of 2 (still better than the default 10)
zo build plans/my-project.md --low-token --max-iterations 5

# Low-token but keep human-in-loop gates
zo build plans/my-project.md --low-token --gate-mode supervised

Precedence

Highest first:

CLI flag: --lead-model, --max-iterations, --gate-mode
Plan field: lead_model: in YAML frontmatter, ## Experiment Loop section
Low-token preset: applied when --low-token or low_token: true
Base default: Opus, 10 iterations, supervised, etc.

This means a plan can opt back into research-grade settings (high iteration count, Opus lead) even with low_token: true set globally. The preset is a “sensible defaults” layer, not a hard clamp.

Trade-offs

Low-token mode is a quality-for-cost trade. Be honest with yourself about which side you’re paying.

Lead nuance. Sonnet is excellent at execution and decomposition for well-defined plans. For research with shifting goalposts or projects whose plan needs creative interpretation, Opus catches things Sonnet misses. If you’re spinning up a new domain for the first time, run the first plan on Opus to validate, then switch to low-token for replays.
Iteration depth. With max_iterations=2, hard problems may not converge before the cap. ZO surfaces this in zo status so you can re-run without --low-token if the oracle wasn’t met.
Cross-cutting research. Without research-scout, agents don’t get a baseline literature review at every phase. For projects in a familiar domain this is fine; for genuinely novel problems, list research-scout explicitly under **Active agents:** in the plan to override.
No headlines. You lose the periodic 1-line “what’s happening” feed. Raw events are still in logs/comms/<date>.jsonl if you want to tail -f.

When NOT to use low-token mode

The first end-to-end run of a research-grade project where you don’t yet know what the right plan looks like.
A production launch where the cost of a poorly-converged model is far higher than the token cost of running on Opus.
Time-sensitive demos: no headlines means less live signal to your stakeholders.

In each case, run on default settings, validate the result, then switch on low_token: true for subsequent replays and ablations.

What’s NOT in this mode (yet)

The features below would help but require a larger architectural change (switching ZO from claude CLI launcher to direct Anthropic SDK). They’re tracked as future work, not in scope for low-token mode v1:

Prompt caching: Anthropic’s 5-minute TTL cache. Would save ~90% on cached input tokens.
Batch API: 50% discount for async jobs. Applicable to other Haiku/Sonnet calls ZO might add in future (e.g., end-of-phase reports) but incompatible with interactive tmux. The per-60-second Haiku ticker that originally motivated this note has since been removed.
Files API: upload static artifacts (plans, specs) once, reference by ID.
Extended thinking budget tuning: cap thinking tokens explicitly.

Side-by-side comparison

What changes, end-to-end, between a default run and a low-token run on the same plan:

Lifecycle stage	Default	Low-token	Saving driver
Lead orchestrator session	Opus, 200 turns	Sonnet, 200 turns	Per-turn cost ~5× cheaper
Lead-prompt build	Full roster + dedicated adaptations section + per-agent contracts	Compact roster + inline adaptations only + per-agent contracts	~2-5 KB removed per phase
Phase 1-3 gates	Pause for human (supervised)	Auto-PROCEED (full-auto)	No human-loop overhead
Phase 4 first iteration	Same	Same	,
Phase 4 iteration cap	10 attempts	2 attempts	The big multiplier
Phase 4 stop condition	`must_pass` tier	`could_pass` tier	Stops earlier on weakest acceptable result
Cross-cutting `research-scout`	Spawned per phase	Skipped	~6 spawns × ~1 KB contract
Cross-cutting `code-reviewer`	Spawned per phase	Spawned per phase	(kept, quality safety net)
End-of-session Haiku summary	Generated	Skipped	1 small call per session. (The previous per-60-second headline ticker — ~60 small calls/hour — was removed unconditionally.)
Auto-compaction trigger	~83% of context window	60% of context window	Earlier compaction → less degraded reasoning at the tail

Worked example: MNIST

The MNIST end-to-end demo (Phase 1 → 6, oracle threshold 95% must_pass / 99% could_pass) is the canonical reference run. Default-mode cost was ~$11, dominated by the Lead Orchestrator on Opus.

# Default run (historical reference)
zo build plans/mnist-digit-classifier.md
# Lead: Opus
# Phase-4 iterations: up to 10 (MNIST converges in 1)
# Headlines: ~60 per hour
# Cost: ~$11
# Wall time: ~50 min

# Low-token run (measured 2026-04-27)
zo build plans/mnist-digit-classifier.md --low-token
# Lead: Sonnet 4.6 (~5x cheaper per token)
# Sub-agents: Sonnet 4.6 (already, no change)
# Phase-4 iterations: capped at 2 (demo hits target on iteration 1, cap doesn't bite)
# Headlines: disabled
# Cost: $7.75 (~30% reduction)
# Wall time: ~75 min (one stuck-gate cycle in this run)

Cost breakdown of the measured run: Lead orchestrator $4.48 + sub-agents $3.27 = $7.75 total (captured via npx ccusage --instances). Phase 1 alone was $3.47, the largest single phase, Phase 4 only ran one iteration. Full bench writeup with the why-30%-not-70% breakdown: reference/cost-benchmark.

Worked example: tiny plan with no Phase 4

If your plan finishes inside Phase 3 (data-only or feature-engineering-only project), the iteration-cap savings disappear and only the lead-model swap and headline disable matter. Expected reduction: ~15-20% vs. the ~30% for a full lifecycle plan.

When to use low-token mode

Replays

A plan that has already converged on the default settings. Replay on low-token; the second run rarely needs ten iterations to find the same answer.

Pro plan / student account

Daily message caps make Opus runs untenable. Low-token’s Sonnet lead + 2-iteration cap fits inside most cap budgets.

Demos

A live demo of ZO doesn’t need ten Phase-4 iterations to make the point. Low-token’s faster wall time also makes for a better demo.

Ablations

When you’re varying a single parameter across many runs, low-token cuts the marginal cost so you can run more variants for the same spend.

When NOT to use low-token mode

The first end-to-end run of a research-grade project where you don’t yet know what the right plan looks like. Default mode’s higher iteration count gives you more attempts to discover what works.
A production launch where the cost of a poorly-converged model is far higher than the token cost.
Time-sensitive demos: no headlines means less live signal to your stakeholders. (Consider --low-token plus --gate-mode supervised to keep the human-in-loop signal at gates.)

In each case: run on default settings, validate the result, then switch on low_token: true for subsequent replays and ablations.

FAQ

Does low-token mode reduce model quality?

Yes, that’s the trade. The lead orchestrator (Opus → Sonnet) is the biggest quality reduction, but Sonnet 4.6 is excellent at execution and decomposition for well-defined plans. Where it falls down is open-ended creative interpretation of an under-specified plan. The Phase-4 iteration cap (10 → 2) means hard problems get fewer attempts to converge, zo status surfaces this so you can re-run without --low-token if the oracle wasn’t met.

Can I use low-token mode AND keep Opus for the lead?

Yes. The override flags compose: zo build plans/x.md --low-token --lead-model opus keeps Opus lead and applies the rest of the preset (max iterations, no headlines, full-auto, earlier compaction). Useful when the lead model matters for plan decomposition but you want the iteration savings.

What happens if Phase 4 doesn't converge in 2 iterations?

The autonomous loop stops with BUDGET_EXHAUSTED. The phase remains in a state where you can re-run without --low-token (or with a higher --max-iterations) and the loop picks up from where it left off, child experiments inherit parent_id so the lineage is preserved. You don’t lose the work, you just unlock more iterations.

Is low_token: true in the plan equivalent to --low-token on the CLI?

Almost. The plan field activates the same preset. The only difference: CLI flags ALWAYS win over plan fields. So a plan with low_token: true AND a --lead-model opus flag runs Opus lead but everything else low-token.

Why isn't research-scout in low-token mode?

The research-scout agent provides cross-cutting baseline literature review. It’s useful but not essential, its absence rarely changes the outcome of a specific phase, and dropping it saves ~6 spawns and their contracts per build. Code-reviewer is kept for quality safety; research-scout is the safer drop. If you genuinely need research-scout active in low-token mode, add it explicitly to your plan’s **Active agents:** block, but note that the orchestrator filters research-scout regardless of the active list when low_token=True (this is documented as a known limitation; an opt-out mechanism may land in v2 if requested).

Does this work with zo continue and zo draft?

zo continue accepts the same flags as zo build and forwards them. zo draft does NOT yet support --low-token, drafting uses Opus + 100 max-turns by default. Adding low-token support to draft is tracked as a follow-up; the savings are smaller anyway because draft is shorter than build.

Do sub-agents (data-engineer, model-builder, etc.) also run on Sonnet in low-token mode?

Yes, sub-agents are on Sonnet 4.6 in both default mode and low-token mode. Default mode never had sub-agents on Opus; their .md frontmatter declares model: claude-sonnet-4-6. So switching to --low-token doesn’t change the sub-agent cost rate. This is also the reason the savings ceiling is ~30% rather than the 70-80% an “everyone-was-Opus” projection would imply.The lead orchestrator’s prompt in low-token mode does include a Sub-Agent Model Override section that explicitly passes model="claude-sonnet-4-6" to every Agent() call as a defence-in-depth measure (in case some future Claude Code version changes the default). Verified working end-to-end on Claude Code 2.1.107: ps aux during the measured bench showed all four processes (lead + 3 sub-agents) on claude-sonnet-4-6.

Can I see how much I'm saving in real time?

Not yet. ZO doesn’t ship a built-in token meter (the claude CLI logs tokens to ~/.claude/projects/*.jsonl but ZO doesn’t surface them). The Optional integrations (planned) section in the README lists ccusage, a Claude Code token usage monitor, as a near-term opt-in for zo usage. For now: run npx ccusage --json after a build to see per-session totals.

Why not lower lead to Haiku?

Haiku 4.5 is excellent on coding (SWE-bench 73.3%, rivalling Sonnet 4) and very cheap. But the Lead Orchestrator’s job is multi-step orchestration, contract reasoning, gate evaluation, and team coordination, Haiku struggles with multi-step planning under uncertainty. Sonnet is the safer default for v1. You can manually opt into Haiku lead with --lead-model haiku if you want to push the savings further (probably 10-15× cheaper than Opus, but with material quality risk).

What happens at gates in low-token mode?

By default, low-token sets --gate-mode full-auto. All gates auto-PROCEED when artifact contracts and oracle thresholds pass. To keep human-in-loop gates while still saving on lead/iterations, pass --gate-mode supervised explicitly: zo build plans/x.md --low-token --gate-mode supervised. The CLI flag wins over the preset’s full-auto default.

What's NOT in this mode?

Several Anthropic API features could provide additional savings but require switching ZO from the claude CLI launcher to direct Anthropic SDK calls, out of scope for low-token v1:

Prompt caching: 5-minute TTL cache. Would save ~90% on cached input tokens.
Batch API: 50% discount for async jobs. Applicable to other Haiku/Sonnet calls ZO might add in future (e.g., end-of-phase reports) but incompatible with interactive tmux. The per-60-second Haiku ticker that originally motivated this note has since been removed.
Files API: upload static artifacts (plans, specs) once, reference by ID.
Extended thinking budget tuning: cap thinking tokens explicitly.

Tracked as future work; would be a separate, larger architectural change.

Get started

Concepts

CLI reference

Reference

Project

Activate it

What the preset flips

Measured savings

Override individual knobs

Precedence

Trade-offs

When NOT to use low-token mode

What’s NOT in this mode (yet)

Side-by-side comparison

Worked example: MNIST

Worked example: tiny plan with no Phase 4

When to use low-token mode

Replays

Pro plan / student account

Demos

Ablations

When NOT to use low-token mode

FAQ

See also

​Activate it

​What the preset flips

​Measured savings

​Override individual knobs

​Precedence

​Trade-offs

​When NOT to use low-token mode

​What’s NOT in this mode (yet)

​Side-by-side comparison

​Worked example: MNIST

​Worked example: tiny plan with no Phase 4

​When to use low-token mode

Replays

Pro plan / student account

Demos

Ablations

​When NOT to use low-token mode

​FAQ

​See also

Activate it

What the preset flips

Measured savings

Override individual knobs

Precedence

Trade-offs

When NOT to use low-token mode

What’s NOT in this mode (yet)

Side-by-side comparison

Worked example: MNIST

Worked example: tiny plan with no Phase 4

When to use low-token mode

When NOT to use low-token mode

FAQ

See also