Coding Agent Loops

Run AI coding agents in persistent, self-healing sessions with automatic retry and completion notification.

Core Concept

Instead of one long agent session that stalls or dies, run many short sessions in a loop. Each iteration starts fresh — no accumulated context. The agent picks up where it left off via files and git history. This is the "Ralph loop" pattern.

Prerequisites

• - tmux installed
• INLINECODE1: INLINECODE2
• A coding agent: codex (Codex CLI) or claude (Claude Code)
• Stable tmux socket: always use ~/.tmux/sock (default /tmp socket gets reaped by macOS)

Quick Start

Single Task

PRD-Based Workflow (Preferred for Multi-Step Work)

Parallel Agents on Separate Tasks

Session Management

Check Progress

List Active Sessions

Kill a Session

The Completion Hook (Mandatory)

Always append this to tmux commands:
CODEBLOCK6

Why each part matters:

• - EXIT_CODE=$? — captures the agent's exit code
• INLINECODE8 — visible in tmux pane output
• INLINECODE9 — fires a wake event so OpenClaw notifies you immediately
• INLINECODE10 — keeps the shell alive so output remains readable

PRD Format

Ralph tracks completion via markdown checklists:
CODEBLOCK7

Ralph validates that all items are checked before accepting a completion signal from the agent.

When to Use What

Key Principles

1. 1. Always use tmux — background exec processes die on gateway/host restart. tmux sessions persist.
2. Always use the stable socket (~/.tmux/sock) — the default /tmp socket gets cleaned up.
3. Always add the completion hook — without it you won't know when the agent finishes.
4. Log active sessions — record running sessions in daily notes or a tracking file so you don't lose awareness.
5. Verify before declaring failure — after a process ends, check git log, git diff, and process output before concluding it failed.
6. PATH in tmux — tmux may not inherit your full PATH. Prepend /opt/homebrew/bin: if tools aren't found.

Troubleshooting

• - Agent exits immediately: Check ~/.codex/log/codex-tui.log for auth errors. May need codex auth login.
• Ralph marks tasks done but nothing committed: Ralph can mark PRD tasks complete even when the agent fails silently. Always verify via git log --oneline -3 and git diff --stat.
• API rate limits (429s): Common when running multiple parallel agents. Ralph's retry handles this, but reduce parallelism if persistent.
• Session disappeared: tmux sessions can die from OOM or system restarts. Check with tmux -S ~/.tmux/sock has-session -t <name> and restart if needed.