Skip to main content
A one-page reference for the --low-token cost-saving preset. For motivation, trade-offs, and FAQ, see the low-token mode concept page.

​
Activation

MethodWherePersistence
--low-token flagzo build, zo continuePer-invocation
low_token: truePlan YAML frontmatterPer project
When either is on, the preset below applies. CLI flag wins over plan field if both are set.

​
The preset

_LOW_TOKEN_PRESET = {
    "lead_model": "sonnet",
    "max_iterations": 2,
    "stop_on_tier": "could_pass",
    "drop_research_scout": True,
    "headlines_disabled": True,
    "gate_mode": "full-auto",
    "compact_threshold": "60",
}
Authoritative location: src/zo/cli.py — search for _LOW_TOKEN_PRESET.

​
Knob reference

KnobDefaultLow-tokenWhere in code
Lead modelopussonnet_resolve_lead_model in cli.py
Phase-4 max_iterations102_LOW_TOKEN_LOOP_CLAMPS in experiment_loop.py
Phase-4 stop_on_tiermust_passcould_pass_LOW_TOKEN_LOOP_CLAMPS in experiment_loop.py
Cross-cutting research-scoutenableddisabled_agents_for_phase in orchestrator.py
Cross-cutting code-reviewerenabledenabled (kept)(not filtered — quality safety)
Haiku headline tickerevery 60sdisabled_maybe_print_headline in cli.py
End-of-session Haiku summarygeneratedskipped_generate_session_summary in cli.py
Default gate modesupervisedfull-auto_resolve_gate_mode in cli.py
Lead prompt: dedicated adaptations sectionincludedomittedbuild_lead_prompt in orchestrator.py
Lead prompt: rosterfull descriptivecompact comma-list_prompt_roster in orchestrator.py
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE envunset60extra_env in cli.py → wrapper

​
Override flags

These compose with --low-token to fine-tune individual knobs:
FlagTypeEffect
--lead-model {opus,sonnet,haiku}choiceOverride the lead model
--max-iterations NintHard cap on Phase-4 iterations
--no-headlinesboolDisable the headline ticker (independent of low-token)
--gate-mode {supervised,auto,full-auto}choiceOverride the gate mode

​
Plan-level fields

Two YAML frontmatter fields complement the CLI flags: 
---
project_name: "..."
# ... required fields ...
low_token: true        # optional, default false
lead_model: sonnet     # optional, default unset
---
Plan-level ## Experiment Loop section overrides individual loop fields with full granularity: 
## Experiment Loop

max_iterations: 5
plateau_epsilon: 0.005
stop_on_tier: should_pass
When low_token is on AND a plan ## Experiment Loop field is set, the plan field wins (the preset is a “sensible defaults” layer, not a hard clamp).

​
Precedence (highest first)

  1. CLI flag — --lead-model, --max-iterations, --gate-mode, --no-headlines
  2. Plan YAML frontmatter — lead_model, low_token
  3. Plan body section — ## Experiment Loop for loop knobs
  4. Low-token preset — applied when --low-token or low_token: true is set
  5. Base default — Opus, 10 iterations, supervised, etc.
Concrete examples:
InvocationPlan hasEffective leadEffective max-iterations
zo build x.md(nothing relevant)opus10
zo build x.md --low-token(nothing relevant)sonnet2
zo build x.md --low-tokenlead_model: opusopus (plan wins over preset)2
zo build x.md --low-token --lead-model haikulead_model: opushaiku (CLI wins over plan)2
zo build x.md --low-token## Experiment Loop
max_iterations: 8		sonnet8 (plan wins over preset clamp)
zo build x.md --low-token --max-iterations 4## Experiment Loop
max_iterations: 8		sonnet4 (CLI wins over plan)

​
Visual confirmation

When low-token is active, the ZO banner shows a [low-token] badge: 
╭──────────────────────────────────────────────────────────────╮
│   ◎ Zero Operators  v1.0.2  [low-token]                     │
│      Autonomous AI Research & Engineering Teams              │
│                                                              │
│   Project:   mnist-demo                                      │
│   Mode:      build                                           │
│   Phase:     starting                                        │
│   Gates:     full-auto                                       │
╰──────────────────────────────────────────────────────────────╯

​
See also