zo build

zo build is the flagship command. It reads the plan, decomposes it into phases, generates contracts for every active agent, and launches the Lead Orchestrator in a tmux session that drives the team to completion.

Synopsis

zo build PLAN_PATH [OPTIONS]

Smart mode detection

zo build auto-detects what to do based on the project’s current state:

State	Behaviour
Fresh (no `STATE.md` or phase = `init`)	Build from scratch. Phase 1 is the entry point.
In-progress	Continue from the recorded phase. Loads the previous phase’s snapshot for context.
Plan edited since last run	Detects the diff via timestamp + content hash. Re-decomposes. Surfaces the change to the human if the diff crosses a phase boundary.

You don’t pass a flag for this, zo build figures it out.

What it does

Validate plan

Parses the plan and runs full validation. Aborts on any error before launching the agent session.

Resolve project context

Finds memory, target, and delivery repo via _load_project_context(). Supports both .zo/-portable layout and legacy top-level memory/.

Build orchestrator

Decomposes the plan into phases (mode-specific). Generates contracts: per-agent inputs, outputs, success criteria, time budget, precedent. Builds the Lead Orchestrator’s spawn prompt with full context (plan + phases + agent roster + memory + coordination instructions + per-project agent adaptations).

Launch session

Creates a tmux pane (default) or runs headless (--no-tmux). Pastes the Lead Orchestrator’s prompt. The Lead reads the full plan, creates the team via TeamCreate, and drives execution.

Monitor

The Python LifecycleWrapper observes via ~/.claude/tasks/ and the tmux pane. Captures lifecycle events, pipes them to JSONL comms log, prints the live task list and recent agent events in your terminal. Auto-launches the training dashboard split-pane during Phase 4.

Gate handling

At every phase boundary, checks artifact contracts and oracle thresholds. Automated gates auto-PROCEED. Blocking gates pause; you approve via /gates:approve or reject via /gates:reject.

Finalise

On Phase 6 PROCEED, writes the final phase snapshot, generates a session summary, kills the tmux window, prints a Haiku 2-3 bullet summary, returns control to the invoking terminal.

Gate modes

--gate-mode controls human involvement:

supervised (default)
auto
full-auto

Every gate pauses for human review. Maximum oversight. Best for the first run of a new project.

zo build plans/my-project.md

Automated gates auto-PROCEED. Blocking gates (Gate 2 representation review, Gate 5 model review) still pause. Standard production setting.

zo build plans/my-project.md --gate-mode auto

All gates auto-PROCEED when checks pass. No human in the loop. For replays, overnight runs, batch CI.

zo build plans/my-project.md --gate-mode full-auto

Toggle mid-session with zo gates set <mode> -p <project>.

Permission prompts: —bypass-permissions

--gate-mode controls human involvement at ZO’s phase gates. Independently, Claude Code’s tool-call permission prompts can also be auto-approved with --bypass-permissions. The two are independent, but --gate-mode full-auto implicitly turns bypass on (no-human-on-gates plus must-click-every-tool is a contradiction).

Flags	Gates	Permission prompts
`--gate-mode supervised` (default)	human approves	human approves each
`--gate-mode supervised --bypass-permissions`	human approves gates	auto-approved (walk away)
`--gate-mode auto`	auto on success, pause on must-pass fail	human approves each
`--gate-mode auto --bypass-permissions`	auto on success, pause on fail	auto-approved
`--gate-mode full-auto`	all auto	auto-approved (implied)
`--gate-mode full-auto --bypass-permissions`	all auto	auto-approved (redundant)

Works in both tmux and headless modes:

Headless (--no-tmux): passes --dangerously-skip-permissions to the Claude Code CLI.
Tmux (default): temporarily overlays permissions.defaultMode: "bypassPermissions" onto your project’s .claude/settings.local.json for the duration of the run. The original file is backed up to .claude/settings.local.json.zo-backup and restored automatically when the run exits (via atexit). If ZO crashes mid-run, the next zo command auto-detects the stale backup and restores.

Behavior change note: previously, --no-tmux runs unconditionally bypassed permissions. Now they only bypass when --bypass-permissions or --gate-mode full-auto is set. If you previously relied on --no-tmux --gate-mode supervised for prompt-free runs, add --bypass-permissions to keep that behavior.

Cross-machine: —repo

When you’ve moved a project from one machine to another (Mac dev → GPU server), use --repo to point at the delivery repo containing the .zo/ layout:

zo build /path/to/<plan>.md --repo /path/to/delivery

zo build auto-detects --repo from the plan path when it’s inside .zo/plans/. So if you cd into the delivery repo and run zo continue, the inference happens for free.

Live monitoring

While zo build is running, you have several windows into what the team is doing:

tmux pane

Ctrl-b n switches to the agent session. Watch the Lead Orchestrator coordinate the team in real time. Ctrl-b p returns.

Training dashboard

Auto-launched as a split-pane during Phase 4. Rich Live panel: progress bar, metrics table, sparkline, checkpoints. See zo watch-training.

Comms log

JSONL events at logs/comms/<date>.jsonl. Five event types: message, decision, gate, error, checkpoint. Replayable.

Options

Option	Default	Purpose
`--gate-mode`	`supervised` (or `full-auto` if `--low-token`)	`supervised` / `auto` / `full-auto`
`--no-tmux`	(off)	Disable interactive tmux flow. Headless mode for one-shot agents. Note: multi-phase orchestration requires the interactive session; `--no-tmux` is for `init` and `draft`, not full builds.
`--repo PATH`	(auto)	Path to delivery repo with `.zo/`. Auto-inferred when the plan path is inside `.zo/plans/`.
`--low-token`	(off)	Activate the cost-saving preset. See low-token mode.
`--lead-model`	`opus` (or `sonnet` if `--low-token`)	Override the lead orchestrator model: `opus` / `sonnet` / `haiku`.
`--max-iterations N`	`10` (or `2` if `--low-token`)	Hard cap on Phase-4 experiment iterations. Wins over plan and preset.
`--no-headlines`	(off)	Skip the end-of-session Haiku bullet summary (~1 Haiku call per run, ~$0.0002).
`--bypass-permissions`	(off)	Auto-approve Claude Code tool-call prompts. Implied by `--gate-mode full-auto`. See Permission prompts.

Examples

First run of a fresh project

zo build plans/mnist-demo.md

Default supervised gate mode. The Lead Orchestrator runs Phase 1; you approve at every gate.

Auto-mode after first validation

zo build plans/mnist-demo.md --gate-mode auto

Automated gates auto-PROCEED; blocking gates still pause.

Resume on a new machine

cd /path/to/delivery
zo continue --repo $(pwd)

zo continue is shorthand for zo build against the project’s known plan, with .zo/ auto-detected.

Overnight unattended run

zo build plans/replay.md --gate-mode full-auto

Use only for plans that have run successfully before, full-auto skips all human review.

Pro plan / student account, minimise token spend

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

Sonnet lead, Haiku for code-reviewer / test-engineer / oracle-qa, 2 max iterations, no end-of-session Haiku summary, full-auto gates, earlier auto-compaction. ~30% measured savings on MNIST ($7.75 vs ~$11 default); 50-60% targeted, 70-80% on the roadmap. See low-token mode for the full preset and trade-offs.

Low-token mode with override

zo build plans/my-project.md --low-token --lead-model opus

Most savings preserved, but lead stays on Opus for higher-quality plan decomposition.

What you’ll see

╭──────────────────────────────────────────────────────────────╮
│   ◎ Zero Operators  v1.0.2                                  │
│      Autonomous AI Research & Engineering Teams              │
│                                                              │
│   Project:   mnist-demo                                      │
│   Mode:      build                                           │
│   Phase:     starting                                        │
│   Gates:     supervised                                      │
╰──────────────────────────────────────────────────────────────╯

Plan validated: 8 sections, oracle defined, 6 active agents.
6 phases, 14 contracts decomposed.

Launching lead session: team=zo-mnist-demo
Agent session running in tmux.
Ctrl-b n → agent window  |  Ctrl-b p → back here
Ctrl-b q N → jump to pane N  |  Ctrl-b z → zoom pane

▸ Phase 1, Data Engineer loading MNIST, validating schema
▸ Phase 1, Test Engineer writing data pipeline tests
▸ Gate 1 PROCEED, all artifacts present, all tests pass
...

When `zo build` stops

The session ends cleanly when:

Phase 6 completes: all artifacts present, all tests pass, oracle confirmed. The final delivery is in the delivery repo.
A blocking gate is hit: human input required. The session stays alive in tmux; you approve/reject via slash commands.
The autonomous experiment loop returns DEAD_END or BUDGET_EXHAUSTED: escalates to human.
You /exit: graceful shutdown. Session summary written, tmux window killed.

Phases & gates

What happens at each phase and gate.

Memory & continuity

How zo build resumes across sessions.

Get started

Concepts

CLI reference

Reference

Project

Synopsis

Smart mode detection

What it does

Gate modes

Permission prompts: —bypass-permissions

Cross-machine: —repo

Live monitoring

tmux pane

Training dashboard

Comms log

Options

Examples

What you’ll see

When `zo build` stops

Next

Phases & gates

Memory & continuity

​Synopsis

​Smart mode detection

​What it does

​Gate modes

​Permission prompts: —bypass-permissions

​Cross-machine: —repo

​Live monitoring

tmux pane

Training dashboard

Comms log

​Options

​Examples

​What you’ll see

​When zo build stops

​Next

Phases & gates

Memory & continuity

Synopsis

Smart mode detection

What it does

Gate modes

Permission prompts: —bypass-permissions

Cross-machine: —repo

Live monitoring

Options

Examples

What you’ll see

When `zo build` stops

Next