Agent-Skills.md

Agent Skills: CODEX Coordinator - Ultra-Strict tmux Orchestration

Codex as coordinator for tmux multi-agent workflows. MANDATORY verification after EVERY command. Zero hallucination enforced through explicit checkpoints.

UncategorizedID: dbmcco/claude-agent-toolkit/orchestrating-tmux-codex

Repository

dbmcco/claude-agent-toolkit
dbmccoLicense: MIT
122

Install this agent skill to your local

pnpm dlx add-skill https://github.com/dbmcco/claude-agent-toolkit/tree/HEAD/skills/orchestrating-tmux-codex

Skill Files

Browse the full folder contents for orchestrating-tmux-codex.

Download Skill

Loading file tree…

skills/orchestrating-tmux-codex/SKILL.md

Skill Metadata

Name
orchestrating-tmux-codex
Description
Codex as coordinator for tmux multi-agent workflows. MANDATORY verification after EVERY command. Zero hallucination enforced through explicit checkpoints.

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.