multi-agent-shogun

multi-agent-shogun is a Bash and tmux-based multi-agent orchestration system designed with a Japanese feudal warrior hierarchy metaphor: Shogun (commander) receives user commands, Karo (manager) decomposes tasks, 7 Ashigaru (workers) execute implementation tasks in parallel, and Gunshi (strategist) handles analysis and evaluation — 10 AI agents collaborating in total.

The system's core design principle is zero coordination overhead — agents communicate through YAML files on disk, with inotifywait event-driven wakeups and flock file locking for race condition prevention. The orchestration process consumes zero API tokens, enabling simultaneous operation of 8 Opus-level agents under CLI flat-rate subscriptions without per-token billing concerns.

For CLI adaptation, the system builds a unified instruction template system (instructions/ directory) that auto-generates CLI-specific instruction files (CLAUDE.md, AGENTS.md, copilot-instructions.md, etc.) from three layers: shared rules, CLI-specific tool descriptions, and role definitions. The lib/cli_adapter.sh abstracts parameter differences across CLIs, enabling the same orchestration logic to uniformly support Claude Code, OpenAI Codex, GitHub Copilot, and Kimi Code.

The system features bottom-up skill discovery: Ashigaru automatically identify reusable patterns during task execution and propose them as skills, which become permanent after user approval and persist in the skills/ directory. A Memory MCP mechanism enables preference and context persistence across sessions. At runtime, dashboard.md and the dash command provide real-time progress views, and users can also remotely monitor and voice-command all agents via an Android companion app over SSH.

Architecture Overview#

User (The Lord)
     │
     ▼  Issue command
┌─────────────┐
│   SHOGUN    │  ← Receives command, delegates immediately
└──────┬──────┘
       │  YAML + tmux
┌──────▼──────┐
│    KARO     │  ← Assigns tasks to workers
└──────┬──────┘
       │
┌─┬─┬─┬─┴─┬─┬─┬─┬────────┐
│1│2│3│4│5│6│7│ GUNSHI │  ← 7 workers + 1 strategist
└─┴─┴─┴─┴─┴─┴─┴────────┘
   ASHIGARU      GUNSHI

Process Management & Communication#

• Carrier: tmux sessions + panes, each agent occupies a dedicated pane
• Session separation: shogun session (user interaction) vs multiagent session (Karo + 7×Ashigaru + Gunshi background panel)
• Message format: YAML files, flowing Shogun → queue/shogun_to_karo.yaml → Karo → each Ashigaru's inbox YAML
• Write safety: scripts/inbox_write.sh uses flock for file locking
• Consumer wakeup: scripts/inbox_watcher.sh uses inotifywait to listen for file events, triggering tmux send-keys to wake target agents

Quick Start#

Prerequisites: tmux, bash 4+, at least one AI CLI (Claude Code / Codex / Copilot / Kimi)

git clone https://github.com/yohey-w/multi-agent-shogun
cd multi-agent-shogun
bash first_setup.sh
source ~/.bashrc
claude --dangerously-skip-permissions
bash shutsujin_departure.sh

Windows (WSL2) users can download the ZIP and run install.bat as administrator to auto-configure WSL2 + Ubuntu.

Typical Use Cases#

• Parallel code generation: e.g., implementing multiple REST API endpoints simultaneously
• Batch research: multiple Ashigaru researching different topics in parallel
• Multi-CLI complementarity: assigning different tasks to different CLIs (Claude Code for tmux integration, Codex for sandbox execution, Copilot for GitHub integration)
• Remote/mobile command: SSH via Android app with voice input to monitor and command agent panels

Unconfirmed Information#

• Author yohey-w's identity and affiliation are not publicly disclosed
• Existence of a standalone documentation site is unconfirmed; GitHub README is the primary doc source
• Comparisons with LangGraph/CrewAI lack independent benchmark data
• Agent roles and counts are currently fixed; dynamic scaling support is unconfirmed
• Actual compatibility completeness for non-Claude Code CLIs remains to be verified