Coding Agent Loops

Run long-lived AI coding agents (Codex, Claude Code) in persistent tmux sessions with Ralph retry loops and completion hooks. Use when running multi-step cod...

Security Scan

Instructions match the stated goal (running persistent coding agents in tmux) but the skill omits declaring several required tooling and implies global installs and cross-system notifications that are surprising and deserve review.

Purpose & Capability

The skill's purpose — running coding agents in persistent tmux sessions with retry/completion hooks — is coherent with the commands shown. However the SKILL.md depends on several external CLIs (ralphy-cli, codex/claude CLIs, and the platform 'openclaw' CLI) and specific filesystem paths (~/.tmux/sock, ~/.codex/log) without declaring them in the manifest. The external tools are plausible for this purpose, but the manifest omission is an inconsistency the user should be aware of.

Instruction Scope

The instructions tell the agent/user to run commands that read and act on local repos (cd /path/to/repo, git log/diff), read logs (~/.codex/log), and invoke an 'openclaw system event' command that posts notifications to the OpenClaw environment. The completion hook is mandatory and will send events outside the local host. These actions go beyond just launching a process and include reading local files and sending external notifications — the scope is broader than the manifest indicates.

Install Mechanism

There is no install spec in the registry, but the SKILL.md instructs users to run `npm install -g ralphy-cli`. Global npm installs run arbitrary code from the npm registry and should be treated as a moderate risk. The skill does not provide a vetted install source or alternative, nor does it declare this dependency in metadata.

Credentials

The manifest lists no required environment variables or credentials, yet the instructions reference tools that typically require authentication (codex auth login) and an 'openclaw' CLI that likely relies on platform credentials or tokens. The SKILL.md also expects access to user home paths. The absence of declared credential or config requirements is an omission and reduces transparency about what secrets or auth will be used.

Persistence & Privilege

The skill is not always-enabled and uses the platform-default model invocation settings, which is appropriate. It does instruct long-lived tmux sessions and uses long sleeps to keep panes alive, and it mandates firing an external event on completion — behavior that persists outside the single-process lifecycle but does not in itself modify other skills or system-wide config.

Scan Findings in Context

[no_static_findings] expected: The static regex scanner found no code files to analyze because this is an instruction-only SKILL.md. That absence is expected but means the security surface is entirely in the prose/instructions.

What to consider before installing

This skill's instructions generally do what its name says, but it omits declaring important dependencies and recommends actions that can change system state and send external notifications. Before using it: (1) verify the provenance of 'ralphy-cli' on npm and prefer installing it in a sandbox or non-global environment after inspecting the package; (2) confirm you have (and are willing to use) the codex/claude CLIs and understand their auth flows; (3) check what 'openclaw system event' does and whether you want automatic external notifications; (4) don't run the provided commands in sensitive repositories without review (they read logs, run git commands, and run arbitrary agent code); (5) consider removing or modifying the mandatory completion hook if you don't want automatic notifications. If the author can update the manifest to list required tools, installs, and any needed credentials, the guidance would be clearer and the risk easier to evaluate.

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
• ralphy-cli: npm install -g ralphy-cli
• 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

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 'Ralph loop my-task finished (exit \$EXIT_CODE) in \$(pwd)' --mode now; \
   sleep 999999"

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

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 'Ralph loop feature-build finished (exit \$EXIT_CODE) in \$(pwd)' --mode now; \
   sleep 999999"

Parallel Agents on Separate Tasks

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

Session Management

Check Progress

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

List Active Sessions

tmux -S ~/.tmux/sock list-sessions

Kill a Session

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

The Completion Hook (Mandatory)

Always append this to tmux commands:

; EXIT_CODE=$?; echo "EXITED: $EXIT_CODE"; \
openclaw system event --text "Ralph loop <name> finished (exit $EXIT_CODE) in $(pwd)" --mode now; \
sleep 999999

Why each part matters:

• EXIT_CODE=$? — captures the agent's exit code
• echo "EXITED: $EXIT_CODE" — visible in tmux pane output
• openclaw system event — fires a wake event so OpenClaw notifies you immediately
• sleep 999999 — keeps the shell alive so output remains readable

PRD Format

Ralph tracks completion via markdown checklists:

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

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

When to Use What

Scenario	Tool
Multi-step features, PRD checklists	ralphy --codex --prd PRD.md
Tasks that have stalled before	ralphy --codex "task" (auto-retry)
Tiny focused fixes, one-file changes	codex exec --full-auto "task"
Parallel work on different tasks	ralphy --codex --parallel --prd PRD.md
Skip tests/lint for speed	ralphy --codex --fast "task"
Use Claude Code instead of Codex	ralphy --claude "task"

Key Principles

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.