Ralph Loop (Event-Driven)

Enhanced Ralph pattern with event-driven notifications — Codex/Claude calls OpenClaw when it needs attention instead of polling.

Key Concepts

Clean Sessions

Each iteration spawns a fresh agent session with clean context. This is intentional:

• - Avoids context window limits
• Each codex exec is a new process with no memory of previous runs
• Memory persists via files: IMPLEMENTATION_PLAN.md, AGENTS.md, git history

File-Based Notification Fallback

If OpenClaw is rate-limited when Codex sends a wake notification:

1. 1. The notification is written to INLINECODE3
2. Wake is attempted (may fail)
3. When OpenClaw recovers, it checks for pending notifications
4. Work is never lost — it's all in git/files

File Structure

CODEBLOCK0

Notification Format

INLINECODE4:
CODEBLOCK1

Status values:

• - pending — Wake failed or not attempted
• INLINECODE6 — Wake succeeded

---

OpenClaw Recovery Procedure

When coming back online after rate limit or downtime, check for pending notifications:

CODEBLOCK2

Recovery Actions by Message Prefix

Prefix	Action
INLINECODE7	Report completion to user, summarize what was built
INLINECODE8

Inform user, ask if ready for BUILDING mode | | PROGRESS: | Log it, update user if significant | | DECISION: | Present options to user, wait for answer, inject into AGENTS.md | | ERROR: | Check logs (.ralph/ralph.log), analyze, help or escalate | | BLOCKED: | Escalate to user immediately with full context | | QUESTION: | Present to user, get clarification, inject into AGENTS.md |

Injecting Responses

To answer a decision/question for the next iteration:
CODEBLOCK3

The next Codex session will read AGENTS.md and see the answer.

Clearing Notifications

After processing a notification, clear it:

mv .ralph/pending-notification.txt .ralph/last-notification.txt

---

Workflow

1. Collect Requirements

Ask for (if not provided):

• - Goal/JTBD: What outcome is needed?
• CLI: codex, claude, opencode, INLINECODE18
• Mode: PLANNING, BUILDING, or INLINECODE21
• Tech stack: Language, framework, database
• Test command: How to verify correctness
• Max iterations: Default 20

2. Generate Specs

Break the goal into topics of concern → specs/*.md:

CODEBLOCK5

3. Generate AGENTS.md

CODEBLOCK6

4. Generate PROMPT.md (Mode-Specific)

PLANNING Mode

CODEBLOCK7bash
openclaw gateway wake --text "PLANNING: " --mode now

Use prefixes:
- `DECISION:` — Need human input on a choice
- `QUESTION:` — Requirements unclear
- `DONE:` — Planning complete

## Completion
When plan is complete and ready for building, add to IMPLEMENTATION_PLAN.md:

STATUS: PLANNING_COMPLETE

Then notify:

bash
openclaw gateway wake --text "DONE: Planning complete. X tasks identified." --mode now
CODEBLOCK10

BUILDING Mode

CODEBLOCK11bash
openclaw gateway wake --text ": " --mode now

Prefixes:
- `DECISION:` — Need human input (e.g., "SQLite vs PostgreSQL?")
- `ERROR:` — Tests failing after 3 attempts
- `BLOCKED:` — Missing dependency, credentials, or unclear spec
- `PROGRESS:` — Major milestone complete (optional)
- `DONE:` — All tasks complete

## Completion
When all tasks are done:
1. Add to IMPLEMENTATION_PLAN.md: `STATUS: COMPLETE`
2. Notify:

bash
openclaw gateway wake --text "DONE: All tasks complete. Summary: " --mode now
CODEBLOCK13

5. Run the Loop

Use the provided scripts/ralph.sh:

CODEBLOCK14

---

Parallel Execution

For independent tasks, use git worktrees:

CODEBLOCK15

Track sessions:

Session ID	Worktree	Task	Status
abc123	/tmp/task-auth	Auth module	running
def456

/tmp/task-upload | Image upload | running |

Each Codex notifies independently. Check .ralph/pending-notification.txt in each worktree.

---

CLI-Specific Notes

Codex

• - Requires git repository
• Each codex exec is a fresh session — no memory between calls
• INLINECODE26: Auto-approve in workspace (sandboxed)
• INLINECODE27: No sandbox, no approvals (dangerous but fast)
• Default model: gpt-5.2-codex

Claude Code

• - --dangerously-skip-permissions: Auto-approve (use in sandbox)
• No git requirement
• Each invocation is fresh

OpenCode

• - INLINECODE29

Goose

• - INLINECODE30

---

Safety

⚠️ Auto-approve flags are dangerous. Always:

1. 1. Run in a dedicated directory/branch
2. Use a sandbox (Docker/VM) for untrusted projects
3. Have git reset --hard ready as escape hatch
4. Review commits before pushing

---

Quick Start

CODEBLOCK16

---

Example: Antique Catalogue

CODEBLOCK17

The agent will:

1. 1. (PLANNING) Break this into 10-15 tasks
2. (BUILDING) Implement each task, one per iteration
3. Commit after each successful implementation
4. Notify on completion or if blocked