multi-agent-daimyo

Multi-Agent Orchestration System for Claude Code

One command. Eight AI agents working in parallel.

What is this?

multi-agent-daimyo 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
      ┌─────────────┐
      │     KARO    │  ← Receives your command, delegates immediately
      └──────┬──────┘
             │ YAML files + tmux
      ┌──────▼──────┐
      │    BUSHO    │  ← 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-daimyo` Or use git: `git clone https://github.com/yuzame/multi-agent-daimyo.git C:\tools\multi-agent-daimyo`
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-daimyo ./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-daimyo
./shutsujin_departure.sh

🐧 Linux / Mac Users (Click to expand)

First-Time Setup

# 1. Clone the repository
git clone https://github.com/yuzame/multi-agent-daimyo.git ~/multi-agent-daimyo
cd ~/multi-agent-daimyo

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

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

Daily Startup

cd ~/multi-agent-daimyo
./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 (karo + multiagent)
✅ Launches Claude Code for all agents
✅ Auto-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
🏯 Karo	Commander - receives your orders	1
📋 Busho	Manager - distributes tasks	1
⚔️ Ashigaru	Workers - execute tasks in parallel	8

You'll see tmux sessions created:

karo - Connect here to give commands
multiagent - Workers running in background

📖 Basic Usage

Step 1: Connect to Karo

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

Open a new terminal and connect to the Karo:

tmux attach-session -t karo

Step 2: Give Your First Order

The Karo is already initialized! Just give your command:

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

The Karo will:

Write the task to a YAML file
Notify the Busho (manager)
Return control to you immediately (you don't have to wait!)

Meanwhile, the Busho 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 Karo delegates immediately and returns control to you:

You: Give order → Karo: 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 Karo:
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
Karo	Opus	Disabled	Delegation & dashboard updates don't need deep reasoning
Busho	Default	Enabled	Task distribution requires careful judgment
Ashigaru	Default	Enabled	Actual implementation needs full capabilities

The Karo 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/karo_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.

Skills can be invoked with /skill-name. Just tell the Karo: "run /skill-name".

🔀 Multi-CLI Support

multi-agent-daimyo supports multiple AI CLIs, not just Claude Code.

Supported CLIs (Coding Agents)

CLI	Features	OpenAI Compatible	Recommended Use Case
Claude Code CLI	Opus/Sonnet models, MCP integration	✅	Tasks requiring advanced reasoning
Codex CLI	OpenAI official, full-auto mode	✅	Code generation focused tasks
Crush CLI	Charmbracelet, YOLO mode	✅	Lightweight tasks, fast processing
Goose CLI	Block, multi-model support	✅	Flexible model switching
GitHub Copilot CLI	Claude/GPT-5 models, GitHub integration	❌	Tasks requiring GitHub integration
Gemini CLI	Google AI, 1M token context	❌	Large context processing

Note: CLIs with ✅ can use OpenAI-compatible APIs (GLM, DeepSeek, etc.) as backends.

軍目付（Inspector - Separate Role）

Name	Role	Features
工兎（Koto）	軍目付 (Inspector)	Code inspection, security analysis (CodeRabbit)

Note: Koto is a "Gun-metsuke" (military inspector) - an independent inspection role separate from the command chain (Karo → Busho → Ashigaru). Koto specializes only in code inspection and cannot perform general tasks.

Configuration

Specify CLI for each agent in config/settings.yaml:

cli:
  # Default for all agents
  default: claude

  # Per-agent configuration (optional)
  agents:
    karo:
      type: claude
      model: opus

    # Claude Code CLI + GLM Backend (OpenAI-compatible)
    ashigaru1:
      type: claude
      backend:
        base_url: "https://open.bigmodel.cn/api/paas/v4"
        api_key_env: "GLM_API_KEY"
        model: "glm-4-plus"

    # Codex CLI + DeepSeek Backend (OpenAI-compatible)
    ashigaru2:
      type: codex
      backend:
        base_url: "https://api.deepseek.com/v1"
        api_key_env: "DEEPSEEK_API_KEY"
        model: "deepseek-coder"

    # Crush CLI
    ashigaru3:
      type: crush

    # Goose CLI
    ashigaru4:
      type: goose

    # GitHub Copilot CLI
    ashigaru5:
      type: copilot

    # Gemini CLI
    ashigaru6:
      type: gemini
      model: gemini-2.5-flash

Command-Line Flags

# Use settings from config file (default)
./shutsujin_departure.sh

# Force all agents to use Claude Code CLI
./shutsujin_departure.sh --claude

# Force all agents to use Codex CLI
./shutsujin_departure.sh --codex

# Force all agents to use Crush CLI
./shutsujin_departure.sh --crush

# Force all agents to use Goose CLI
./shutsujin_departure.sh --goose

# Force all agents to use GitHub Copilot CLI
./shutsujin_departure.sh --copilot

# Force all agents to use Gemini CLI
./shutsujin_departure.sh --gemini

Prerequisites

Claude Code CLI:

npm install -g @anthropic-ai/claude-code

Codex CLI:

npm install -g @openai/codex
export OPENAI_API_KEY="your-api-key"

Crush CLI:

brew install charmbracelet/tap/crush
# or
npm install -g @charmland/crush

Goose CLI:

curl -fsSL https://github.com/block/goose/raw/main/download_cli.sh | bash

GitHub Copilot CLI:

npm install -g @github/copilot
# or
brew install copilot-cli

Gemini CLI:

npm install -g @google/gemini-cli
# or
brew install gemini-cli

軍目付（Inspector）Installation

工兎（Koto） - CodeRabbit CLI:

curl -fsSL https://cli.coderabbit.ai/install.sh | sh
coderabbit auth login

Ashigaru requests inspection from Koto after implementing code. Inspection results are reported to Busho, who redistributes fix tasks:
Ashigaru implements code
    ↓
Ashigaru: "工兎殿に検分を依頼し申した"
    (coderabbit --prompt-only --type uncommitted)
    ↓
Ashigaru reports Koto's findings to Busho
    ↓
Busho analyzes and splits fix tasks
    ↓
Multiple Ashigaru fix in parallel

OpenAI-Compatible Backend Configuration

To use OpenAI-compatible APIs like GLM or DeepSeek:

cli:
  agents:
    ashigaru1:
      type: claude  # claude, codex, crush, or goose
      backend:
        base_url: "https://open.bigmodel.cn/api/paas/v4"  # API endpoint
        api_key_env: "GLM_API_KEY"  # Environment variable name
        model: "glm-4-plus"  # Model name

Set the environment variables:

export GLM_API_KEY="your-glm-api-key"
export DEEPSEEK_API_KEY="your-deepseek-api-key"

🏛️ Design Philosophy

Why Hierarchical Structure?

The Karo → Busho → Ashigaru hierarchy exists for:

Immediate Response: Karo delegates instantly and returns control to you
Parallel Execution: Busho distributes to multiple Ashigaru simultaneously
Separation of Concerns: Each role is clearly defined — Karo decides "what", Busho decides "who"
Scalability: Adding more Ashigaru doesn't break the structure
Fault Isolation: One Ashigaru failing doesn't affect others
Centralized Reporting: Only Karo communicates with you, keeping information organized

Why YAML + send-keys?

YAML files: Structured communication that survives agent restarts and is human-readable for debugging
send-keys: Event-driven wakeups (no polling = no wasted API calls)
No direct calls: Agents can't interrupt each other or your input
Conflict avoidance: Each Ashigaru has dedicated files, preventing race conditions

Why Only Busho Updates Dashboard?

Single responsibility: One writer = no conflicts
Information hub: Busho receives all reports, knows the full picture
Consistency: All updates go through one quality gate
No interruptions: Prevents disrupting your input when Karo would otherwise update the dashboard

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 notices a repeatable pattern during work
    ↓
Candidate appears in dashboard.md under "Skill Candidates"
    ↓
You (the Lord) review the candidate
    ↓
If approved, Busho creates the skill

Skills are user-driven — they only grow when you decide they're useful. Automatic growth would make them unmanageable, so only what you explicitly approve 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/karo_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. Karo delegates to Busho
2. Busho 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. Busho 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                                      │
│      │         • "karo" 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 karo       # 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 karo: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 karo
tmux kill-session -t multiagent

# Start fresh
./shutsujin_departure.sh

Convenient Aliases (Click to expand)

Running first_setup.sh automatically adds these aliases to ~/.bashrc:

alias css='cd /mnt/c/tools/multi-agent-daimyo && ./shutsujin_departure.sh'  # Setup + deploy
alias csm='cd /mnt/c/tools/multi-agent-daimyo'                              # Navigate to directory only

To apply aliases, run source ~/.bashrc or restart your terminal. On WSL, run wsl --shutdown in PowerShell first — simply closing the window does not terminate WSL.

📁 File Structure

Click to expand file structure

multi-agent-daimyo/
│
│  ┌─────────────────── 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
│   ├── karo.md               # Commander instructions
│   ├── busho.md              # Manager instructions
│   └── ashigaru.md           # Worker instructions
│
├── config/
│   └── settings.yaml         # Language and other settings
│
├── projects/                # Project details (git-ignored, contains client data)
│   └── <project_id>.yaml   # Full project info (client, tasks, Notion links, etc.)
│
├── queue/                    # Communication files
│   ├── karo_to_busho.yaml    # Commands from Karo to Busho
│   ├── tasks/                # Individual worker task files
│   └── reports/              # Worker reports
│
├── memory/                   # Memory MCP storage
├── dashboard.md              # Real-time status overview
└── CLAUDE.md                 # Project context for Claude

📂 Project Management

This system manages all white-collar tasks, not just its own development. Projects can live anywhere on your filesystem — they don't need to be inside this repository.

How It Works

config/projects.yaml          # Project registry (ID, name, path, status)
projects/<project_id>.yaml    # Full project details (client info, tasks, Notion links, etc.)

config/projects.yaml: Lists all projects with basic metadata (ID, name, path, status)
projects/<id>.yaml: Contains full details for each project (client info, contract, tasks, related files, Notion pages, etc.)
Project files (source code, docs, etc.) live at the path specified in the project entry — anywhere on the filesystem
projects/ is git-ignored because it may contain confidential client information

Example

# config/projects.yaml
projects:
  - id: my_client
    name: "Client X Consulting"
    path: "/mnt/c/Consulting/client_x"
    status: active

# projects/my_client.yaml
id: my_client
client:
  name: "Client X"
  company: "X Corp"
contract:
  fee: "monthly"
current_tasks:
  - id: task_001
    name: "System architecture review"
    status: in_progress

This separation allows the Karo system to orchestrate tasks across multiple external projects while keeping project details private and out of version control.

🔧 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 karo`	Connect to Karo
`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 karo`	Stop Karo session
`tmux kill-session -t multiagent`	Stop worker sessions

🖱️ Mouse Support

first_setup.sh automatically configures tmux mouse support (set -g mouse on in ~/.tmux.conf). This enables the following mouse operations:

Action	Description
Scroll wheel	Scroll within a pane
Click on a pane	Switch focus between panes
Drag pane border	Resize panes

Note: If you set up tmux manually (without first_setup.sh), add set -g mouse on to your ~/.tmux.conf to enable mouse support.

🙏 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 51 Commits
.claude		.claude
config		config
context		context
instructions		instructions
lib		lib
scripts		scripts
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

yuzamesan3/multi-agent-daimyo

Folders and files

Latest commit

History

Repository files navigation