ralph-loop-agentGuide OpenClaw agents to execute Ralph Wiggum loops using exec and process tools. Agent orchestrates coding agents (Codex, Claude Code, OpenCode, Goose) with proper TTY support via pty:true. Plans/builds code via PROMPT.md + AGENTS.md, SPECS and IMPLEMENTATION_PLAN.md. Includes PLANNING vs BUILDING modes, backpressure, sandboxing, and completion conditions. Users request loops, agents execute using tools.
Install via ClawdBot CLI:
clawdbot install addozhang/ralph-loop-agentThis 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:
1) Define Requirements ā JTBD ā Focus Topics ā specs/*.md
2) PLANNING Loop ā Create/update IMPLEMENTATION_PLAN.md (do not implement)
3) 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.
This skill generates instructions for OpenClaw agents to execute Ralph Loops using the exec and process tools.
exec tool with the coding agent commandpty: true to provide TTY for interactive CLIsbackground: true for monitoring capabilitiesprocess tool to monitor progress and detect completionImportant: Users don't run these scripts directly - the OpenClaw agent executes them using its tool capabilities.
Some coding agents require a real terminal (TTY) to work properly, or they will hang:
Interactive CLIs (need TTY):
Non-interactive CLIs (file-based):
Solution: Use exec + process mode for interactive CLIs, simple loops for file-based tools.
For OpenCode, Codex, Claude Code, Pi, and Goose - these require TTY support:
When I (the agent) receive a Ralph Loop request, I will:
exec tool with parameters:
- command: "opencode run --model <MODEL> \"$(cat PROMPT.md)\""
- workdir: <project_path>
- background: true
- pty: true
- yieldMs: 60000
- timeout: 3600
process tool with:
- action: "poll"
- sessionId: <captured_session_id>
process tool with:
- action: "log"
- sessionId: <captured_session_id>
- offset: -30 (for recent output)
IMPLEMENTATION_PLAN.md for sentinel text
process tool with:
- action: "kill"
- sessionId: <session_id>
Benefits: TTY support, real-time logs, timeout handling, parallel sessions, workdir isolation
Required:
opencode, codex, claude, goose, pi, other)PLANNING, BUILDING, or BOTH)Optional:
STATUS: COMPLETE in IMPLEMENTATION_PLAN.md)$PWD)--full-auto, --yolo, --dangerously-skip-permissions)Auto-detect:
If requirements are unclear:
specs/.md for eachPROMPT.md references:
specs/*.mdIMPLEMENTATION_PLAN.mdAGENTS.md includes:
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
The agent constructs command strings using these patterns:
| CLI | Command String Pattern |
|-----|----------------------|
| OpenCode | opencode run --model |
| Codex | codex exec (requires git) |
| Claude Code | claude |
| Pi | pi --provider |
| Goose | goose run "$(cat PROMPT.md)" |
Common flags:
--full-auto, --yolo, --model --dangerously-skip-permissionsAgent 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"
}
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
Use flexible regex to match variations:
grep -Eq "STATUS:?\s*(PLANNING_)?COMPLETE" IMPLEMENTATION_PLAN.md
Matches:
STATUS: COMPLETESTATUS:COMPLETESTATUS: PLANNING_COMPLETE## Status: PLANNING_COMPLETE--full-auto (sandboxed, auto-approve) or --yolo (no sandbox!)--dangerously-skip-permissionsCtrl+Cgit reset --hard HEAD~N| Problem | Solution |
|---------|----------|
| OpenCode hangs | Ensure agent uses exec tool with pty: true |
| Session won't start | Check CLI path, git repo, command syntax |
| Completion not detected | Verify sentinel format in IMPLEMENTATION_PLAN.md |
| Process timeout | Agent should increase timeout parameter or simplify tasks |
| Parallel conflicts | Agent should use git worktrees for isolation |
| Can't see progress | Agent should use process tool with action: "log" |
MIT
This skill builds upon work by:
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.
Generated Feb 24, 2026
A software development team uses Ralph Loop to refactor a legacy codebase. The agent orchestrates coding agents to analyze the code, create a refactoring plan, and implement changes incrementally while running tests to ensure functionality is preserved. This reduces manual effort and minimizes errors during large-scale code modernization.
A startup leverages Ralph Loop to rapidly prototype new features for their web application. The agent guides coding agents through planning and building phases, generating specifications, writing code, and integrating backpressure tests to validate each iteration. This accelerates product development cycles and improves code quality.
An IT operations team employs Ralph Loop to automate infrastructure-as-code scripts. The agent uses coding agents to design and implement deployment pipelines, monitor progress with TTY support, and update documentation based on operational learnings. This streamlines cloud resource management and reduces manual configuration errors.
An educational institution integrates Ralph Loop to build interactive coding tutorials. The agent orchestrates agents to generate lesson plans, code examples, and automated grading scripts, with sandboxing for safe execution. This enhances learning experiences by providing real-time feedback and adaptive content.
A data science team utilizes Ralph Loop to optimize ETL pipelines. The agent guides coding agents through planning data transformations, implementing efficient code, and running backpressure tests to ensure performance and reliability. This improves data processing speeds and reduces maintenance overhead.
Offer Ralph Loop as a cloud-based service where users pay a monthly fee for access to AI agent orchestration, with tiers based on usage limits and support levels. This provides recurring revenue and scales with customer growth in software development and automation markets.
Sell on-premise licenses to large organizations needing secure, customized Ralph Loop deployments for internal development teams. This includes premium support, training, and integration services, generating high-value contracts and long-term partnerships.
Provide professional services to help clients implement Ralph Loop for specific projects, such as legacy system upgrades or new product development. Revenue comes from hourly rates or project-based fees, leveraging expertise in AI agent workflows and tooling.
š¬ Integration Tip
Ensure proper TTY configuration for interactive coding agents like OpenCode to prevent hangs, and use sandboxing for safe execution in production environments.
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
Provides a 7-step debugging protocol plus language-specific commands to systematically identify, verify, and fix software bugs across multiple environments.
A comprehensive skill for using the Cursor CLI agent for various software engineering tasks (updated for 2026 features, includes tmux automation guide).
Write, run, and manage unit, integration, and E2E tests across TypeScript, Python, and Swift using recommended frameworks.
Control and operate Opencode via slash commands. Use this skill to manage sessions, select models, switch agents (plan/build), and coordinate coding through Opencode.
Coding style memory that adapts to your preferences, conventions, and patterns for consistent coding.