multi-agent-shogun

Multi-Agent Orchestration System for Claude Code

One command. Eight AI agents working in parallel.

English | Japanese / 日本語

---

What is this?

multi-agent-shogun is a system that runs multiple Claude Code instances simultaneously, organized like a feudal Japanese army.

Why use this?

• Give one command, get 8 AI workers executing in parallel
• No waiting - you can keep giving commands while tasks run in background
• AI remembers your preferences across sessions (Memory MCP)
• Real-time progress tracking via dashboard

        You (The Lord)
             │
             ▼ Give orders
      ┌─────────────┐
      │   SHOGUN    │  ← Receives your command, delegates immediately
      └──────┬──────┘
             │ YAML files + tmux
      ┌──────▼──────┐
      │    KARO     │  ← Distributes tasks to workers
      └──────┬──────┘
             │
    ┌─┬─┬─┬─┴─┬─┬─┬─┐
    │1│2│3│4│5│6│7│8│  ← 8 workers execute in parallel
    └─┴─┴─┴─┴─┴─┴─┴─┘
        ASHIGARU

---

🚀 Quick Start

🪟 Windows Users (Most Common)

Step 1	📥 Download this repository Download ZIP and extract to C:\tools\multi-agent-shogun Or use git: git clone https://github.com/yohey-w/multi-agent-shogun.git C:\tools\multi-agent-shogun
Step 2	🖱️ Double-click install.bat That's it! The installer handles everything automatically.
Step 3	✅ Done! 10 AI agents are now running.

📅 Daily Startup (After First Install)

Open Ubuntu terminal (WSL), navigate to your project directory, and run:

# Navigate to your project directory, then launch
cd /mnt/c/Users/you/my-project
/mnt/c/tools/multi-agent-shogun/shutsujin_departure.sh

# Or specify the project directory with -p
/mnt/c/tools/multi-agent-shogun/shutsujin_departure.sh -p /mnt/c/Users/you/my-project

---

🐧 Linux / Mac Users (Click to expand)

First-Time Setup

# 1. Clone the repository
git clone https://github.com/yohey-w/multi-agent-shogun.git ~/multi-agent-shogun
cd ~/multi-agent-shogun

# 2. Make scripts executable
chmod +x *.sh

# 3. Run first-time setup
./first_setup.sh

Daily Startup

# Navigate to your project directory, then launch
cd ~/my-project
~/multi-agent-shogun/shutsujin_departure.sh

# Or specify the project directory with -p
~/multi-agent-shogun/shutsujin_departure.sh -p ~/my-project

---

❓ What is WSL2? Why do I need it? (Click to expand)

About WSL2

WSL2 (Windows Subsystem for Linux) lets you run Linux inside Windows. This system uses tmux (a Linux tool) to manage multiple AI agents, so WSL2 is required on Windows.

Don't have WSL2 yet?

No problem! When you run install.bat, it will:

1. Check if WSL2 is installed
2. If not, show you exactly how to install it
3. Guide you through the entire process

Quick install command (run in PowerShell as Administrator):

wsl --install

Then restart your computer and run install.bat again.

---

📋 Script Reference (Click to expand)

Script	Purpose	When to Run
install.bat	Windows: First-time setup (runs first_setup.sh via WSL)	First time only
first_setup.sh	Installs tmux, Node.js, Claude Code CLI	First time only
shutsujin_departure.sh	Creates tmux sessions + starts Claude Code + loads instructions	Every day

What install.bat does automatically:

• ✅ Checks if WSL2 is installed
• ✅ Opens Ubuntu and runs first_setup.sh
• ✅ Installs tmux, Node.js, and Claude Code CLI
• ✅ Creates necessary directories

What shutsujin_departure.sh does:

• ✅ Creates tmux sessions (shogun + multiagent)
• ✅ Launches Claude Code on all 10 agents
• ✅ Automatically loads instruction files for each agent
• ✅ Resets queue files for a fresh start
• ✅ Sets all panes' working directory to the target project (launcher mode)

After running, all agents are ready to receive commands immediately!

---

🔧 Prerequisites (for manual setup) (Click to expand)

If you prefer to install dependencies manually:

Requirement	How to install	Notes
WSL2 + Ubuntu	wsl --install in PowerShell	Windows only
tmux	sudo apt install tmux	Terminal multiplexer
Node.js v20+	nvm install 20	Required for Claude Code CLI
Claude Code CLI	npm install -g @anthropic-ai/claude-code	Anthropic's official CLI

---

✅ What Happens After Setup

After running either option, 10 AI agents will start automatically:

Agent	Role	Quantity
🏯 Shogun	Commander - receives your orders	1
📋 Karo	Manager - distributes tasks	1
⚔️ Ashigaru	Workers - execute tasks in parallel	8

You'll see tmux sessions created:

• shogun - Connect here to give commands
• multiagent - Workers running in background

---

🚀 Launcher Mode (Use with Any Project)

multi-agent-shogun can be installed in a fixed location and launched from any project directory.

How It Works

Variable	Meaning	Auto-set
SHOGUN_HOME	Tool installation directory	Resolved from script location
PROJECT_DIR	Target project directory	Current directory, or specified with -p
PROJECT_ID	Resolved project identifier	From config/projects.yaml path match, else basename(PROJECT_DIR)
DASHBOARD_PATH	Active dashboard file	$SHOGUN_HOME/dashboards/{project_id}/dashboard.md

• All tmux panes' working directory is set to PROJECT_DIR
• System files (queue/, config/, etc.) are referenced from SHOGUN_HOME
• Dashboard is initialized per project at dashboards/{project_id}/dashboard.md
• SHOGUN_HOME/dashboard.md remains as a backward-compatible alias to the active project dashboard
• When SHOGUN_HOME == PROJECT_DIR, it works the same as before (backward compatible)

How to Launch

# Method 1: Navigate to your project, then launch
cd ~/my-app
~/tools/multi-agent-shogun-Fe-wind/shutsujin_departure.sh

# Method 2: Specify with -p flag (from anywhere)
~/tools/multi-agent-shogun-Fe-wind/shutsujin_departure.sh -p ~/my-app

# Set up an alias for convenience (~/.bashrc)
alias shogun='~/tools/multi-agent-shogun-Fe-wind/shutsujin_departure.sh'
# → cd ~/my-app && shogun

After Launch

SHOGUN_HOME (~/tools/multi-agent-shogun-Fe-wind/)     PROJECT_DIR (~/my-app/)
├── queue/          ← System communication    ├── src/          ← Ashigaru work here
├── config/         ← Settings                ├── package.json
├── instructions/   ← Agent instructions      └── ...
├── dashboards/
│   └── my-app/dashboard.md  ← Project dashboard
├── dashboard.md    ← Alias to active project dashboard (compat)
└── ...

---

📖 Basic Usage

Step 1: Connect to Shogun

After running shutsujin_departure.sh, all agents automatically load their instructions and are ready to work.

Open a new terminal and connect to the Shogun:

tmux attach-session -t shogun

Step 2: Give Your First Order

The Shogun is already initialized! Just give your command:

Investigate the top 5 JavaScript frameworks and create a comparison table.

The Shogun will:

1. Write the task to a YAML file
2. Notify the Karo (manager)
3. Return control to you immediately (you don't have to wait!)

Meanwhile, the Karo distributes the work to Ashigaru workers who execute in parallel.

Step 3: Check Progress

Open the project dashboard in your editor to see real-time status:

cat "$SHOGUN_HOME/dashboards/$PROJECT_ID/dashboard.md"
# Legacy-compatible path (points to active project)
cat "$SHOGUN_HOME/dashboard.md"

## In Progress
| Worker | Task | Status |
|--------|------|--------|
| Ashigaru 1 | React research | Running |
| Ashigaru 2 | Vue research | Running |
| Ashigaru 3 | Angular research | Done |

---

✨ Key Features

⚡ 1. Parallel Execution

One command can spawn up to 8 parallel tasks:

You: "Research 5 MCP servers"
→ 5 Ashigaru start researching simultaneously
→ Results ready in minutes, not hours

🔄 2. Non-Blocking Workflow

The Shogun delegates immediately and returns control to you:

You: Give order → Shogun: Delegates → You: Can give next order immediately
                                           ↓
                         Workers: Execute in background
                                           ↓
                         Karo updates dashboard
                                           ↓
                         Karo notifies Shogun on completion
                                           ↓
                         Dashboard: Shows results / Shogun can relay status

You never have to wait for long tasks to complete.

🧠 3. Memory Across Sessions (Memory MCP)

The AI remembers your preferences:

Session 1: You say "I prefer simple solutions"
           → Saved to Memory MCP

Session 2: AI reads memory at startup
           → Won't suggest over-engineered solutions

📡 4. Event-Driven (No Polling)

Agents communicate via YAML files and wake each other with tmux send-keys. No API calls are wasted on polling loops.

📸 5. Screenshot Support

VSCode's Claude Code extension lets you paste screenshots to explain issues. This CLI system brings the same capability:

# Configure your screenshot folder in config/settings.yaml
screenshot:
  path: "/mnt/c/Users/YourName/Pictures/Screenshots"

# Then just tell the Shogun:
You: "Check the latest screenshot"
You: "Look at the last 2 screenshots"
→ AI reads and analyzes your screenshots instantly

💡 Windows Tip: Press Win + Shift + S to take a screenshot. Configure the save location to match your settings.yaml path for seamless integration.

Perfect for:

• Explaining UI bugs visually
• Showing error messages
• Comparing before/after states

🧠 Model Configuration

Agent	Model	Thinking	Reason
Shogun	Opus	Disabled	Delegation & dashboard updates don't need deep reasoning
Karo	Default	Enabled	Task distribution requires careful judgment
Ashigaru	Default	Enabled	Actual implementation needs full capabilities

The Shogun uses MAX_THINKING_TOKENS=0 to disable extended thinking, reducing latency and cost while maintaining Opus-level judgment for high-level decisions.

📁 Context Management

The system uses a three-layer context structure for efficient knowledge sharing:

Layer	Location	Purpose
Memory MCP	memory/shogun_memory.jsonl	Persistent memory across sessions (preferences, decisions)
Global	memory/global_context.md	System-wide settings, user preferences
Project	context/{project}.md	Project-specific knowledge and state

This design allows:

• Any Ashigaru to pick up work on any project
• Consistent context across agent switches
• Clear separation of concerns
• Knowledge persistence across sessions

Universal Context Template

All projects use the same 7-section template:

Section	Purpose
What	Brief description of the project
Why	Goals and success criteria
Who	Stakeholders and responsibilities
Constraints	Deadlines, budget, limitations
Current State	Progress, next actions, blockers
Decisions	Decision log with rationale
Notes	Free-form notes and insights

This standardized structure ensures:

• Quick onboarding for any agent
• Consistent information across all projects
• Easy handoffs between Ashigaru workers

🛠️ Skills

Skills are not included in this repository by default. As you use the system, skill candidates will appear in dashboard.md. Review and approve them to grow your personal skill library.

---

🏛️ Design Philosophy

Why Hierarchical Structure?

The Shogun → Karo → Ashigaru hierarchy exists for:

1. Immediate Response: Shogun delegates instantly and returns control to you
2. Parallel Execution: Karo distributes to multiple Ashigaru simultaneously
3. Separation of Concerns: Shogun decides "what", Karo decides "who"

Why YAML + send-keys?

• YAML files: Structured communication that survives agent restarts
• send-keys: Event-driven wakeups (no polling = no wasted API calls)
• No direct calls: Agents can't interrupt each other or your input

Why Only Karo Updates Dashboard?

• Single responsibility: One writer = no conflicts
• Information hub: Karo receives all reports, knows the full picture
• Consistency: All updates go through one quality gate

How Skills Work

Skills (.claude/commands/) are not committed to this repository by design.

Why?

• Each user's workflow is different
• Skills should grow organically based on your needs
• No one-size-fits-all solution

How to create new skills:

1. Ashigaru report "skill candidates" when they notice repeatable patterns
2. Candidates appear in dashboard.md under "Skill Candidates"
3. You review and approve (or reject)
4. Approved skills are created by Karo

This keeps skills user-driven — only what you find useful gets added.

---

🔌 MCP Setup Guide

MCP (Model Context Protocol) servers extend Claude's capabilities. Here's how to set them up:

What is MCP?

MCP servers give Claude access to external tools:

• Notion MCP → Read/write Notion pages
• GitHub MCP → Create PRs, manage issues
• Memory MCP → Remember things across sessions

Installing MCP Servers

Run these commands to add MCP servers:

# 1. Notion - Connect to your Notion workspace
claude mcp add notion -e NOTION_TOKEN=your_token_here -- npx -y @notionhq/notion-mcp-server

# 2. Playwright - Browser automation
claude mcp add playwright -- npx @playwright/mcp@latest
# Note: Run `npx playwright install chromium` first

# 3. GitHub - Repository operations
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=your_pat_here -- npx -y @modelcontextprotocol/server-github

# 4. Sequential Thinking - Step-by-step reasoning for complex problems
claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking

# 5. Memory - Long-term memory across sessions (Recommended!)
claude mcp add memory -e MEMORY_FILE_PATH="$PWD/memory/shogun_memory.jsonl" -- npx -y @modelcontextprotocol/server-memory

Verify Installation

claude mcp list

You should see all servers with "Connected" status.

---

🌍 Real-World Use Cases

Example 1: Research Task

You: "Research the top 5 AI coding assistants and compare them"

What happens:
1. Shogun delegates to Karo
2. Karo assigns:
   - Ashigaru 1: Research GitHub Copilot
   - Ashigaru 2: Research Cursor
   - Ashigaru 3: Research Claude Code
   - Ashigaru 4: Research Codeium
   - Ashigaru 5: Research Amazon CodeWhisperer
3. All 5 research simultaneously
4. Results compiled in dashboard.md

Example 2: PoC Preparation

You: "Prepare a PoC for the project in this Notion page: [URL]"

What happens:
1. Karo fetches Notion content via MCP
2. Ashigaru 2: Lists items to clarify
3. Ashigaru 3: Researches technical feasibility
4. Ashigaru 4: Creates PoC plan document
5. All results in dashboard.md, ready for your meeting

---

⚙️ Configuration

Language Setting

Edit config/settings.yaml:

language: ja   # Japanese only
language: en   # Japanese + English translation

---

🛠️ Advanced Usage

Script Architecture (Click to expand)

┌─────────────────────────────────────────────────────────────────────┐
│                      FIRST-TIME SETUP (Run Once)                    │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  install.bat (Windows)                                              │
│      │                                                              │
│      └──▶ first_setup.sh (via WSL)                                  │
│                │                                                    │
│                ├── Check/Install tmux                               │
│                ├── Check/Install Node.js v20+ (via nvm)             │
│                └── Check/Install Claude Code CLI                    │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│                      DAILY STARTUP (Run Every Day)                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  shutsujin_departure.sh                                             │
│      │                                                              │
│      ├──▶ Create tmux sessions                                      │
│      │         • "shogun" session (1 pane)                          │
│      │         • "multiagent" session (9 panes, 3x3 grid)           │
│      │                                                              │
│      ├──▶ Reset queue files and dashboard                           │
│      │                                                              │
│      └──▶ Launch Claude Code on all agents                          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

shutsujin_departure.sh Options (Click to expand)

# Default: Launch with current directory as the target project
cd ~/my-project && ~/tools/multi-agent-shogun-Fe-wind/shutsujin_departure.sh

# Specify project directory with -p
~/tools/multi-agent-shogun-Fe-wind/shutsujin_departure.sh -p ~/my-project

# Session setup only (without launching Claude Code)
./shutsujin_departure.sh -s
./shutsujin_departure.sh --setup-only

# Full startup + open Windows Terminal tabs
./shutsujin_departure.sh -t
./shutsujin_departure.sh --terminal

# Show help
./shutsujin_departure.sh -h
./shutsujin_departure.sh --help

Directory Variables:

Variable	Meaning	Example
SHOGUN_HOME	Tool installation directory	~/tools/multi-agent-shogun-Fe-wind
PROJECT_DIR	Target project directory	/home/user/my-app
PROJECT_ID	Resolved project identifier	my-app
DASHBOARD_PATH	Active dashboard path	~/tools/multi-agent-shogun-Fe-wind/dashboards/my-app/dashboard.md

System files (queue/, config/, instructions/, etc.) live in SHOGUN_HOME, while actual coding work happens in PROJECT_DIR.

Common Workflows (Click to expand)

Normal Daily Usage:

cd ~/my-project
~/tools/multi-agent-shogun-Fe-wind/shutsujin_departure.sh  # Start everything
tmux attach-session -t shogun                       # Connect to give commands

Debug Mode (manual control):

~/tools/multi-agent-shogun-Fe-wind/shutsujin_departure.sh -s  # Create sessions only

# Manually start Claude Code on specific agents
tmux send-keys -t shogun:0 'claude --dangerously-skip-permissions' Enter
tmux send-keys -t multiagent:0.0 'claude --dangerously-skip-permissions' Enter

Restart After Crash:

# Kill existing sessions
tmux kill-session -t shogun
tmux kill-session -t multiagent

# Start fresh
cd ~/my-project
~/tools/multi-agent-shogun-Fe-wind/shutsujin_departure.sh

---

📁 File Structure

Click to expand file structure

multi-agent-shogun/
│
│  ┌─────────────────── SETUP SCRIPTS ───────────────────┐
├── install.bat               # Windows: First-time setup
├── first_setup.sh            # Ubuntu/Mac: First-time setup
├── shutsujin_departure.sh    # Daily startup (auto-loads instructions)
│  └────────────────────────────────────────────────────┘
│
├── instructions/             # Agent instruction files
│   ├── shogun.md             # Commander instructions
│   ├── karo.md               # Manager instructions
│   └── ashigaru.md           # Worker instructions
│
├── config/
│   └── settings.yaml         # Language and other settings
│
├── queue/                    # Communication files
│   ├── shogun_to_karo.yaml   # Commands from Shogun to Karo
│   ├── karo_to_shogun.yaml   # Completion notifications from Karo to Shogun
│   ├── tasks/                # Individual worker task files
│   └── reports/              # Worker reports
│
├── memory/                   # Memory MCP storage
├── dashboards/               # Project dashboards
│   └── {project_id}/
│       └── dashboard.md
├── dashboard.md              # Alias to active project dashboard (compat)
└── CLAUDE.md                 # Project context for Claude

---

🔧 Troubleshooting

MCP tools not working?

MCP tools are "deferred" and need to be loaded first:

# Wrong - tool not loaded
mcp__memory__read_graph()  ← Error!

# Correct - load first
ToolSearch("select:mcp__memory__read_graph")
mcp__memory__read_graph()  ← Works!

Agents asking for permissions?

Make sure to start with --dangerously-skip-permissions:

claude --dangerously-skip-permissions --system-prompt "..."

Workers stuck?

Check the worker's pane:

tmux attach-session -t multiagent
# Use Ctrl+B then number to switch panes

tmux says "sessions should be nested with care"?

Cause:

1. Command typo like tmux attach-session -t shoguntmux attach-session -t shogun
2. Running attach-session from inside an existing tmux session

Use this inside tmux:

tmux ls
tmux switch-client -t shogun
tmux switch-client -t multiagent

Use this only from a normal shell (outside tmux):

tmux attach-session -t shogun

Force attach from inside tmux (not recommended):

TMUX= tmux attach-session -t shogun

---

📚 tmux Quick Reference

Command	Description
tmux attach-session -t shogun	Connect to Shogun (outside tmux)
tmux attach-session -t multiagent	Connect to workers (outside tmux)
tmux switch-client -t shogun	Switch to Shogun (inside tmux)
tmux switch-client -t multiagent	Switch to workers (inside tmux)
Ctrl+B then 0-8	Switch between panes
Ctrl+B then d	Detach (leave running)
tmux kill-session -t shogun	Stop Shogun session
tmux kill-session -t multiagent	Stop worker sessions

---

🙏 Credits

Based on Claude-Code-Communication by Akira-Papa.

---

📄 License

MIT License - See LICENSE for details.

---

Command your AI army. Build faster.