Community Plugin: /dispatch — Parallel task dispatcher across tmux sessions

What

Open-source plugin that dispatches tasks in parallel across multiple Claude Code sessions running in tmux. One coordinator session distributes work to N worker sessions, monitors completion, and auto-reassigns.

Repo: https://github.com/felmarv/-claude-dispatch

Why

Some workloads are embarrassingly parallel — research across multiple topics, batch document generation, multi-market analysis. Running them sequentially wastes time. This plugin turns 13 hours of sequential work into 3 hours with 4 workers.

How it works

1. User writes a task file: ID|TYPE|NAME|OUTPUT_PATH|INSTRUCTION
2. /dispatch run tasks.txt --workers 4 launches the dispatcher
3. Bash script runs in background, monitoring every 60s:

• Detects completion via file existence (more reliable than screen scraping)
• Auto-injects "no subagents for web search" (they don't inherit bypassPermissions)
• Sends automatic Enter after paste to resolve "Pasted text" buffer issue
• Watchdog detects stuck workers (15 min without screen change → auto-unblock)
• Supports task dependencies (DAG)

1. /dispatch status shows progress, /dispatch retry 5 retries failed tasks

Born from real usage

Built and battle-tested dispatching 13 research tasks (6 Mexican states + 6 countries + 1 consolidated report) on a Mac Mini server running 24/7. 11 bugs found and documented with root causes and solutions.

Key technical learnings for the community

• Subagents don't inherit bypassPermissions — web search gets blocked. Workaround: inject "no subagents" in every instruction.
• tmux send-keys with long text creates "Pasted text" that doesn't auto-execute. Fix: sleep 3 && tmux send-keys Enter after every send.
• Idle detection via screen scraping is fragile — completed task output contains activity keywords ("Writing", "Bash") that make the worker look busy. Fix: only check the very last line for ❯.
• Watchdog is essential — without it, stuck workers go undetected for hours. Compare captures every cycle, alert after 15 min of no change.

Installation

git clone https://github.com/felmarv/-claude-dispatch.git ~/plugins/dispatch
cp ~/plugins/dispatch/commands/dispatch.md ~/.claude/commands/
# /dispatch is now available — no restart needed

Requirements: macOS, tmux, Claude Code CLI, ~300MB RAM per worker.

Hope this helps others who want to parallelize their Claude Code workflows!