Cook: A simple CLI for orchestrating Claude Code

Cook parses three categories of tokens:

A prompt. One agent call. The core unit.

Wrap work with iteration: xN , review , ralph .

Run parallel branches and resolve: vN , vs , pick .

Operators compose left to right. Each wraps everything to its left.

cook "work" x3 review # (work×3) → review loop
cook "work" review x3 # (work → review loop) × 3
cook "work" review v3 pick # race 3, each with a review loop

xN runs work N times sequentially, each pass seeing the previous output.

cook "Add dark mode" x3 # 3 sequential passes
cook "Add dark mode" repeat 3 # long-form
cook "Add dark mode" x3 review # 3 passes, then a review loop
cook "Add dark mode" review x3 # review loop repeated 3 times

review adds a review→gate loop. After work, a reviewer checks quality and a gate decides DONE or ITERATE. On ITERATE, the iterate step runs, then review→gate repeats.

cook "Add dark mode" review # default prompts, up to 3 iterations
cook "Add dark mode" review 5 # up to 5 iterations

Provide custom prompts after review , or use positional shorthand:

# Explicit
cook "Add dark mode" review \
"Review for accessibility" \
"DONE if WCAG AA, else ITERATE"
# Shorthand — same result
cook "Add dark mode" \
"Review for accessibility" \
"DONE if WCAG AA, else ITERATE"
# With iterate prompt and max-iterations
cook "Add dark mode" \
"Review for accessibility" \
"DONE if WCAG AA, else ITERATE" \
"Fix the issues" 5

Use different agents or models per step:

cook "Add dark mode" review \
--work-agent codex --work-model gpt-5-codex \
--review-agent claude --review-model opus

Ralph wraps a cook with an outer gate for task-list progression. The work prompt is self-directing — it reads project state to find the current task each time.

cook "Work on next task in plan.md" \
ralph 5 "DONE if all tasks complete, else NEXT"
# review gate per task, then ralph advances
cook "Work on next task in plan.md" \
review "Code review" "DONE if no High issues, else ITERATE" \
ralph 5 "DONE if all tasks complete, else NEXT"

The review gate decides DONE (pass to ralph) or ITERATE (fix and retry). The ralph gate decides DONE (exit) or NEXT (advance to next task, reset iterations).

Composition operators run multiple cooks in parallel isolated git worktrees, then combine the results with a resolver.

vN runs N identical cooks in parallel worktrees. pick is the default resolver.

cook "Add dark mode" v3 # 3 runs, pick the best
cook "Add dark mode" v3 "least code wins" # with pick criteria
cook "Add dark mode" race 3 "least code wins" # long-form alias
cook "Add dark mode" review v3 "cleanest" # race 3, each with a review loop
cook "Add dark mode" x3 v3 "most complete" # race 3, each with 3 passes

vs runs two different cooks in parallel worktrees. Each branch is a full cook — it can have its own loop operators.

cook "Implement auth with JWT" \
vs \
"Implement auth with sessions" \
pick "best security"
cook "Build with React" review "Check accessibility" "DONE if WCAG AA" 3 \
vs \
"Build with Vue" review "Check bundle size" "DONE if under 50kb" 5 \
merge "best developer experience"

| Resolver | Behavior | |---|---| pick ["criteria"] | Pick one winner. Merge that branch. Default. | merge ["criteria"] | Synthesize all results into a fresh implementation. | compare | Write a comparison doc to .cook/compare-<session>.md . No merge. |

Run cook init in your project root to scaffold configuration files:

cook init

This creates:

COOK.md — project instructions and agent prompt template .cook/config.json — agent/model/sandbox defaults and per-step overrides .cook/Dockerfile — project dependencies for Docker sandbox mode .cook/logs/ — session logs (gitignored)

Example .cook/config.json :

{
"agent": "claude",
"sandbox": "agent",
"steps": {
"work": { "agent": "codex", "model": "gpt-5-codex" },
"review": { "agent": "claude", "model": "opus" }
},
"env": ["CLAUDE_CODE_OAUTH_TOKEN"]
}

| Mode | Flag | Description | |---|---|---| Agent (default) | --sandbox agent | Agents use their own OS-level sandboxes. No Docker required. | Docker | --sandbox docker | Agents run in a Docker container with restricted network access. |

Note: OpenCode is only supported in Docker mode.