multi-agent-shogun

Multi-Agent Orchestration System for Claude Code

One command. Eight AI agents working in parallel.

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	🖱️ Run `install.bat` Right-click and select "Run as administrator" (required if WSL2 is not yet installed). The installer will guide you through each step — you may need to restart your PC or set up Ubuntu before re-running.
Step 3	🐧 Open Ubuntu and run (first time only) cd /mnt/c/tools/multi-agent-shogun ./first_setup.sh
Step 4	✅ Deploy! ./shutsujin_departure.sh

📅 Daily Startup (After First Install)

Open Ubuntu terminal (WSL) and run:

cd /mnt/c/tools/multi-agent-shogun
./shutsujin_departure.sh

🐧 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

cd ~/multi-agent-shogun
./shutsujin_departure.sh

❓ 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:

Check if WSL2 is installed (auto-install if missing)
Check if Ubuntu is installed (auto-install if missing)
Guide you to the next steps (first_setup.sh)

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: WSL2 + Ubuntu setup	First time only
`first_setup.sh`	Installs tmux, Node.js, Claude Code CLI + configures Memory MCP	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 (auto-install if missing)
✅ Checks if Ubuntu is installed (auto-install if missing)
✅ Guides you to the next steps (first_setup.sh)

What `shutsujin_departure.sh` does:

✅ Creates tmux sessions (shogun + multiagent)
✅ Launches Claude Code on all agents
✅ Automatically loads instruction files for each agent
✅ Resets queue files for a fresh start

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
Set Ubuntu as default	`wsl --set-default Ubuntu`	Required for scripts to work
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, 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

📖 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:

Write the task to a YAML file
Notify the Karo (manager)
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 dashboard.md in your editor to see real-time status:

## 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
                                           ↓
                         Dashboard: Shows results

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:

Immediate Response: Shogun delegates instantly and returns control to you
Parallel Execution: Karo distributes to multiple Ashigaru simultaneously
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:

Ashigaru report "skill candidates" when they notice repeatable patterns
Candidates appear in dashboard.md under "Skill Candidates"
You review and approve (or reject)
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!)
# ✅ Automatically configured by first_setup.sh
# To reconfigure manually:
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)                                              │
│      │                                                              │
│      ├── Check/Install WSL2                                         │
│      └── Check/Install Ubuntu                                       │
│                                                                     │
│  first_setup.sh (run manually in Ubuntu/WSL)                        │
│      │                                                              │
│      ├── Check/Install tmux                                         │
│      ├── Check/Install Node.js v20+ (via nvm)                      │
│      ├── Check/Install Claude Code CLI                              │
│      └── Configure Memory MCP server                                │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│                      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: Full startup (tmux sessions + Claude Code launch)
./shutsujin_departure.sh

# 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

Common Workflows (Click to expand)

Normal Daily Usage:

./shutsujin_departure.sh          # Start everything
tmux attach-session -t shogun     # Connect to give commands

Debug Mode (manual control):

./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
./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
│   ├── tasks/                # Individual worker task files
│   └── reports/              # Worker reports
│
├── memory/                   # Memory MCP storage
├── dashboard.md              # Real-time status overview
└── 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 Quick Reference

Command	Description
`tmux attach -t shogun`	Connect to Shogun
`tmux attach -t multiagent`	Connect to workers
`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.

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
context		context
instructions		instructions
skills/skill-creator		skills/skill-creator
templates		templates
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
README_ja.md		README_ja.md
first_setup.sh		first_setup.sh
install.bat		install.bat
setup.sh		setup.sh
shutsujin_departure.sh		shutsujin_departure.sh

License

curva/multi-agent-shogun-copilot

Folders and files

Latest commit

History

Repository files navigation