coding-agent-loops_skill

Overview

This skill runs long-lived AI coding agents in persistent tmux sessions using the Ralph retry loop and completion hooks. It makes agent runs self-healing: sessions survive restarts, agents auto-retry on transient failures, and you get immediate completion notifications. The pattern is optimized for multi-step coding tasks and PRD-driven workflows.

How this skill works

Each run starts a fresh short-lived agent iteration inside a named tmux session tied to a stable socket (e.g., ~/.tmux/sock). The agent works from repo files and git history, and a completion hook captures exit codes, fires an OpenClaw event, and leaves the tmux pane readable. Ralph loops restart failed iterations until PRD checklist items are completed or a terminal condition is reached.

When to use it

• Running multi-step feature work driven by a PRD checklist
• Long-running or flaky coding agents that must survive host restarts
• Automated retry for tasks that hit transient API errors or rate limits
• Parallel agents working on separate tasks or branches
• Small focused fixes where you still want session persistence and notifications

Best practices

• Always run agents inside tmux and use a stable socket (e.g., ~/.tmux/sock) to avoid macOS/tmp cleanup
• Append the completion hook to every tmux command to capture EXIT_CODE, emit an OpenClaw event, and keep the pane alive
• Prefer PRD.md checklists for multi-step work so Ralph can validate completion
• Log active session names externally (daily notes or a tracker) to avoid orphaned runs
• Verify commits and diffs after a run (git log/diff) before declaring failure or success
• Prepend common tool paths in tmux if tools are not found (PATH issues are common)

Example use cases

• Run ralphy --codex --prd PRD.md in tmux to complete a multi-step feature across several iterations
• Start a persistent session for a bugfix: tmux new -d -s fix 'cd repo && ralphy --codex "Fix X"; <completion-hook>'
• Execute parallel feature builds with ralphy --codex --parallel --prd PRD.md to process multiple PRD items concurrently
• Use claude/claude-code via ralphy --claude for agents that prefer Claude Code instead of Codex
• Quick single-file fixes with codex exec inside a tmux Ralph loop to survive transient failures