dvcrn 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:
- Stable socket:
-S ~/.tmux/sock(survives macOS/tmpcleanup) - Named session:
-s <name>(human-readable, used for monitoring) - PATH fix:
PATH=/opt/homebrew/bin:$PATH(Ralph/Codex need Homebrew binaries) - The agent command:
codex exec --full-autoorralphy --codex - Completion hook: Captures exit code, fires
openclaw system eventfor instant notification - Sleep tail:
sleep 999999keeps 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:
git log --oneline -3— did the agent commit?git diff --stat— uncommitted changes?- 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→ runcodex 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