tmux Orchestrator

A Claude Code skill for coordinating multiple AI coding agents (Claude Code + Codex) through tmux, with automatic task tracking, independent evaluation, and structured context management.

What This Does

If you use both Claude Code and OpenAI Codex CLI, this skill turns your main Claude Code session into a dispatcher that:

• Opens tmux panes and dispatches tasks to Codex workers (code) and Claude Code workers (browser verification)
• Tracks every task in persistent markdown files so nothing gets lost
• Runs an independent Evaluator loop on UI tasks to catch bugs before you review
• Manages worker context lifecycle (compact vs. handoff based on remaining context)
• Sends Telegram notifications on task completion (optional)
• Enforces file locking for parallel work without merge conflicts

Architecture

You (terminal)
  |
  v
Dispatcher (main Claude Code session)
  |
  |-- reads/writes --> task files (docs/agent-memory/tasks/YYYY-MM-DD.md)
  |-- reads/writes --> lock files (docs/agent-memory/LOCKS.md)
  |
  |-- tmux send-keys --> Codex pane 0 (code + tests + commit)
  |-- tmux send-keys --> Codex pane 1 (parallel task)
  |-- Agent tool -----> Claude Code evaluator (independent UI verification)
  |
  v
Notifications (git hook + Telegram + patrol script)

Key Design Decisions

Based on Anthropic's Harness Design for Long-Running Apps:

1. Generator-Evaluator Separation: Codex writes code, a separate Claude Code agent independently verifies UI changes. Self-evaluation tends toward leniency; independent evaluation catches real bugs.

2. Context Reset > Compaction: When a worker's context drops below 15%, it writes a structured handoff file and a fresh worker continues. Compaction degrades quality; reset preserves it.

3. Two Enters Rule: tmux send-keys requires exactly 2 Enters to submit a task to Codex/Claude Code (1st enters the input, 2nd submits). Pressure-tested on Codex v0.118+.

4. User Verification is Final: Even when the Evaluator passes, the user must explicitly approve before a task is marked complete. The Evaluator reduces issues reaching the user, it doesn't replace the user.

Prerequisites

• Claude Code CLI
• OpenAI Codex CLI (v0.118+)
• tmux
• Node.js 18+ (for Playwright verification)

Optional

• Telegram bot token (for notifications)
• Playwright (for headless UI verification)

Setup

1. Copy the skill file

# Create the skill directory
mkdir -p ~/.claude/skills/tmux-orchestrator

# Copy the skill
cp skill.md ~/.claude/skills/tmux-orchestrator/skill.md

2. Configure your project directory

Open skill.md and replace all occurrences of <YOUR_PROJECT_DIR> with your actual project path:

sed -i '' 's|<YOUR_PROJECT_DIR>|/path/to/your/project|g' ~/.claude/skills/tmux-orchestrator/skill.md

3. Configure Codex (recommended)

Add to ~/.codex/config.toml so Codex doesn't prompt for approval:

[projects."/path/to/your/project"]
trust_level = "trusted"
approval_policy = "never"
sandbox_mode = "danger-full-access"

4. Set up task tracking (optional but recommended)

mkdir -p /path/to/your/project/docs/agent-memory/tasks
mkdir -p /path/to/your/project/docs/agent-memory/signals

5. Set up Telegram notifications (optional)

See scripts/notify-telegram.sh for setup instructions.

6. Set up patrol script (optional)

See scripts/tmux-patrol.sh for background monitoring.

Usage

Start a Claude Code session and tell it:

You are a tmux dispatcher. Read the tmux-orchestrator skill and manage my project at /path/to/project.

Or simply describe your tasks — if the skill is installed, Claude Code will activate it when you mention dispatching, parallel workers, or tmux.

Common commands

You say	Dispatcher does
"Fix the login bug and add dark mode"	Opens 2 Codex panes, dispatches both in parallel
"s" or "status"	Reports all pane status + pending tasks
Any bug description	Immediately dispatches to a new pane

Task lifecycle

You describe a task
  -> Dispatcher writes to task file: - [ ] task | pane: P0
  -> Dispatches to Codex pane
  -> Codex completes + commits: - [x] task
  -> (If UI task) Evaluator independently verifies
  -> You confirm OK: - [✅] task

Customization

Notification method

Replace notify-telegram calls in the skill with your preferred notification tool (Slack, Discord, desktop notification, etc.).

Evaluator trigger

By default, the Evaluator only runs for UI tasks. Adjust the routing table in the "Evaluator Loop" section of skill.md to match your project's needs.

Context thresholds

The default context management tiers are:

• >30%: Normal operation
• 30-15%: Compact (sufficient for simple tasks)
• <15%: Force handoff + new pane

Adjust these based on your typical task complexity.

File Structure

tmux-orchestrator/
├── skill.md                    # Core skill (install to ~/.claude/skills/tmux-orchestrator/)
├── README.md
├── scripts/
│   ├── notify-telegram.sh      # Optional Telegram notification helper
│   └── tmux-patrol.sh          # Optional background pane monitor
└── templates/
    ├── task-file.md             # Daily task file template
    ├── handoff.md               # Context handoff template
    └── locks.md                 # File lock table template

How It Works (Detail)

Dispatcher Role

The dispatcher (your main Claude Code session) never writes code itself. It:

• Talks to you
• Opens/closes tmux panes
• Sends tasks via tmux send-keys
• Reads task files and pane output to track progress
• Reports status when you ask

Codex Worker Role

Each Codex pane:

• Receives a task with clear acceptance criteria
• Implements the fix/feature
• Runs TypeScript checks (tsc --noEmit)
• Runs related tests
• Runs Playwright verification (if UI change)
• Commits to the dev branch
• Sends notification

Evaluator Role (UI tasks only)

After Codex commits a UI change:

• Dispatcher spawns a Claude Code agent in the background
• Agent opens the page via browser automation (CDP)
• Tests edge cases, checks console errors, takes screenshots
• Reports PASS/FAIL back to dispatcher
• If FAIL: feedback goes to Codex for another attempt (up to 3 rounds)

File Locking

When multiple panes work in parallel:

• Each pane writes which files it will modify to LOCKS.md
• Before starting, a pane checks for conflicts
• If conflict: waits (checks every 2 min) instead of proceeding
• On completion: releases the lock

License

MIT