Cook parses three categories of tokens:

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

cook "work" x3 review          
cook "work" review x3          
cook "work" review v3 pick     

repeat (xN)

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

cook "Add dark mode" x3           
cook "Add dark mode" repeat 3     
cook "Add dark mode" x3 review    
cook "Add dark mode" review x3    

review

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.

work -> review -> gate -> iterate <<

cook "Add dark mode" review           
cook "Add dark mode" review 5         

Provide custom prompts after review, or use positional shorthand:

cook "Add dark mode" review \
     "Review for accessibility" \
     "DONE if WCAG AA, else ITERATE"


cook "Add dark mode" \
     "Review for accessibility" \
     "DONE if WCAG AA, else ITERATE"


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

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"


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.

versions (vN / race N)

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

cook "Add dark mode" v3                       
cook "Add dark mode" v3 "least code wins"     
cook "Add dark mode" race 3 "least code wins" 

cook "Add dark mode" review v3 "cleanest"      
cook "Add dark mode" x3 v3 "most complete"     

vs

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"

Resolvers

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"]
}

Sandbox Modes

Note: OpenCode is only supported in Docker mode.