Ralph Loop (Agent Mode)

Overview

This skill guides OpenClaw agents to execute Ralph Loop workflows using the exec and process tools. The agent orchestrates AI coding agent sessions following the Ralph playbook flow: Define Requirements → JTBD → Focus Topics → specs/*.md PLANNING Loop → Create/update IMPLEMENTATION_PLAN.md (do not implement) BUILDING Loop → Implement tasks, run tests (backpressure), update plan, commit The loop persists context via PROMPT.md + AGENTS.md (loaded each iteration) and the plan/specs on disk.

How This Skill Works

This skill generates instructions for OpenClaw agents to execute Ralph Loops using the exec and process tools. The agent calls exec tool with the coding agent command Uses pty: true to provide TTY for interactive CLIs Uses background: true for monitoring capabilities Uses process tool to monitor progress and detect completion Important: Users don't run these scripts directly - the OpenClaw agent executes them using its tool capabilities.

TTY Requirements

Some coding agents require a real terminal (TTY) to work properly, or they will hang: Interactive CLIs (need TTY): OpenCode, Codex, Claude Code, Pi, Goose Non-interactive CLIs (file-based): aider, custom scripts Solution: Use exec + process mode for interactive CLIs, simple loops for file-based tools.

Interactive CLIs (Recommended Pattern)

• For OpenCode, Codex, Claude Code, Pi, and Goose - these require TTY support:
• When I (the agent) receive a Ralph Loop request, I will:
• Use exec tool to launch the coding agent:
• exec tool with parameters:
• command: "opencode run --model <MODEL> \"$(cat PROMPT.md)\""
• workdir: <project_path>
• background: true
• pty: true
• yieldMs: 60000
• timeout: 3600
• Capture session ID from exec tool response
• Use process tool to monitor:
• process tool with:
• action: "poll"
• sessionId: <captured_session_id>
• process tool with:
• action: "log"
• sessionId: <captured_session_id>
• offset: -30 (for recent output)
• Check completion by reading IMPLEMENTATION_PLAN.md for sentinel text
• Clean up with process kill if needed:
• process tool with:
• action: "kill"
• sessionId: <session_id>
• Benefits: TTY support, real-time logs, timeout handling, parallel sessions, workdir isolation

1) Gather Inputs

Required: Goal / JTBD CLI (opencode, codex, claude, goose, pi, other) Mode (PLANNING, BUILDING, or BOTH) Max iterations (default: PLANNING=5, BUILDING=10) Optional: Completion sentinel (default: STATUS: COMPLETE in IMPLEMENTATION_PLAN.md) Working directory (default: $PWD) Timeout per iteration (default: 3600s) Sandbox choice Auto-approval flags (--full-auto, --yolo, --dangerously-skip-permissions) Auto-detect: If CLI in interactive list → use exec tool with pty: true Extract model flag from CLI requirements

2) Requirements → Specs (Optional)

If requirements are unclear: Break JTBD into focus topics Draft specs/<topic>.md for each Keep specs short and testable

3) PROMPT.md + AGENTS.md

PROMPT.md references: specs/*.md IMPLEMENTATION_PLAN.md Relevant project files AGENTS.md includes: Test commands (backpressure) Build/run instructions Operational learnings

4) Prompt Templates

• PLANNING Prompt (no implementation):
• You are running a Ralph PLANNING loop for this goal: <goal>.
• Read specs/* and the current codebase. Only update IMPLEMENTATION_PLAN.md.
• Rules:
• Do not implement
• Do not commit
• Create a prioritized task list
• Write down questions if unclear
• Completion:
• When plan is ready, add: STATUS: PLANNING_COMPLETE
• BUILDING Prompt:
• You are running a Ralph BUILDING loop for this goal: <goal>.
• Context: specs/*, IMPLEMENTATION_PLAN.md, AGENTS.md
• Tasks:
• 1) Pick the most important task
• 2) Investigate code
• 3) Implement
• 4) Run backpressure commands from AGENTS.md
• 5) Update IMPLEMENTATION_PLAN.md
• 6) Update AGENTS.md with learnings
• 7) Commit with clear message
• Completion:
• When all done, add: STATUS: COMPLETE

5) CLI Command Reference

The agent constructs command strings using these patterns: CLICommand String PatternOpenCodeopencode run --model <MODEL> "$(cat PROMPT.md)"Codexcodex exec <FLAGS> "$(cat PROMPT.md)" (requires git)Claude Codeclaude <FLAGS> "$(cat PROMPT.md)"Pipi --provider <PROVIDER> --model <MODEL> -p "$(cat PROMPT.md)"Goosegoose run "$(cat PROMPT.md)" Common flags: Codex: --full-auto, --yolo, --model <model> Claude: --dangerously-skip-permissions

Example 1: OpenCode Ralph Loop

• Agent executes this sequence:
• Step 1: Launch OpenCode with exec tool
• {
• command: "opencode run --model github-copilot/claude-opus-4.5 \"$(cat PROMPT.md)\"",
• workdir: "/path/to/project",
• background: true,
• pty: true,
• timeout: 3600,
• yieldMs: 60000
• }
• Step 2: Capture session ID from response
• sessionId: "abc123"
• Step 3: Monitor with process tool every 10-30 seconds
• {
• action: "poll",
• sessionId: "abc123"
• }
• Step 4: Check recent logs
• {
• action: "log",
• sessionId: "abc123",
• offset: -30
• }
• Step 5: Read IMPLEMENTATION_PLAN.md to check for completion
• Look for: "STATUS: COMPLETE" or "STATUS: PLANNING_COMPLETE"
• Step 6: If complete or timeout, cleanup
• {
• action: "kill",
• sessionId: "abc123"
• }

Example 2: Codex with Full Auto

Agent tool calls: exec tool: { command: "codex exec --full-auto --model anthropic/claude-opus-4 \"$(cat PROMPT.md)\"", workdir: "/path/to/project", background: true, pty: true, timeout: 3600 } # Then monitor with process tool as above

Completion Detection

Use flexible regex to match variations: grep -Eq "STATUS:?\s*(PLANNING_)?COMPLETE" IMPLEMENTATION_PLAN.md Matches: STATUS: COMPLETE STATUS:COMPLETE STATUS: PLANNING_COMPLETE ## Status: PLANNING_COMPLETE

Auto-Approval Flags (Risky!)

Codex: --full-auto (sandboxed, auto-approve) or --yolo (no sandbox!) Claude: --dangerously-skip-permissions Recommendation: Use sandboxes (docker/e2b/fly) and limited credentials

Escape Hatches

Stop: Ctrl+C Kill session: process tool with action: "kill" Rollback: git reset --hard HEAD~N

Best Practices

Start small: Test with 1-2 iterations first Workdir isolation: Prevent reading unrelated files Set timeouts: Default 1h may not fit all tasks Monitor actively: Check logs, don't terminate prematurely Requirements first: Clear specs before building Backpressure early: Add tests from the start

Troubleshooting

ProblemSolutionOpenCode hangsEnsure agent uses exec tool with pty: trueSession won't startCheck CLI path, git repo, command syntaxCompletion not detectedVerify sentinel format in IMPLEMENTATION_PLAN.mdProcess timeoutAgent should increase timeout parameter or simplify tasksParallel conflictsAgent should use git worktrees for isolationCan't see progressAgent should use process tool with action: "log"

License

MIT

Credits

This skill builds upon work by: @jordyvandomselaar - Original Ralph Loop concept and workflow design @steipete - Coding agent patterns and exec/process tool usage with pty support Key improvement: Uses OpenClaw's exec tool with pty: true to provide TTY for interactive CLIs, solving the hanging issue that occurs with simple background bash execution.