Coordinate multiple Claude Code agents through tmux sessions and YAML-driven task queues. A hierarchical command structure — Shogun, Karo, Ashigaru — keeps agents focused, parallel, and conflict-free.
# Command hierarchy ┌──────────┐ │ SHOGUN │ ← Project orchestrator └────┬─────┘ │ YAML task queues ┌────▼─────┐ │ KARO │ ← Task manager & distributor └────┬─────┘ │ YAML task assignments ┌───┬───┬──▼┬───┬───┬───┬───┐ │A1 │A2 │A3 │A4 │A5 │A6 │A7 │A8 │ ← Ashigaru workers └───┴───┴───┴───┴───┴───┴───┴───┘
What makes oopunsoosu different from running agents in separate terminals.
Run up to 8 agents simultaneously in tmux panes. Each agent operates in its own pane with dedicated task files, eliminating write conflicts between workers.
Tasks are defined and tracked as YAML files. Shogun writes to a queue, Karo distributes to per-worker files, Ashigaru reads and reports back. No polling — event-driven via tmux send-keys.
Built on tmux sessions with named windows and indexed panes. Monitor all agents at a glance, inspect output in real time, and intervene when needed — all from one terminal.
Inspired by feudal military organization. Shogun sets strategy, Karo manages task distribution and quality, Ashigaru execute. Clear chain of command prevents agents from stepping on each other.
Three steps to your first multi-agent session.
$ git clone https://github.com/kawagutt/multi-agent-shogun.git $ cd multi-agent-shogun
$ cp config/settings.yaml.example config/settings.yaml $ vim config/settings.yaml # Set language, agent count, etc.
$ bash shutsujin_departure.sh # Spawns tmux sessions: shogun (1 pane) + multiagent (up to 9 panes) # Shogun, Karo, and Ashigaru agents start automatically
The communication flow between agents.
Shogun writes high-level objectives. Karo picks them up and breaks them into subtasks for individual Ashigaru.
Each Ashigaru has a dedicated task file. No shared writes, no race conditions. Karo notifies workers via tmux send-keys.
Workers report back through dedicated report files. Karo aggregates results and updates the dashboard for human review.