ralph-loop

Original source / Raw SKILL.md

---
name: ralph-loop
description: Guide 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.
version: 1.1.0
author: OpenClaw Community
keywords: [ralph-loop, ai-agent, coding-agent, pty, tty, automation, loop, opencode, codex, claude, goose, exec-tool, process-tool]
license: MIT
---

# Ralph Loop

## 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:

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.

## 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.

---

## Agent Tool Usage Patterns

### 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:**

1. **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
   ```

2. **Capture session ID** from exec tool response

3. **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)
   ```

4. **Check completion** by reading `IMPLEMENTATION_PLAN.md` for sentinel text

5. **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

---

## Agent Workflow

### 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:

| CLI | Command String Pattern |
|-----|----------------------|
| **OpenCode** | `opencode run --model <MODEL> "$(cat PROMPT.md)"` |
| **Codex** | `codex exec <FLAGS> "$(cat PROMPT.md)"` (requires git) |
| **Claude Code** | `claude <FLAGS> "$(cat PROMPT.md)"` |
| **Pi** | `pi --provider <PROVIDER> --model <MODEL> -p "$(cat PROMPT.md)"` |
| **Goose** | `goose run "$(cat PROMPT.md)"` |

Common flags:
- Codex: `--full-auto`, `--yolo`, `--model <model>`
- Claude: `--dangerously-skip-permissions`

---

## Detailed Agent Tool Usage Examples

### 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:

```bash
grep -Eq "STATUS:?\s*(PLANNING_)?COMPLETE" IMPLEMENTATION_PLAN.md
```

**Matches**:
- `STATUS: COMPLETE`
- `STATUS:COMPLETE`
- `STATUS: PLANNING_COMPLETE`
- `## Status: PLANNING_COMPLETE`

---

## Safety & Safeguards

### 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
1. **Start small**: Test with 1-2 iterations first
2. **Workdir isolation**: Prevent reading unrelated files
3. **Set timeouts**: Default 1h may not fit all tasks
4. **Monitor actively**: Check logs, don't terminate prematurely
5. **Requirements first**: Clear specs before building
6. **Backpressure early**: Add tests from the start

---

## Troubleshooting

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

---

## 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.


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# Ralph Loop

## Acknowledgments

This skill is inspired by and improves upon:

1. **Ralph Loop** by @jordyvandomselaar  
   https://github.com/openclaw/skills/blob/main/skills/jordyvandomselaar/ralph-loop/SKILL.md

2. **Coding Agent** by @steipete  
   https://github.com/openclaw/skills/blob/main/skills/steipete/coding-agent/SKILL.md

## Key Improvement

**Solved the hanging issue** with coding agents in ralph-loop: The original pure background bash mode couldn't provide TTY for interactive CLIs (OpenCode, Codex, Claude Code), causing processes to hang.

**Solution**: Uses OpenClaw's **exec + process mode** to provide a real TTY environment with background monitoring and real-time log access.

---

## Introduction

Ralph Loop is a skill that guides **OpenClaw agents** to execute Ralph Wiggum playbook workflows using the `exec` and `process` tools. The agent orchestrates AI coding agent sessions, dividing software development into two phases:

1. **PLANNING**: Analyze requirements, create implementation plan, no code writing
2. **BUILDING**: Implement features according to plan, run tests, commit code

## How This Works

**For OpenClaw Agents**: This skill teaches you how to use the `exec` and `process` tools to orchestrate Ralph Loops.

**For Users**: You ask your OpenClaw agent to "create a Ralph Loop" and it will:
- Use its `exec` tool to launch coding agents (OpenCode, Codex, etc.)
- Use its `process` tool to monitor progress
- Check completion conditions by reading files
- Report progress back to you

**You don't run scripts directly** - your OpenClaw agent handles everything using its tool capabilities.

## Core Features

### ✅ Agent Tool Integration
- Uses OpenClaw's `exec` tool for launching coding agents
- Uses OpenClaw's `process` tool for monitoring and control
- Proper TTY support via `pty: true` parameter

### ✅ Interactive CLI Support
- Provides real terminal environment for OpenCode, Codex, Claude Code, Goose
- Solves hanging issues that occur without proper TTY
- Background execution with real-time monitoring

### ✅ Flexible Workflow
- Supports PLANNING, BUILDING, BOTH modes
- Configurable iteration counts and completion conditions
- Automatic task completion detection

### ✅ Safety Safeguards
- Supports sandbox environments (docker/e2b/fly)
- Working directory isolation
- Git repository validation

## Quick Start

### For Users

Simply ask your OpenClaw agent:

```
"Create a ralph loop for me using OpenCode to implement user authentication"
```

Your agent will:
1. Gather requirements and preferences
2. Create necessary files (PROMPT.md, AGENTS.md, IMPLEMENTATION_PLAN.md)
3. Use exec tool to launch the coding agent
4. Monitor progress with process tool
5. Report results to you

### For OpenClaw Agents

When a user requests a Ralph Loop:

1. **Gather configuration:**
   - CLI choice (opencode, codex, claude, goose, etc.)
   - Model selection
   - Mode (PLANNING/BUILDING/BOTH)
   - Max iterations

2. **Setup files:**
   - Create PROMPT.md with task instructions
   - Create AGENTS.md with test commands
   - Create IMPLEMENTATION_PLAN.md

3. **Execute loop using tools:**
   ```
   exec tool:
   - command: "opencode run --model X \"$(cat PROMPT.md)\""
   - workdir: project_path
   - background: true
   - pty: true
   - timeout: 3600
   ```

4. **Monitor with process tool:**
   ```
   process tool:
   - action: "poll" (check status)
   - action: "log" (view output)
   - action: "kill" (cleanup)
   ```

5. **Check completion:**
   - Read IMPLEMENTATION_PLAN.md
   - Look for "STATUS: COMPLETE"

## How OpenClaw Agents Use This Skill

### Step-by-Step Agent Workflow

**1. User Request:**
```
User: "Set up a Ralph Loop to build a REST API"
```

**2. Agent Gathers Info:**
- Which coding CLI? (OpenCode, Codex, Claude, Goose)
- Which model?
- PLANNING or BUILDING or BOTH?
- How many max iterations?

**3. Agent Creates Files:**
- Write PROMPT.md with detailed instructions
- Write AGENTS.md with test commands
- Initialize IMPLEMENTATION_PLAN.md

**4. Agent Uses exec Tool:**
```
Call exec tool with:
{
  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
}

Response contains: sessionId: "abc123"
```

**5. Agent Monitors with process Tool:**
```
Every 10-30 seconds:

Call process tool:
{
  action: "poll",
  sessionId: "abc123"
}
→ Returns: {state: "running"}

Call process tool:
{
  action: "log",
  sessionId: "abc123",
  offset: -30
}
→ Returns recent output
```

**6. Agent Checks Completion:**
```
Read IMPLEMENTATION_PLAN.md
Search for: "STATUS: COMPLETE" or "STATUS: PLANNING_COMPLETE"

If found: Success! Move to next phase or finish
If not found and under max iterations: Start next iteration
If max iterations reached: Report to user
```

**7. Agent Cleans Up:**
```
Call process tool:
{
  action: "kill",
  sessionId: "abc123"
}
```

## Workflow Details

### PLANNING Phase

Goal: Create a clear implementation plan, **without writing code**

1. Analyze requirements documents (`specs/*.md`)
2. Study existing codebase
3. Break down tasks into small steps
4. Record in `IMPLEMENTATION_PLAN.md`
5. Mark complete: `STATUS: PLANNING_COMPLETE`

**Prompt Template Example**:
```markdown
You are running a Ralph PLANNING loop for this goal: Implement user authentication.

Read specs/* and the current codebase. Only update IMPLEMENTATION_PLAN.md.

Rules:
- Do not implement any code
- Do not commit
- Create prioritized task list
- Identify risks and dependencies
- Write down questions if unclear

Completion:
When plan is ready, add: STATUS: PLANNING_COMPLETE
```

### BUILDING Phase

Goal: Implement features according to plan, ensure quality

1. Select next task from `IMPLEMENTATION_PLAN.md`
2. Investigate relevant code
3. Implement feature
4. Run test commands from `AGENTS.md` (backpressure)
5. Update implementation plan status
6. Record learnings in `AGENTS.md`
7. Commit code
8. Mark when all done: `STATUS: COMPLETE`

**Prompt Template Example**:
```markdown
You are running a Ralph BUILDING loop for this goal: Implement user authentication.

Context:
- specs/auth.md: Authentication requirements
- IMPLEMENTATION_PLAN.md: Task list
- AGENTS.md: Test commands and operational guide

Tasks:
1) Select the most important incomplete task
2) Investigate relevant code
3) Implement feature
4) Run backpressure commands from AGENTS.md (tests, lint)
5) Update IMPLEMENTATION_PLAN.md to mark task complete
6) Update AGENTS.md with today's learnings
7) Commit code with clear commit message

Completion:
When all tasks complete, add: STATUS: COMPLETE
```

## Supported CLI Tools

| Tool | Type | TTY Required | Command Template |
|------|------|-------------|-----------------|
| **OpenCode** | Interactive | ✅ Required | `opencode run --model <MODEL> "$(cat PROMPT.md)"` |
| **Codex** | Interactive | ✅ Required | `codex exec --model <MODEL> "$(cat PROMPT.md)"` |
| **Claude Code** | Interactive | ✅ Required | `claude "$(cat PROMPT.md)"` |
| **Pi** | Interactive | ✅ Required | `pi --provider <PROVIDER> --model <MODEL> -p "$(cat PROMPT.md)"` |
| **Goose** | Interactive | ✅ Required | `goose run "$(cat PROMPT.md)"` |
| **aider** | File-based | ❌ Not needed | `aider --message "$(cat PROMPT.md)"` |

## Configuration Options

### Required Configuration

- **CLI_CMD**: AI coding tool command to use
- **MODEL**: AI model (e.g., `github-copilot/claude-opus-4.5`)
- **MODE**: Run mode (`PLANNING` / `BUILDING` / `BOTH`)

### Optional Configuration

- **MAX_PLANNING_ITERS**: Maximum planning phase iterations (default: 5)
- **MAX_BUILDING_ITERS**: Maximum building phase iterations (default: 10)
- **TIMEOUT**: Timeout per iteration in seconds (default: 3600)
- **WORKDIR**: Working directory (default: `$PWD`)
- **PLAN_SENTINEL**: Completion marker regex (default: `STATUS:\s*(PLANNING_)?COMPLETE`)

### Auto-Approval Flags (Use with Caution!)

Some CLIs support auto-approval of operations, but come with risks:

- **Codex**: `--full-auto` (sandboxed), `--yolo` (⚠️ no sandbox)
- **Claude**: `--dangerously-skip-permissions` (⚠️ skips permission checks)

**Recommendations**:
- Use auto-approval in controlled environments
- Prefer sandboxes (docker, e2b, fly)
- Limit cloud service credential permissions

## Monitoring and Control (For Users)

While your agent is running a Ralph Loop, you can ask it to:

### Check Status
```
"What's the status of the Ralph Loop?"
```
Agent will use process tool to poll and show current state.

### View Progress
```
"Show me the recent output"
```
Agent will use process tool with action: "log" to display recent activity.

### Stop the Loop
```
"Stop the Ralph Loop"
```
Agent will use process tool with action: "kill" to terminate the session.

### Check What's Been Completed
```
"What tasks are done?"
```
Agent will read IMPLEMENTATION_PLAN.md and report progress.

## Troubleshooting

### Problem: OpenCode/Codex Hangs

**Cause**: Interactive CLIs need real TTY environment

**Solution**: Agent must use exec tool with `pty: true` parameter

**For users**: If your agent reports hanging, say: "Make sure you're using pty: true in the exec tool"

### Problem: Can't See What's Happening

**Solution**: Ask your agent:
- "Show me the logs"
- "What's the current status?"
- "Display recent output"

Agent will use process tool to retrieve information.

### Problem: Loop Takes Too Long

**Solution**: Ask your agent:
- "What iteration are we on?"
- "Stop this and let's try with fewer iterations"
- "Can we simplify the task?"

### Problem: Agent Reports Session Won't Start

**Check with agent**:
- Is the project in a Git repository?
- Is the coding CLI installed?
- Are the command strings correct?

## Best Practices

### For Users

1. **Start Small**: First time? Try 2-3 iterations to see how it works
2. **Clear Requirements**: Provide detailed specs in `specs/*.md` files
3. **Stay Engaged**: Check in periodically, don't just "fire and forget"
4. **Trust Your Agent**: It knows how to use the exec and process tools correctly

### For OpenClaw Agents

1. **Always Use pty: true**: For interactive CLIs (OpenCode, Codex, Claude, Goose)
2. **Set Reasonable Timeouts**: Default 3600s, adjust based on task complexity
3. **Monitor Regularly**: Poll every 10-30 seconds, not too frequently
4. **Check Completion**: Always read IMPLEMENTATION_PLAN.md after each iteration
5. **Report Progress**: Keep user informed of current iteration and status
6. **Save Logs**: Store output for debugging if things go wrong
7. **Workdir Isolation**: Use workdir parameter to limit file access scope

## Security Considerations

### For Agents: Sandbox Environments

When using auto-approval flags, prefer sandboxed execution:

**Codex with sandbox:**
```
exec tool with:
  command: "codex exec --sandbox docker --full-auto \"$(cat PROMPT.md)\""
```

**Available sandboxes:**
- Docker (local isolation)
- E2B (cloud sandbox)
- Fly.io (temporary containers)

### Auto-Approval Flags (Use Cautiously)

- **Codex**: `--full-auto` (sandboxed) or `--yolo` (⚠️ no sandbox)
- **Claude**: `--dangerously-skip-permissions` (⚠️ skips checks)

**Agent should warn user** when using auto-approval without sandbox.

### Credential Management

- Use read-only or limited permission API keys
- Don't include secrets in PROMPT.md
- Use environment variables

### Workdir Isolation

Agent should set workdir parameter to limit file access:
```
exec tool with:
  workdir: "/path/to/specific/project"
```

## Escape Hatches

If things go wrong:

### For Users

**Stop immediately:**
```
"Stop the Ralph Loop now"
"Kill the current session"
```

**Rollback changes:**
```
"Undo the last 3 commits"
"Reset to the previous state"
```

### For Agents

**Kill session:**
```
process tool:
  action: "kill"
  sessionId: <session_id>
```

**Help user rollback:**
```
exec tool:
  command: "git reset --hard HEAD~N"
```

## License

MIT License

## Contributing

Welcome to submit issues and improvement suggestions!

If you improve this skill, please consider sharing to Clawhub.

## Related Resources

- [OpenClaw Documentation](https://openclaw.com/docs)
- [Original Ralph Loop](https://github.com/openclaw/skills/blob/main/skills/jordyvandomselaar/ralph-loop/SKILL.md)
- [Coding Agent](https://github.com/openclaw/skills/blob/main/skills/steipete/coding-agent/SKILL.md)
- [Ralph Wiggum Playbook](https://ralphwiggum.dev)

```

### _meta.json

```json
{
  "owner": "addozhang",
  "slug": "ralph-loop-agent",
  "displayName": "Ralph Loop (Agent Mode)",
  "latest": {
    "version": "1.1.0",
    "publishedAt": 1770354202802,
    "commit": "https://github.com/openclaw/skills/commit/6ad73ae74f61c4a1ec9e7fc4aed512954dc9308c"
  },
  "history": []
}

```