Coding Sessions

Run long-lived AI coding agents (Codex CLI, Claude Code, Ralph loops) in persistent tmux sessions with completion hooks and automatic monitoring. Use when la...

Security Scan

The instructions mostly match the stated goal (running long-lived coding agents) but the skill omits required binaries/credentials and makes assumptions about tooling and file locations that are not declared — this mismatch could lead to unexpected access or behavior.

Purpose & Capability

The skill claims to orchestrate long-running coding agents but the SKILL.md requires/assumes tmux, codex, ralphy/ralph (agent CLIs), git, and an openclaw CLI hook, plus a Homebrew PATH. None of these required binaries or credentials are declared in the skill metadata, which is an incoherence: a user would reasonably expect the manifest to list required tools and credentials.

Instruction Scope

Runtime instructions stay within the described purpose (start agents in tmux, monitor output, run verification via git). However the instructions also reference reading user-local logs (~/.codex/log), running auth commands (codex auth login), and writing 'daily notes' (memory/YYYY-MM-DD.md). These are reasonable for this task but broaden the scope to reading/writing user files and invoking auth flows — the skill should have declared that.

Install Mechanism

No install spec (instruction-only). This reduces install-time risk because nothing is downloaded or written by an installer. Risk comes from the commands the user/agent will run at runtime, not the installer.

Credentials

The skill declares no required environment variables or credentials but the instructions implicitly rely on existing credentials/config (e.g., codex tokens, possibly Homebrew-installed binaries in /opt/homebrew/bin). Expectation of sensitive tokens or auth state (and calls like `codex auth login`) should be reflected in the manifest; omission is disproportionate and opaque.

Persistence & Privilege

always is false and the skill does not request persistent system-wide privileges. It asks the agent to create long-lived tmux sessions and log to a local 'memory' file, which is consistent with its purpose and does not appear to alter other skills or global configuration.

What to consider before installing

This skill appears to be what it advertises (helpers for running long-lived coding agents), but it omits important implementation details. Before installing or using it, verify you have the required tools (tmux, the codex/ralph/ralphy CLIs, git, openclaw) and understand where credentials live (e.g., ~/.codex). Be cautious running or enabling '--full-auto' agents in repositories with sensitive data: those agents can execute arbitrary commands and modify files. Consider updating or requesting the skill author to: (1) declare required binaries and any credentials in the manifest, (2) fix inconsistent names/typos (e.g., 'Ralph' vs 'ralphy'), and (3) document what the openclaw event sends. If you don’t trust the agent CLIs, do not run these commands in production or sensitive projects and run them in an isolated environment.

Orchestrate long-running AI coding agents in persistent tmux sessions with completion notifications and health monitoring.

Why tmux?

Background exec processes die on gateway restart. Any coding agent expected to run >5 minutes MUST run inside tmux. This is non-negotiable.

Always use the stable socket (~/.tmux/sock) — the default /tmp socket gets reaped by macOS.

Quick Start

Single Codex Task

tmux -S ~/.tmux/sock new -d -s <name> "cd <project-dir> && \
  PATH=/opt/homebrew/bin:\$PATH codex exec --full-auto '<task description>'; \
  EXIT_CODE=\$?; echo 'EXITED:' \$EXIT_CODE; \
  openclaw system event --text '<name> finished (exit \$EXIT_CODE) in <project-dir>' --mode now; \
  sleep 999999"

Ralph Loop (preferred for multi-step work)

tmux -S ~/.tmux/sock new -d -s <name> "cd <project-dir> && \
  PATH=/opt/homebrew/bin:\$PATH ralphy --codex --prd PRD.md; \
  EXIT_CODE=\$?; echo 'EXITED:' \$EXIT_CODE; \
  openclaw system event --text 'Ralph loop <name> finished (exit \$EXIT_CODE) in <project-dir>' --mode now; \
  sleep 999999"

Parallel Ralph Loops

tmux -S ~/.tmux/sock new -d -s <name> "cd <project-dir> && \
  PATH=/opt/homebrew/bin:\$PATH ralphy --codex --parallel --prd PRD.md; \
  EXIT_CODE=\$?; echo 'EXITED:' \$EXIT_CODE; \
  openclaw system event --text 'Ralph parallel <name> finished (exit \$EXIT_CODE)' --mode now; \
  sleep 999999"

Command Anatomy

Every tmux coding session follows this pattern:

1. Stable socket: -S ~/.tmux/sock (survives macOS /tmp cleanup)
2. Named session: -s <name> (human-readable, used for monitoring)
3. PATH fix: PATH=/opt/homebrew/bin:$PATH (Ralph/Codex need Homebrew binaries)
4. The agent command: codex exec --full-auto or ralphy --codex
5. Completion hook: Captures exit code, fires openclaw system event for instant notification
6. Sleep tail: sleep 999999 keeps the shell alive so output remains readable

Monitoring

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

# Check recent output
tmux -S ~/.tmux/sock capture-pane -t <name> -p | tail -20

# Check if session exists
tmux -S ~/.tmux/sock has-session -t <name> 2>/dev/null && echo "alive" || echo "dead"

# Kill a completed session
tmux -S ~/.tmux/sock kill-session -t <name>

When to Use Ralph vs Raw Codex

Scenario	Tool
Multi-step feature with PRD/checklist	ralphy --codex --prd PRD.md
Task that has stalled or failed before	ralphy --codex (auto-retry with fresh context)
Parallel independent tasks	ralphy --codex --parallel --prd PRD.md
Tiny focused fix, one-file change	codex exec --full-auto
Exploratory work, investigation	codex exec --full-auto

PRD Format

Ralph tracks completion via markdown checklists:

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

Ralph restarts the agent with fresh context each iteration. The agent picks up where it left off via files + git history. Include test-first instructions in task prompts for deterministic validation.

Post-Completion Verification

Before declaring success or failure, always check:

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

Ralph can mark PRD tasks as done even when codex fails silently. Verify via git, not PRD checkboxes.

Logging

After starting any long-running session, log it in daily notes (memory/YYYY-MM-DD.md) under "Active Long-Running Processes" with the session name and original command. This ensures context survives compaction and heartbeat monitoring can track/restart sessions.

Troubleshooting

• "Failed to refresh token" in ~/.codex/log/codex-tui.log → run codex auth login
• Agent reads files and exits → wrap in Ralph loop (auto-retry solves this)
• API rate limits (429s) with parallel agents → reduce parallelism or stagger starts
• Session died → restart with same command from daily notes