imabusyman/dmux-workflows

dmux Workflows — parallel orchestration via tmux

Use tmux pane multiplexing for true parallel execution with integrated monitoring and log aggregation.

Prerequisites

• Windows: WSL 2 with Ubuntu + tmux installed, OR Git Bash / Cygwin with tmux.
• macOS / Linux: Native tmux (built-in or brew install tmux).
• Blaze.LlmGateway: Must be cloned into the WSL filesystem (not /mnt/c/, to avoid path-length issues).

When to use

• Orchestrator parallel path on Unix/Linux or WSL.
• You want integrated tmux monitoring (watch all agents in real time).
• You need true shell-based concurrency (vs. task queue abstraction).
• Agents write to separate log files and report completion via exit codes.

Architecture

tmux session: blaze-squad
├─ pane:0  [Conductor/Orchestrator] — orchestration logic
├─ pane:1  [Coder subagent 1]       — implement Provider X
├─ pane:2  [Coder subagent 2]       — implement Provider Y
├─ pane:3  [Tester subagent 1]      — test all providers
└─ pane:4  [Infra subagent 1]       — wire AppHost

All panes are visible; coordinator watches logs in real time.

Workflow

1. Initialize tmux session

# From repo root
tmux new-session -d -s blaze-squad -x 240 -y 60

# Create panes for each agent
tmux new-window -t blaze-squad -n conductor
tmux split-window -t blaze-squad -h  # splits conductor pane horizontally
tmux split-window -t blaze-squad -v  # splits vertically into more panes

2. Dispatch agents to panes

# Pane 0: Orchestrator runs the coordination loop
tmux send-keys -t blaze-squad:0 "pwsh ./scripts/orchestrator.ps1 --prd Docs/PRD/new-feature.md" Enter

# Pane 1: Coder agent on worktree A
tmux send-keys -t blaze-squad:1 "cd .worktrees/task-1 && coder-agent --task 'implement Provider X'" Enter

# Pane 2: Coder agent on worktree B
tmux send-keys -t blaze-squad:2 "cd .worktrees/task-2 && coder-agent --task 'implement Provider Y'" Enter

# ... etc for Tester, Infra

3. Monitor & aggregate

Conductor polls all panes for completion:

# Check exit code of pane 1 (blocks until done)
tmux capture-pane -t blaze-squad:1 -p
if [ $? -eq 0 ]; then echo "Pane 1 done"; fi

# Collect logs from all panes
for pane in 1 2 3 4; do
  echo "=== Pane $pane ===" >> aggregated.log
  tmux capture-pane -t blaze-squad:$pane -p >> aggregated.log
done

4. Cleanup

tmux kill-session -t blaze-squad

Agent handoff format (tmux-aware)

Each agent's handoff includes:

execution_env: tmux
tmux_pane: blaze-squad:1
log_file: Docs/squad/runs/<ts>/logs/pane-1.log
ready_signal: "echo AGENT_DONE >> $log_file && exit 0"
error_signal: "echo AGENT_BLOCKED >> $log_file && exit 1"

Agent logs exit code or a status string; Orchestrator reads it from the tmux pane.

Advantages

• Real-time visibility: All agents' output visible in one tmux window.
• No polling: tmux captures full stdout/stderr history.
• Cleanup: Kill the session to terminate all panes at once.

Limitations

• Windows: Requires WSL (or Git Bash/Cygwin with tmux).
• Path lengths: .worktrees/ must be short (WSL+Windows 260-char limit still applies).
• Log parsing: Agents must emit clear completion signals (exit codes or magic strings).

See also

• autonomous-agent-harness — cross-platform task queue alternative (no tmux).
• subagent-driven-development — structure subagent delegation.