tmux-delegation

Multi-Harness tmux Delegation

Manage and delegate tasks to coding agents running inside tmux panes and windows. Designed for orchestrators (like Hermes, OpenCode, Pi, or Tech Lead profiles) that decompose work and delegate execution to bounded workers across diverse CLI harnesses: Codex CLI, Claude Code, Pi CLI, OpenCode, cursor-agent, or standard shells.

The core rule: The orchestrator plans, routes, and audits; the worker implements in an isolated tmux pane.

---

1. Pane Selection & Allocation (Anti-Contamination Rule)

Never reuse a pane that has active context or conversation history from a different task or repository. Context pollution corrupts reasoning.

Inventory Existing Panes

# Check all windows and panes in the session with command, cwd, and alive status
tmux list-panes -t "$TMUX_SESSION" -F \
  '#{window_index}:#{pane_index} #{pane_id} #{pane_current_command} #{pane_dead} #{pane_current_path}'

Pane Selection Matrix

Pane Condition	Suitable?	Action
Target harness running, same repo, idle prompt	YES	Reset context if needed (/clear in Claude/Codex) and proceed.
Target harness running, different repo	NO	Open a new window. Do not contaminate active context.
Empty shell (zsh/bash), same repo	YES	Boot the desired agent directly in this pane.
Empty shell, different directory	YES	cd /abs/repo/path then launch agent.
All panes occupied or conflicting	NO	Spawn a fresh window.

Spawning a Fresh Pane

When creating a new window, always specify the absolute working directory:

# 1. Create window with explicit cwd
tmux new-window -t "$TMUX_SESSION" -n "$TASK_SLUG" -c "$ABS_REPO_PATH"

# 2. Launch the target harness
# Claude Code:
tmux send-keys -t "$TMUX_SESSION:$WINDOW_INDEX" "claude --dangerously-skip-permissions" Enter

# Codex CLI:
tmux send-keys -t "$TMUX_SESSION:$WINDOW_INDEX" "codex" Enter

# Pi CLI:
tmux send-keys -t "$TMUX_SESSION:$WINDOW_INDEX" "pi" Enter

# OpenCode CLI:
tmux send-keys -t "$TMUX_SESSION:$WINDOW_INDEX" "opencode" Enter

# cursor-agent CLI:
tmux send-keys -t "$TMUX_SESSION:$WINDOW_INDEX" "cursor-agent" Enter