Skip to content

marucc/multi-agent-shogun

BranchesTags
 
 

Repository files navigation

multi-agent-shogun

Multi-Agent Orchestration System for Claude Code

One command. Multiple AI agents working in parallel via Agent Teams.

License: MIT Claude Code tmux

English | Japanese / 日本語

Fork notice: This repository is a fork of yohey-w/multi-agent-shogun. See CHANGELOG.md for changes since the fork.

What is this?

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

Why use this?

  • Give one command, get multiple AI workers executing in parallel
  • Built on Claude Code's Agent Teams — agents communicate via SendMessage/TaskCreate
  • 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
      └──────┬──────┘
             │ Agent Teams API
      ┌──────▼──────┐
      │    KARO     │  ← Distributes tasks to workers
      └──────┬──────┘
             │
    ┌────────┼────────┐
    ▼        ▼        ▼
┌────────┐ ┌──┬──┬──┐
│METSUKE │ │A1│A2│A3│ ...  ← Workers execute in parallel
│(Review)│ └──┴──┴──┘
└────────┘   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/marucc/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

✅ Done! AI agents are now running.

📅 Daily Startup (After First Install)

Open Ubuntu terminal (WSL) and run from your project directory:

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

🔐 First-Time Authentication (One Time Only)

  1. After running ./shutsujin_departure.sh, a login screen appears in each pane
  2. In just ONE pane, copy the URL and open it in your browser to log in
  3. After authentication, press Ctrl+C in other panes and re-run claude --dangerously-skip-permissions
  4. Credentials are saved to ~/.claude/ and won't be needed again

Note: You don't need to log in separately on every pane.

🐧 Linux / Mac Users (Click to expand)

First-Time Setup

# 1. Clone the repository
git clone https://github.com/marucc/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 ~/your-project
~/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:

  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 + configures Memory MCP First time only
shutsujin_departure.sh Creates .shogun/ + tmux sessions + starts Claude Code Every day (run from project dir)

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
  • ✅ Configures Memory MCP server (for cross-session memory)

What shutsujin_departure.sh does:

  • ✅ Creates .shogun/ directory in your project (dashboard, logs, wrapper scripts)
  • ✅ Creates tmux sessions (shogun-<project> + multiagent-<project>)
  • ✅ Launches Claude Code with Agent Teams enabled
  • ✅ Automatically loads instruction files for each agent
  • ✅ Sets up the team hierarchy (Shogun → Karo → Ashigaru)

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
🔍 Metsuke Reviewer — quality assurance 1
⚔️ Ashigaru Workers — execute tasks in parallel Configurable (default: 3)

You'll see tmux sessions created (names include your project name):

  • shogun-<project> — Connect here to give commands
  • multiagent-<project> — Workers running in background

Wrapper scripts are generated in .shogun/bin/ for easy access.

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

.shogun/bin/shogun.sh

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. Create tasks via Agent Teams API
  2. Send instructions to the Karo (manager) via SendMessage
  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 .shogun/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 multiple parallel tasks:

You: "Research 5 MCP servers"
→ 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. Agent Teams Communication

Agents communicate via Claude Code's Agent Teams API:

  • SendMessage — Direct messages between agents
  • TaskCreate / TaskUpdate — Task management and assignment
  • Automatic delivery — No polling, no wasted API calls

📸 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.

📁 6. 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

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

🛠️ 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"
  4. Quality Gate: Metsuke reviews outputs independently

Why Agent Teams?

  • Native integration: Built on Claude Code's Agent Teams API
  • Automatic message delivery: No polling, no file-based workarounds
  • Task management: Built-in TaskCreate/TaskUpdate/TaskList
  • Reliable communication: SendMessage with guaranteed delivery

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

🔌 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.

⚙️ Configuration

Agent Count

Edit config/settings.yaml:

ashigaru_count: 3   # Number of workers (1-8)

Language Setting

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                    │
│                └── Configure Memory MCP server                      │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│                      DAILY STARTUP (Run Every Day)                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  shutsujin_departure.sh                                             │
│      │                                                              │
│      ├──▶ Create .shogun/ directory in project                        │
│      │                                                              │
│      ├──▶ Create tmux sessions                                      │
│      │         • "shogun-<project>" session (Shogun agent)          │
│      │         • "multiagent-<project>" session (Karo+Metsuke+Ashi) │
│      │                                                              │
│      └──▶ Launch Claude Code with Agent Teams                       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
shutsujin_departure.sh Options (Click to expand) 
# Run from your project directory
cd /path/to/your/project

# Default: Full startup (.shogun/ creation + tmux sessions + Claude Code launch)
/path/to/multi-agent-shogun/shutsujin_departure.sh

# Show help
/path/to/multi-agent-shogun/shutsujin_departure.sh -h
Common Workflows (Click to expand)

Normal Daily Usage:

cd /path/to/your/project
/path/to/multi-agent-shogun/shutsujin_departure.sh   # Start everything
.shogun/bin/shogun.sh                                 # Connect to give commands

Re-launch (after retreat):

.shogun/bin/shutsujin.sh          # Re-deploy from project directory

Retreat (shutdown):

.shogun/bin/tettai.sh             # Graceful shutdown with backup

📁 File Structure

Click to expand file structure 
multi-agent-shogun/                      # SHOGUN_ROOT (system files)
│
│  ┌─────────────────── SCRIPTS ─────────────────────────┐
├── install.bat               # Windows: First-time setup
├── first_setup.sh            # Ubuntu/Mac: First-time setup
├── shutsujin_departure.sh    # Deploy (run from project dir)
├── tettai_retreat.sh         # Shutdown / retreat
├── watchdog.sh               # Monitoring daemon
├── switch_account.sh         # Account switching
│  └────────────────────────────────────────────────────┘
│
├── instructions/             # Agent instruction files
│   ├── shogun.md             # Commander instructions
│   ├── karo.md               # Manager instructions
│   ├── metsuke.md            # Reviewer instructions
│   └── ashigaru.md           # Worker instructions
│
├── scripts/
│   ├── claude-shogun         # Claude Code launcher wrapper
│   ├── notify.sh             # tmux send-keys wrapper
│   └── project-env.sh        # Shared variable definitions
│
├── config/
│   └── settings.yaml         # Language, agent count settings
│
├── context/                  # Project context files
├── memory/                   # Memory MCP storage
└── CLAUDE.md                 # Project context for Claude

your-project/.shogun/                    # Generated per project
├── project.env               # Project metadata
├── dashboard.md              # Real-time status overview
├── bin/
│   ├── shutsujin.sh          # Re-deploy wrapper
│   ├── tettai.sh             # Retreat wrapper
│   ├── shogun.sh             # Attach to shogun session
│   └── multiagent.sh         # Attach to multiagent session
├── status/
│   └── pending_tasks.yaml    # Saved on retreat
└── logs/
    └── backup_*/             # Backups

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

.shogun/bin/multiagent.sh
# Use Ctrl+B then arrow keys to switch panes

📚 tmux Quick Reference

Command Description
.shogun/bin/shogun.sh Connect to Shogun
.shogun/bin/multiagent.sh Connect to workers
.shogun/bin/tettai.sh Graceful shutdown
Ctrl+B then 0-8 Switch between panes
Ctrl+B then d Detach (leave running)
tmux ls List all sessions

🙏 Credits

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

Forked from yohey-w/multi-agent-shogun.

📄 License

MIT License - See LICENSE for details.

Command your AI army. Build faster.

About

Samurai-inspired multi-agent system for Claude Code. Orchestrate parallel AI tasks via tmux with shogun → karo → ashigaru hierarchy.

Resources

Readme

License

MIT license
Activity

Stars

5 stars

Watchers

0 watching

Forks

4 forks
Report repository

Releases

26 tags

Packages

 
 
 

Contributors

Languages

  • Shell 95.4%
  • Batchfile 4.6%