Cook — Agent Orchestration CLI

cook wraps your coding agent (Claude Code, Codex, OpenCode) in composable workflows: review loops, repeat passes, parallel races, and task-list orchestration.

Important: Never use --sandbox none. The default sandbox mode (agent) is correct when running as a skill. It preserves the parent agent's security boundaries.

Quick reference

# Single work call
cook "Implement dark mode"

# Review loop (work → review → gate, repeat until DONE)
cook "Implement dark mode" review

# Repeat 3 times
cook "Improve the design" x3

# Race 3 versions, pick the best
cook "Implement dark mode" v3 pick "cleanest implementation"

# Two approaches, pick the winner
cook "Auth with JWT" vs "Auth with sessions" pick "best security"

# Work through a task list
cook "Do the next task in PLAN.md" \
     ralph 5 "DONE if all tasks complete, else NEXT"

# Everything composes
cook "Implement dark mode" review v3 "cleanest result"

Operators

Operators compose left to right. Loop operators wrap everything to their left.

Loop operators

Operator	Effect
review	Add a review→gate loop (up to 3 iterations by default)
review N	Review loop with up to N iterations
xN / repeat N	Run work N times sequentially
ralph N "gate"	Outer gate for task-list progression (DONE/NEXT)

Custom review/gate prompts (positional shorthand):

cook "work prompt" "review prompt" "gate prompt"
cook "work prompt" "review prompt" "gate prompt" "iterate prompt" N

Composition operators

Operator	Effect
vN / race N	N identical runs in parallel worktrees
vs	2+ different runs in parallel worktrees
pick ["criteria"]	Resolver: pick one winner (default)
merge ["criteria"]	Resolver: synthesize all results
compare	Resolver: write comparison doc, no merge

Composition examples

cook "A" vs "B" pick "criteria" -y       # two approaches, pick winner
cook "A" vs "B" merge "best of both" -y  # synthesize both
cook "A" vs "B" compare                  # comparison doc only (no prompts)
cook "A" v3 "criteria" -y                # race 3, implicit pick
cook "A" x3 vs "B" x3 pick "best" -y    # per-branch loop operators

Agents must always pass -y on composition commands to avoid hanging on prompts.

Flags

-y, --yes                      Auto-accept all prompts (REQUIRED for agents)
--max-iterations N             Max review iterations
--work-agent AGENT             Per-step agent override
--review-agent AGENT
--work-model MODEL             Per-step model override
--review-model MODEL
--hide-request                 Hide the templated request panel

IMPORTANT: Always use -y when invoking cook as an agent. Composition commands (v3, vs, pick, merge) prompt for confirmation ("Apply Run N?", "Remove worktrees?"). Without -y, the process hangs waiting for interactive input that agents cannot provide. This flag auto-accepts all prompts.

Prerequisites

Before running cook:

1. The project must have cook init run (creates COOK.md, .cook/config.json)
2. For composition operators (vs, vN), the working tree must be clean (commit first)

When to use cook vs doing the work directly

Use cook when:

• The user explicitly asks to "cook" or "let it cook"
• Multiple iterations of refinement are needed (review loops)
• Multiple competing approaches should be tried (races, vs)
• A task list needs sequential progression (ralph)
• The user wants autonomous completion without manual review cycles

Do the work directly when:

• It's a simple, one-shot change
• The user wants to review each step interactively