From fac694fc035a5b0c19f930ba031c26b21786a1e9 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 3 Jan 2026 19:45:11 +0000
Subject: [PATCH] docs(skills): add parallel Codex orchestration learnings

- coding-agent: document --yolo flag, git worktree + tmux pattern
- tmux: add section on orchestrating coding agents in parallel

Learnings from running 5 parallel Codex sessions to analyze GitHub issues
---
 skills/coding-agent/SKILL.md | 53 +++++++++++++++++++++++++++++++++++-
 skills/tmux/SKILL.md         | 35 ++++++++++++++++++++++++
 2 files changed, 87 insertions(+), 1 deletion(-)

diff --git a/skills/coding-agent/SKILL.md b/skills/coding-agent/SKILL.md
index f52f74f89..05ba08734 100644
--- a/skills/coding-agent/SKILL.md
+++ b/skills/coding-agent/SKILL.md
@@ -41,9 +41,15 @@ process action:kill sessionId:XXX
 
 **Model:** `gpt-5.2-codex` is the default (set in ~/.codex/config.toml)
 
-### Building/Creating (use --full-auto)
+### Building/Creating (use --full-auto or --yolo)
 ```bash
+# --full-auto: sandboxed but auto-approves in workspace
 bash workdir:~/project background:true command:"codex exec --full-auto \"Build a snake game with dark theme\""
+
+# --yolo: NO sandbox, NO approvals (fastest, most dangerous)
+bash workdir:~/project background:true command:"codex --yolo \"Build a snake game with dark theme\""
+
+# Note: --yolo is a shortcut for --dangerously-bypass-approvals-and-sandbox
 ```
 
 ### Reviewing PRs (vanilla, no flags)
@@ -144,6 +150,51 @@ Use the tmux skill for interactive coding sessions (always, except very simple o
 
 ---
 
+## Parallel Issue Fixing with git worktrees + tmux
+
+For fixing multiple issues in parallel, use git worktrees (isolated branches) + tmux sessions:
+
+```bash
+# 1. Clone repo to temp location
+cd /tmp && git clone git@github.com:user/repo.git repo-worktrees
+cd repo-worktrees
+
+# 2. Create worktrees for each issue (isolated branches!)
+git worktree add -b fix/issue-78 /tmp/issue-78 main
+git worktree add -b fix/issue-99 /tmp/issue-99 main
+
+# 3. Set up tmux sessions
+SOCKET="${TMPDIR:-/tmp}/codex-fixes.sock"
+tmux -S "$SOCKET" new-session -d -s fix-78
+tmux -S "$SOCKET" new-session -d -s fix-99
+
+# 4. Launch Codex in each (after pnpm install!)
+tmux -S "$SOCKET" send-keys -t fix-78 "cd /tmp/issue-78 && pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'" Enter
+tmux -S "$SOCKET" send-keys -t fix-99 "cd /tmp/issue-99 && pnpm install && codex --yolo 'Fix issue #99: <description>. Commit and push.'" Enter
+
+# 5. Monitor progress
+tmux -S "$SOCKET" capture-pane -p -t fix-78 -S -30
+tmux -S "$SOCKET" capture-pane -p -t fix-99 -S -30
+
+# 6. Check if done (prompt returned)
+tmux -S "$SOCKET" capture-pane -p -t fix-78 -S -3 | grep -q "❯" && echo "Done!"
+
+# 7. Create PRs after fixes
+cd /tmp/issue-78 && git push -u origin fix/issue-78
+gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."
+
+# 8. Cleanup
+tmux -S "$SOCKET" kill-server
+git worktree remove /tmp/issue-78
+git worktree remove /tmp/issue-99
+```
+
+**Why worktrees?** Each Codex works in isolated branch, no conflicts. Can run 5+ parallel fixes!
+
+**Why tmux over bash background?** Codex is interactive — needs TTY for proper output. tmux provides persistent sessions with full history capture.
+
+---
+
 ## ⚠️ Rules
 
 1. **Respect tool choice** — if user asks for Codex, use Codex. NEVER offer to build it yourself!
diff --git a/skills/tmux/SKILL.md b/skills/tmux/SKILL.md
index 3393edb04..ca84cc636 100644
--- a/skills/tmux/SKILL.md
+++ b/skills/tmux/SKILL.md
@@ -65,6 +65,41 @@ To monitor:
 - tmux is supported on macOS/Linux. On Windows, use WSL and install tmux inside WSL.
 - This skill is gated to `darwin`/`linux` and requires `tmux` on PATH.
 
+## Orchestrating Coding Agents (Codex, Claude Code)
+
+tmux excels at running multiple coding agents in parallel:
+
+```bash
+SOCKET="${TMPDIR:-/tmp}/codex-army.sock"
+
+# Create multiple sessions
+for i in 1 2 3 4 5; do
+  tmux -S "$SOCKET" new-session -d -s "agent-$i"
+done
+
+# Launch agents in different workdirs
+tmux -S "$SOCKET" send-keys -t agent-1 "cd /tmp/project1 && codex --yolo 'Fix bug X'" Enter
+tmux -S "$SOCKET" send-keys -t agent-2 "cd /tmp/project2 && codex --yolo 'Fix bug Y'" Enter
+
+# Poll for completion (check if prompt returned)
+for sess in agent-1 agent-2; do
+  if tmux -S "$SOCKET" capture-pane -p -t "$sess" -S -3 | grep -q "❯"; then
+    echo "$sess: DONE"
+  else
+    echo "$sess: Running..."
+  fi
+done
+
+# Get full output from completed session
+tmux -S "$SOCKET" capture-pane -p -t agent-1 -S -500
+```
+
+**Tips:**
+- Use separate git worktrees for parallel fixes (no branch conflicts)
+- `pnpm install` first before running codex in fresh clones
+- Check for shell prompt (`❯` or `$`) to detect completion
+- Codex needs `--yolo` or `--full-auto` for non-interactive fixes
+
 ## Cleanup
 
 - Kill a session: `tmux -S "$SOCKET" kill-session -t "$SESSION"`.