One Karo (manager) coordinating 8 Ashigaru (workers) — real session, no mock data.

Give a single command. The Shogun (general) delegates to the Karo (steward), who distributes work across up to 8 Ashigaru (foot soldiers) — all running as independent Claude Code processes in tmux. Communication flows through YAML files and tmux send-keys, meaning zero extra API calls for agent coordination.

Most multi-agent frameworks burn API tokens on coordination. Shogun doesn't.

Zero coordination overhead — Agents talk through YAML files on disk. The only API calls are for actual work, not orchestration. Run 8 agents and pay only for 8 agents' work.

Full transparency — Every agent runs in a visible tmux pane. Every instruction, report, and decision is a plain YAML file you can read, diff, and version-control. No black boxes.

Battle-tested hierarchy — The Shogun → Karo → Ashigaru chain of command prevents conflicts by design: clear ownership, dedicated files per agent, event-driven communication, no polling.

This is the feature no other framework has.

As Ashigaru execute tasks, they automatically identify reusable patterns and propose them as skill candidates. The Karo aggregates these proposals in dashboard.md, and you — the Lord — decide what gets promoted to a permanent skill.

Ashigaru finishes a task
    ↓
Notices: "I've done this pattern 3 times across different projects"
    ↓
Reports in YAML:  skill_candidate:
                     found: true
                     name: "api-endpoint-scaffold"
                     reason: "Same REST scaffold pattern used in 3 projects"
    ↓
Appears in dashboard.md → You approve → Skill created in .claude/commands/
    ↓
Any agent can now invoke /api-endpoint-scaffold

Skills grow organically from real work — not from a predefined template library. Your skill set becomes a reflection of your workflow.

        You (上様 / The Lord)
             │
             ▼  Give orders
      ┌─────────────┐
      │   SHOGUN    │  Receives your command, plans strategy
      │    (将軍)    │  Session: shogun
      └──────┬──────┘
             │  YAML + send-keys
      ┌──────▼──────┐
      │    KARO     │  Breaks tasks down, assigns to workers
      │    (家老)    │  Session: multiagent, pane 0
      └──────┬──────┘
             │  YAML + send-keys
    ┌─┬─┬─┬─┴─┬─┬─┬─┐
    │1│2│3│4│5│6│7│8│  Execute in parallel
    └─┴─┴─┴─┴─┴─┴─┴─┘
         ASHIGARU (足軽)
         Panes 1-8

Communication protocol:

• Downward (orders): Write YAML → wake target with tmux send-keys
• Upward (reports): Write YAML only (no send-keys to avoid interrupting your input)
• Polling: Forbidden. Event-driven only. Your API bill stays predictable.

Context persistence (4 layers):

After /clear, an agent recovers in ~2,000 tokens by reading Memory MCP + its task YAML. No expensive re-prompting.

Agents can be deployed in different formations (陣形 / jindate) depending on the task:

./shutsujin_departure.sh          # Normal formation
./shutsujin_departure.sh -k       # Battle formation (all Opus)

The Karo can also promote individual Ashigaru mid-session with /model opus when a specific task demands it.

# 1. Clone
git clone https://github.com/yohey-w/multi-agent-shogun.git C:\tools\multi-agent-shogun

# 2. Run installer (right-click → Run as Administrator)
#    → install.bat handles WSL2 + Ubuntu setup automatically

# 3. In Ubuntu terminal:
cd /mnt/c/tools/multi-agent-shogun
./first_setup.sh          # One-time: installs tmux, Node.js, Claude Code CLI
./shutsujin_departure.sh  # Deploy your army

# 1. Clone
git clone https://github.com/yohey-w/multi-agent-shogun.git ~/multi-agent-shogun
cd ~/multi-agent-shogun && chmod +x *.sh

# 2. Setup + Deploy
./first_setup.sh          # One-time: installs dependencies
./shutsujin_departure.sh  # Deploy your army

cd /path/to/multi-agent-shogun
./shutsujin_departure.sh           # Normal startup (resumes existing tasks)
./shutsujin_departure.sh -c        # Clean startup (resets task queues, preserves command history)
tmux attach-session -t shogun      # Connect and give orders

Startup options:

• Default: Resumes with existing task queues and command history intact
• -c / --clean: Resets task queues for a fresh start while preserving command history in queue/shogun_to_karo.yaml. Previously assigned tasks are backed up before reset.

alias csst='cd /mnt/c/tools/multi-agent-shogun && ./shutsujin_departure.sh'
alias css='tmux attach-session -t shogun'
alias csm='tmux attach-session -t multiagent'

Control your AI army from your phone — bed, café, or bathroom.

Requirements:

• Tailscale (free) — creates a secure tunnel to your WSL
• Termux (free) — terminal app for Android
• SSH — already installed

Setup:

1. Install Tailscale on both WSL and your phone
2. In WSL (auth key method — browser not needed):

   curl -fsSL https://tailscale.com/install.sh | sh
   sudo tailscaled &
   sudo tailscale up --authkey tskey-auth-XXXXXXXXXXXX
   sudo service ssh start

3. In Termux on your phone:

   pkg update && pkg install openssh
   ssh youruser@your-tailscale-ip
   css    # Connect to Shogun

4. Open a new Termux window (+ button) for workers:

   ssh youruser@your-tailscale-ip
   csm    # See all 9 panes

Disconnect: Just swipe the Termux window closed. tmux sessions survive — agents keep working.

Voice input: Use your phone's voice keyboard to speak commands. The Shogun understands natural language, so typos from speech-to-text don't matter.

You: "Research the top 5 MCP servers and create a comparison table"

The Shogun writes the task to queue/shogun_to_karo.yaml and wakes the Karo. Control returns to you immediately — no waiting.

The Karo breaks the task into subtasks and assigns each to an Ashigaru:

All 5 Ashigaru research simultaneously. You can watch them work in real time:

Open dashboard.md to see aggregated results, skill candidates, and blockers — all maintained by the Karo.

This system manages all white-collar tasks, not just code. Projects can live anywhere on your filesystem.

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

Research sprints — 8 agents research different topics in parallel, results compiled in minutes.

Multi-project management — Switch between client projects without losing context. Memory MCP preserves preferences across sessions.

Document generation — Technical writing, test case reviews, comparison tables — distributed across agents and merged.

# config/settings.yaml
language: ja   # Samurai Japanese only
language: en   # Samurai Japanese + English translation

# Memory (auto-configured by first_setup.sh)
claude mcp add memory -e MEMORY_FILE_PATH="$PWD/memory/shogun_memory.jsonl" -- npx -y @modelcontextprotocol/server-memory

# Notion
claude mcp add notion -e NOTION_TOKEN=your_token -- npx -y @notionhq/notion-mcp-server

# GitHub
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=your_pat -- npx -y @modelcontextprotocol/server-github

# Playwright (browser automation)
claude mcp add playwright -- npx @playwright/mcp@latest

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

Tell the Shogun "check the latest screenshot" and it reads your screen captures for visual context. (Win+Shift+S on Windows.)

multi-agent-shogun/
├── install.bat                # Windows first-time setup
├── first_setup.sh             # Linux/Mac first-time setup
├── shutsujin_departure.sh     # Daily deployment script
│
├── instructions/              # Agent behavior definitions
│   ├── shogun.md
│   ├── karo.md
│   └── ashigaru.md
│
├── config/
│   ├── settings.yaml          # Language, model, screenshot settings
│   └── projects.yaml          # Project registry
│
├── queue/                     # Communication (source of truth)
│   ├── shogun_to_karo.yaml
│   ├── tasks/ashigaru{1-8}.yaml
│   └── reports/ashigaru{1-8}_report.yaml
│
├── memory/                    # Memory MCP persistent storage
├── dashboard.md               # Human-readable status board
└── CLAUDE.md                  # System instructions (auto-loaded)

ToolSearch("select:mcp__memory__read_graph")
mcp__memory__read_graph()

# From the crashed pane:
claude --model opus --dangerously-skip-permissions

# Or from another pane:
tmux respawn-pane -t shogun:0.0 -k 'claude --model opus --dangerously-skip-permissions'

tmux attach-session -t multiagent
# Ctrl+B then 0-8 to switch panes

Mouse support is enabled by default (set -g mouse on in ~/.tmux.conf, configured by first_setup.sh). Scroll, click to focus, drag to resize.

Issues and pull requests are welcome.

• Bug reports: Open an issue with reproduction steps
• Feature ideas: Open a discussion first
• Skills: Skills are personal by design and not included in this repo

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

MIT