ralph-loop

# 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`:
```json
{
  "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**:

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

# Or check a speci...

# 🐺 Ralph Loop (Event-Driven)

An enhanced [Ralph pattern](https://ghuntley.com/ralph/) implementation with **event-driven notifications** and **rate-limit resilience** for AI agent loops.

## Key Features

- 🔔 **Event-driven notifications** — Agent notifies OpenClaw on decisions, errors, completion
- 💾 **File-based fallback** — Notifications persist to `.ralph/pending-notification.txt` if wake fails
- 🔄 **Clean sessions** — Each iteration is a fresh agent context (avoids context limits)
- 📋 **PLANNING/BUILDING modes** — Separate phases for architecture and implementation
- 🧪 **Backpressure** — Run tests/lints after each implementation

## What's Different?

| Standard Ralph | This Version |
|----------------|--------------|
| Bash loop runs until done/fail | Agent notifies on events |
| Manual monitoring | Automatic escalation |
| Silent failures | Immediate error alerts |
| No rate-limit handling | File-based notification fallback |
| Lost notifications | Always recoverable |

## How It Works

1. **PLANNING phase**: Agent analyzes specs, creates `IMPLEMENTATION_PLAN.md`
2. **BUILDING phase**: Agent implements tasks one by one, tests, commits
3. **Notifications**: Agent writes to `.ralph/pending-notification.txt` + triggers OpenClaw via cron
4. **Triage**: OpenClaw receives notification, evaluates if it can help or needs to escalate to human

### Notification Flow

```
Codex/Claude ──► .ralph/pending-notification.txt
     │                        │
     └──► openclaw cron add ──┴──► OpenClaw (triage)
                                        │
                              ┌─────────┴─────────┐
                              ▼                   ▼
                        Can help?            Escalate
                              │                   │
                              ▼                   ▼
                        Fix & restart      Notify human
```

### Notification Prefixes

| Prefix | Meaning | Typical Action |
|--------|---------|----------------|...