Coding Sessions

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 (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

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