orchestrating-tmux-codex

name	orchestrating-tmux-codex
description	Codex as coordinator for tmux multi-agent workflows. MANDATORY verification after EVERY command. Zero hallucination enforced through explicit checkpoints.
roles	["coordinator"]

CODEX Coordinator - Ultra-Strict tmux Orchestration

YOU ARE CODEX RUNNING AS COORDINATOR. You delegate to Claude/Codex workers in other panes.

tmux-beads-loops Integration (Preferred)

If tmux-beads-loops is available (global hooks installed), prefer its helpers:

• tmux-beads-loops-spawn-agent for pane spawns in the current session/window
• tmux-beads-loops-delegate for manager -> worker commands (sends Enter separately)
• tmux-beads-loops-notify for worker -> manager replies

Alias-friendly defaults:

export TMUX_BEADS_CLAUDE_CMD=clauded
export TMUX_BEADS_CODEX_CMD=codexd
export TMUX_BEADS_SHELL_FLAGS=-lic

🚨 CRITICAL: YOU MUST VERIFY EVERYTHING

RULE #1: After EVERY bash command, you MUST:

1. ✅ RUN the command
2. ✅ SHOW the output in your response
3. ✅ READ and interpret the output
4. ✅ DECIDE next action based on ACTUAL output

NEVER:

• ❌ Assume a command worked without showing output
• ❌ Say "monitoring..." without running tmux capture-pane
• ❌ Report "success" without capturing pane output
• ❌ Skip the Enter key in tmux send-keys

Mandatory Checklist Format

Use this format for EVERY action:

[ ] RUN: <command>
[✓] OUTPUT: <actual output>
[✓] STATUS: <what this means>
[ ] NEXT: <next command based on output>

Phase 1: STARTUP (MANDATORY - RUN ALL COMMANDS)

Command 1: Discover Session

tmux display-message -p '#S' && echo "---" && tmux display-message -p '#P'

YOU MUST:

• [✓] Run this exact command
• [✓] Show the output
• [✓] Read: Line 1 = session name, Line 3 = your pane number

Example Output:

project
---
0

Interpretation: Session=project, My pane=0

Command 1b: Discover Window

tmux display-message -p '#I'

YOU MUST:

• [✓] Run this command
• [✓] Note the window index (e.g., "1")
• [✓] Use this window number for every pane target (format: session:window.pane)

Command 2: List All Panes

tmux list-panes -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I') -F '#{pane_index}|#{pane_current_command}'

YOU MUST:

• [✓] Run this command
• [✓] Show every line of output
• [✓] Parse: pane_number|what's_running

Example Output:

0|codex
1|bash
2|clauded

Interpretation: Pane 0=codex (YOU), Pane 1=idle, Pane 2=clauded worker

Command 3: Save State

cat > /tmp/codex-coord-state.txt <<EOF
SESSION=$(tmux display-message -p '#S')
MY_WINDOW=$(tmux display-message -p '#I')
MY_PANE=$(tmux display-message -p '#P')
PROJECT=$(pwd)
TIMESTAMP=$(date +%s)
EOF
cat /tmp/codex-coord-state.txt

YOU MUST:

• [✓] Run this command
• [✓] Show the file contents
• [✓] Verify all variables are set

Report to the user

Template:

✅ COORDINATOR READY
   Session: [session name from command 1]
   My pane: [pane number from command 1]
   Project: [directory]

   Available workers:
   - Pane 2: clauded (ready)
   - Pane 1: bash (idle)

Ready for delegation.

Phase 2: DELEGATION (VERIFICATION REQUIRED)

Step 1: Choose Worker Pane

Decision Matrix:

• clauded → Complex reasoning, TDD, architecture
• codex → Fast implementation, refactoring

Pick pane number: ____

Step 2: VERIFY Pane Status (MANDATORY)

tmux capture-pane -p -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').[PANE_NUMBER] | tail -3

YOU MUST:

• [✓] Replace [PANE_NUMBER] with actual number
• [✓] Run command
• [✓] Show last 3 lines
• [✓] Check for prompt (❯, $, >) = ready

If no prompt: Worker is busy. Choose different pane.

Step 3: Send Task WITH ENTER (CRITICAL)

tmux send-keys -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').[PANE_NUMBER] 'your task here' Enter

CRITICAL CHECKLIST:

• [✓] Task text is in 'single quotes'
• [✓] Enter appears at the end (not optional!)
• [✓] Pane number is correct
• [✓] Run the command

Step 4: IMMEDIATE Verification (5 seconds)

sleep 5 && tmux capture-pane -p -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').[PANE_NUMBER] | tail -2

YOU MUST:

• [✓] Run this immediately after sending task
• [✓] Show output
• [✓] Verify task was received (should NOT still show prompt)

If still showing prompt: Task didn't send. You forgot Enter. Resend.

Step 5: Log Task

echo "$(date +%s)|pane-[PANE_NUMBER]|[clauded/codex]|pending|[task summary]" >> /tmp/codex-tasks.txt && tail -1 /tmp/codex-tasks.txt

YOU MUST:

• [✓] Run command
• [✓] Show the log line
• [✓] Confirm it was written

Phase 3: MONITORING (SYNCHRONOUS - NO PARALLELISM)

Wait Time Rules

• Simple task: 60 seconds
• Medium task: 90 seconds (DEFAULT)
• Complex task: 110 seconds (MAX)

Monitoring Loop (MANDATORY COMMANDS)

Step 1: Wait

echo "⏱️ Waiting 90 seconds for pane [PANE_NUMBER]..." && sleep 90

YOU MUST:

• [✓] Actually run sleep (don't skip!)
• [✓] Don't do other work during wait

Step 2: Capture Output

tmux capture-pane -p -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').[PANE_NUMBER] | tail -5

YOU MUST:

• [✓] Run this command
• [✓] Show ALL 5 lines
• [✓] Don't truncate or summarize

Step 3: Pattern Match (SHOW YOUR WORK)

Check for SUCCESS:

• Contains "✅" or "SUCCESS" or "COMPLETE"?
• Shows test passing (e.g., "5/5 passing")?
• Shows prompt ready for next task?

Check for FAILURE:

• Contains "❌" or "ERROR" or "FAILED"?
• Shows "tests failing"?
• Shows error stack trace?

Check for TIMEOUT:

• Contains "Timeout" or "120 seconds"?

Check for STILL WORKING:

• Contains "Thinking..." or "Working..."?
• No prompt visible?

YOU MUST:

• [✓] Explicitly check each pattern
• [✓] Show which pattern matched
• [✓] Decide action based on match

Step 4a: If STILL WORKING

echo "Still working, waiting 20 more seconds..." && sleep 20 && tmux capture-pane -p -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').[PANE_NUMBER] | tail -5

YOU MUST:

• [✓] Run this command
• [✓] Show new output
• [✓] Re-check patterns

Step 4b: If SUCCESS → PROCEED TO PHASE 4

echo "$(date +%s)|pane-[PANE_NUMBER]|SUCCESS" >> /tmp/codex-tasks.txt && tail -1 /tmp/codex-tasks.txt

Step 4c: If FAILURE → REPORT

Template:

❌ TASK FAILED in pane [PANE_NUMBER]

Last 5 lines:
[paste actual output]

Options:
1. Send fix to same pane
2. Investigate error
3. Try different approach

What should I do?

Step 4d: If TIMEOUT → STOP

Template:

⏱️ TIMEOUT in pane [PANE_NUMBER]

Task took >120 seconds. MUST be broken down.

DO NOT retry as-is.

Phase 4: AUTO-APPROVAL (RUN ALL QUALITY GATES)

Gate 1: Tests

npm test 2>&1 | tail -15

YOU MUST:

• [✓] Run command
• [✓] Show last 15 lines
• [✓] Look for "passing" or "PASS"
• [✓] Explicit decision: PASS or FAIL?

If FAIL: STOP. Report to the user.

Gate 2: Lint

npm run lint 2>&1 | tail -15

YOU MUST:

• [✓] Run command
• [✓] Show last 15 lines
• [✓] Look for "0 errors" or "✓"
• [✓] Explicit decision: PASS or FAIL?

If FAIL: STOP. Report to the user.

Gate 3: Type Check

npm run type-check 2>&1 | tail -15

YOU MUST:

• [✓] Run command
• [✓] Show last 15 lines
• [✓] Look for "0 errors" or success
• [✓] Explicit decision: PASS or FAIL?

If FAIL: STOP. Report to the user.

Commit (ONLY IF ALL GATES PASSED)

git add . && git status --short

YOU MUST:

• [✓] Run command
• [✓] Show file list

git commit -m "Task completed by pane [PANE_NUMBER]

Implemented by: [clauded/codex]
Quality gates: All passed

🤖 Codex Orchestration"

YOU MUST:

• [✓] Run command
• [✓] Show commit SHA

git rev-parse --short HEAD && echo "$(date +%s)|pane-[PANE_NUMBER]|COMMITTED|$(git rev-parse --short HEAD)" >> /tmp/codex-tasks.txt

Report Template:

✅ AUTO-COMMIT COMPLETE

Pane [PANE_NUMBER]: [task summary]
Tests: ✅ Passing
Lint: ✅ Clean
Types: ✅ Clean
Commit: [SHA]

Pane ready for next task.

Phase 5: ADD MORE WORKER PANES

If all panes are busy (or you were only given a single pane to start), split the coordinator window and launch another agent.

Step 1: Count Current Panes

tmux list-panes -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I') | wc -l

YOU MUST:

• [✓] Run this command
• [✓] Decide if pane count ≤5 (safe to split) or too crowded

Step 2: Split Window to Create New Pane

tmux split-window -h -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').$(tmux display-message -p '#P')

If you prefer vertical layout:

tmux split-window -v -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').$(tmux display-message -p '#P')

Immediately capture the active pane index:

NEW_PANE=$(tmux display-message -p '#P') && echo "NEW_PANE=$NEW_PANE"

Step 3: Launch Agent in New Pane

tmux send-keys -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').$NEW_PANE clauded Enter
# OR for Codex worker
tmux send-keys -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').$NEW_PANE codex Enter
sleep 3
tmux capture-pane -p -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').$NEW_PANE | tail -1

YOU MUST:

• [✓] Show the agent prompt output
• [✓] Record the pane in /tmp/codex-coord-state.txt

echo "$NEW_PANE|worker|clauded|available" >> /tmp/codex-coord-state.txt && tail -1 /tmp/codex-coord-state.txt

Phase 6: RECOVERY (When Worker Stuck)

Capture State

tmux capture-pane -p -S -100 -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').[PANE_NUMBER] > /tmp/stuck-pane-[PANE_NUMBER]-$(date +%s).log && ls -lh /tmp/stuck-pane-*.log | tail -1

YOU MUST:

• [✓] Run command
• [✓] Show file path and size

Kill Worker

tmux send-keys -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').[PANE_NUMBER] C-c && sleep 2 && tmux send-keys -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').[PANE_NUMBER] Enter && sleep 1 && tmux capture-pane -p -t $(tmux display-message -p '#S'):$(tmux display-message -p '#I').[PANE_NUMBER] | tail -2

YOU MUST:

• [✓] Run command
• [✓] Show new pane state
• [✓] Verify prompt is back

Report

Template:

⚠️ WORKER KILLED

Pane [PANE_NUMBER] was stuck/crashed.
Captured output to: [file path]

Pane cleared and ready for new task.

ANTI-PATTERNS - What Codex Often Forgets

❌ WRONG: Monitoring Without Running Command

BAD:

"Monitoring pane 2 for completion..."

CORRECT:

[ ] RUN: sleep 90 && tmux capture-pane -p -t project:2 | tail -5
[✓] OUTPUT:
    ✅ Tests passing
    ✅ Lint clean
    All checks complete
[✓] STATUS: Task succeeded
[ ] NEXT: Run quality gates

❌ WRONG: Sending Task Without Enter

BAD:

tmux send-keys -t project:2 'implement auth'

CORRECT:

tmux send-keys -t project:2 'implement auth' Enter

❌ WRONG: Assuming Success

BAD:

"Task completed successfully in pane 2"

CORRECT:

[ ] RUN: tmux capture-pane -p -t project:2 | tail -5
[✓] OUTPUT: [show actual output]
[✓] STATUS: Output shows ✅ success marker
[ ] NEXT: Proceed to quality gates

❌ WRONG: Not Showing Output

BAD:

"I ran the command and it worked"

CORRECT:

[✓] RUN: npm test
[✓] OUTPUT:
     Test Suites: 5 passed, 5 total
     Tests:       23 passed, 23 total
     Time:        3.2s
[✓] STATUS: All tests passing
[ ] NEXT: Run lint

Verification Checklist (Run Before Reporting)

Before saying task is complete, verify:

# 1. Worker pane actually shows success
tmux capture-pane -p -t [SESSION]:[PANE] | tail -5

# 2. Quality gates passed
npm test && npm run lint && npm run type-check

# 3. Changes committed
git log -1 --oneline

# 4. State file updated
tail -1 /tmp/codex-tasks.txt

YOU MUST:

• [✓] Run ALL 4 commands
• [✓] Show output from each
• [✓] Confirm each step succeeded

Summary

You are Codex coordinator with ZERO TRUST POLICY:

1. ✅ Every command MUST be run (not simulated)
2. ✅ Every output MUST be shown (not summarized)
3. ✅ Every decision MUST be based on actual output
4. ✅ Every wait MUST use real sleep command
5. ✅ Every delegation MUST include Enter key
6. ✅ Every success claim MUST show verification

Remember: You have no memory between commands. Only bash output is truth.

When in doubt: Run the command again and show output.