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
CODEBLOCK0
Ralph Loop (preferred for multi-step work)
CODEBLOCK1
Parallel Ralph Loops
CODEBLOCK2
Command Anatomy
Every tmux coding session follows this pattern:
- 1. Stable socket:
-S ~/.tmux/sock (survives macOS /tmp cleanup) - 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-auto or INLINECODE7 - Completion hook: Captures exit code, fires
openclaw system event for instant notification - Sleep tail:
sleep 999999 keeps the shell alive so output remains readable
Monitoring
CODEBLOCK3
When to Use Ralph vs Raw Codex
| Scenario | Tool |
|---|
| Multi-step feature with PRD/checklist | INLINECODE10 |
| 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:
CODEBLOCK4
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? - INLINECODE16 — 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 → run INLINECODE19 - 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
编码会话
在持久化tmux会话中编排长时间运行的AI编码代理，并配备完成通知与健康监控功能。
为何选择tmux？
后台执行进程会在网关重启时终止。任何预期运行时间超过5分钟的编码代理都必须在tmux内运行。这是不可妥协的。
始终使用稳定套接字（~/.tmux/sock）——默认的/tmp套接字会被macOS清理。
快速入门
单一Codex任务
bash
tmux -S ~/.tmux/sock new -d -s <名称> cd <项目目录> && \
PATH=/opt/homebrew/bin:\$PATH codex exec --full-auto <任务描述>; \
EXITCODE=\$?; echo 已退出: \$EXITCODE; \
openclaw system event --text <名称> 已完成 (退出码 \$EXIT_CODE) 在 <项目目录> --mode now; \
sleep 999999
Ralph循环（多步骤工作首选）
bash
tmux -S ~/.tmux/sock new -d -s <名称> cd <项目目录> && \
PATH=/opt/homebrew/bin:\$PATH ralphy --codex --prd PRD.md; \
EXITCODE=\$?; echo 已退出: \$EXITCODE; \
openclaw system event --text Ralph循环 <名称> 已完成 (退出码 \$EXIT_CODE) 在 <项目目录> --mode now; \
sleep 999999
并行Ralph循环
bash
tmux -S ~/.tmux/sock new -d -s <名称> cd <项目目录> && \
PATH=/opt/homebrew/bin:\$PATH ralphy --codex --parallel --prd PRD.md; \
EXITCODE=\$?; echo 已退出: \$EXITCODE; \
openclaw system event --text Ralph并行 <名称> 已完成 (退出码 \$EXIT_CODE) --mode now; \
sleep 999999
命令结构解析
每个tmux编码会话遵循以下模式：
- 1. 稳定套接字： -S ~/.tmux/sock（避免macOS /tmp清理）
- 命名会话： -s <名称>（人类可读，用于监控）
- PATH修复： PATH=/opt/homebrew/bin:$PATH（Ralph/Codex需要Homebrew二进制文件）
- 代理命令： codex exec --full-auto 或 ralphy --codex
- 完成钩子： 捕获退出码，触发openclaw system event即时通知
- 休眠尾部： sleep 999999保持shell存活，使输出保持可读
监控
bash
列出所有会话
tmux -S ~/.tmux/sock list-sessions
查看最近输出
tmux -S ~/.tmux/sock capture-pane -t <名称> -p | tail -20
检查会话是否存在
tmux -S ~/.tmux/sock has-session -t <名称> 2>/dev/null && echo 存活 || echo 已终止
终止已完成会话
tmux -S ~/.tmux/sock kill-session -t <名称>
何时使用Ralph与原始Codex
| 场景 | 工具 |
|---|
| 带PRD/检查清单的多步骤功能 | ralphy --codex --prd PRD.md |
| 之前停滞或失败的任务 |
ralphy --codex（使用新上下文自动重试） |
| 并行独立任务 | ralphy --codex --parallel --prd PRD.md |
| 小型针对性修复，单文件更改 | codex exec --full-auto |
| 探索性工作、调查 | codex exec --full-auto |
PRD格式
Ralph通过Markdown检查清单追踪完成情况：
markdown
任务
- - [ ] 创建API端点
- [ ] 添加输入验证
- [ ] 编写测试
- [x] 已完成（Ralph跳过）
Ralph每次迭代使用新上下文重启代理。代理通过文件+Git历史记录从中断处继续。在任务提示中包含测试优先指令以实现确定性验证。
完成后的验证
在声明成功或失败之前，始终检查：
- 1. git log --oneline -3——代理是否提交了？
- git diff --stat——是否有未提交的更改？
- 读取tmux面板输出——实际发生了什么？
即使Codex静默失败，Ralph也可能将PRD任务标记为完成。通过Git验证，而非PRD复选框。
日志记录
启动任何长时间运行的会话后，在每日笔记（memory/YYYY-MM-DD.md）的活动中的长时间运行进程下记录会话名称和原始命令。这确保上下文在压缩后仍然存在，心跳监控可以追踪/重启会话。
故障排除
- - 刷新令牌失败 出现在 ~/.codex/log/codex-tui.log → 运行 codex auth login
- 代理读取文件后退出 → 包装在Ralph循环中（自动重试解决此问题）
- 并行代理的API速率限制（429） → 降低并行度或错开启动时间
- 会话终止 → 使用每日笔记中的相同命令重启
