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. The notification is written to .ralph/pending-notification.txt
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

project/
├── PROMPT.md                      # Loaded each iteration (mode-specific)
├── AGENTS.md                      # Project context, test commands, learnings
├── IMPLEMENTATION_PLAN.md         # Task list with status
├── specs/                         # Requirements specs
│   ├── overview.md
│   └── <feature>.md
└── .ralph/
    ├── ralph.log                  # Execution log
    ├── pending-notification.txt   # Current pending notification (if any)
    └── last-notification.txt      # Previous notification (for reference)

Notification Format

.ralph/pending-notification.txt:

{
  "timestamp": "2026-02-07T02:30:00+01:00",
  "project": "/home/user/my-project",
  "message": "DONE: All tasks complete.",
  "iteration": 15,
  "max_iterations": 20,
  "cli": "codex",
  "status": "pending"
}

Status values:

• pending — Wake failed or not attempted
• delivered — Wake succeeded

OpenClaw Recovery Procedure

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

# Find all pending notifications across projects
find ~/projects -name "pending-notification.txt" -path "*/.ralph/*" 2>/dev/null

# Or check a specific project
cat /path/to/project/.ralph/pending-notification.txt

Recovery Actions by Message Prefix

Injecting Responses

To answer a decision/question for the next iteration:

echo "## Human Decisions
- [$(date '+%Y-%m-%d %H:%M')] Q: <question>? A: <answer>" >> AGENTS.md

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

Clearing Notifications