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.

Prerequisites

tmux installed
ralphy-cli: npm install -g ralphy-cli
A coding agent: codex (Codex CLI) or claude (Claude Code)
Stable tmux socket: always use ~/.tmux/sock

Quick Start

Single Task

tmux -S ~/.tmux/sock new -d -s my-task \
  "cd /path/to/repo && ralphy --codex 'Fix the authentication bug'; \
   EXIT_CODE=\$?; echo EXITED: \$EXIT_CODE; \
   openclaw system event --text 'my-task finished (exit \$EXIT_CODE) in \$(pwd)' --mode now; \
   sleep 999999"

PRD-Based Workflow

tmux -S ~/.tmux/sock new -d -s feature-build \
  "cd /path/to/repo && ralphy --codex --prd PRD.md; \
   EXIT_CODE=\$?; echo EXITED: \$EXIT_CODE; \
   openclaw system event --text 'feature-build finished (exit \$EXIT_CODE)' --mode now; \
   sleep 999999"

Parallel Agents

ralphy --codex --parallel --prd PRD.md

Session Management

# List active sessions
tmux -S ~/.tmux/sock list-sessions

# Check progress
tmux -S ~/.tmux/sock capture-pane -t my-task -p | tail -20

# Kill a session
tmux -S ~/.tmux/sock kill-session -t my-task

Command Anatomy

Stable socket: -S ~/.tmux/sock (survives macOS /tmp cleanup)
Named session: -s <name> (for monitoring)
PATH fix: PATH=/opt/homebrew/bin:$PATH (if tools aren't found)
The agent command: codex exec --full-auto or ralphy --codex
Completion hook: openclaw system event for instant notification
Sleep tail: sleep 999999 keeps shell alive for readable output

PRD Format

Ralph tracks completion via markdown checklists:

## Tasks
- [ ] Create the API endpoint
- [ ] Add input validation
- [ ] Write tests
- [x] Already done (skipped)

When to Use What

Scenario	Tool
Multi-step feature with PRD	`ralphy --codex --prd PRD.md`
Task that has stalled before	`ralphy --codex` (auto-retry)
Parallel independent tasks	`ralphy --codex --parallel --prd PRD.md`
Tiny focused fix	`codex exec --full-auto`
Skip tests for speed	`ralphy --codex --fast`
Use Claude Code	`ralphy --claude`

Post-Completion Verification

Before declaring success or failure:

git log --oneline -3 — did the agent commit?
git diff --stat — uncommitted changes?
Read the tmux pane output — what actually happened?

Troubleshooting

"Failed to refresh token" → run codex auth login
Agent reads files and exits → wrap in Ralph loop
API rate limits (429s) → reduce parallelism or stagger starts
Session died → restart with same command

coding-agent-loops