📖 Sequel (Aug 2026): The author has since disbanded his own 10-agent army down to a single agent that carries his judgment. The successor project is kagemusha — it ships the forms of a judgment loop (corrections → principles → standing rules), not the agents. The story of the disbandment: article (JP). multi-agent-shogun itself continues to work as-is.

One Karo (manager) coordinating 7 Ashigaru (workers) + 1 Gunshi (strategist) — real session, no mock data.

Quick Start

Requirements: tmux, bash 4+, at least one of: Claude Code / Codex / Copilot / Kimi / OpenCode / Antigravity

git clone https://github.com/yohey-w/multi-agent-shogun
cd multi-agent-shogun
bash first_setup.sh                        # one-time setup: config, dependencies, MCP
source ~/.bashrc                           # reload PATH
claude --dangerously-skip-permissions      # first run only: OAuth + accept Bypass Permissions → /exit
bash shutsujin_departure.sh                # launch all agents

For full install steps (incl. Windows) and the first-30-minutes walkthrough, see 🚀 Quick Start and the basic usage section below.

Type a command in the Shogun pane:

"Build a REST API for user authentication"

Shogun delegates → Karo breaks it down → 7 Ashigaru execute in parallel. You watch the dashboard. That's it.

Want to go deeper? The rest of this README covers architecture, configuration, memory design, and multi-CLI setup.

What is this?

multi-agent-shogun is a system that runs multiple AI coding CLI instances simultaneously, orchestrating them like a feudal Japanese army. Supports Claude Code, OpenAI Codex, GitHub Copilot, Kimi Code, OpenCode, Cursor, and Antigravity.

Why use it?

• One command spawns 7 AI workers + 1 strategist executing in parallel
• Zero wait time — give your next order while tasks run in the background
• AI remembers your preferences across sessions (Memory MCP)
• Real-time progress on a dashboard

        You (上様 / The Lord)
             │
             ▼  Give orders
      ┌─────────────┐
      │   SHOGUN    │  ← Receives your command, delegates instantly
      └──────┬──────┘
             │  YAML + tmux
      ┌──────▼──────┐
      │    KARO     │  ← Distributes tasks to workers
      └──────┬──────┘
             │
    ┌─┬─┬─┬─┴─┬─┬─┬─┬────────┐
    │1│2│3│4│5│6│7│ GUNSHI │  ← 7 workers + 1 strategist
    └─┴─┴─┴─┴─┴─┴─┴────────┘
       ASHIGARU      軍師

Why Shogun?

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

What makes this different

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.

Why CLI (Not API)?

Most AI coding tools charge per token. Running 8 Opus-grade agents through the API costs $100+/hour. CLI subscriptions flip this:

"Use AI recklessly" — With flat-rate CLI subscriptions, deploy 8 agents without hesitation. The cost is the same whether they work 1 hour or 24 hours. No more choosing between "good enough" and "thorough" — just run more agents.

Multi-CLI Support

Shogun isn't locked to one vendor. The system supports 7 CLI tools, each with unique strengths:

OpenCode sessions load the agent-specific .opencode/agents/<agent_id>.md definition via --agent and keep automation resets on /new; model changes require a relaunch. Automation uses the repository-provided config/opencode-tui.json via OPENCODE_TUI_CONFIG, which disables app_exit and pins session_interrupt/input_clear to known bindings. Role boundaries are embedded in the generated agent frontmatter: Shogun can read queue/reports/* for oversight but cannot write them, Karo is limited to coordination files plus report aggregation, Ashigaru only touch their own task/report pair, and Gunshi reads ashigaru reports but only writes gunshi_report.yaml.

Antigravity sessions launch with agy --dangerously-skip-permissions. Shogun treats type: antigravity, type: agy, and legacy type: gemini as Antigravity. Authentication and default model selection stay in the host user's Antigravity CLI setup; settings.yaml may optionally pass a concrete model, but auto uses the host default or last-used model.

A unified instruction build system generates CLI-specific instruction files from shared templates:

instructions/
├── common/              # Shared rules (all CLIs)
├── cli_specific/        # CLI-specific tool descriptions
│   ├── claude_tools.md  # Claude Code tools & features
│   ├── copilot_tools.md # GitHub Copilot CLI tools & features
│   ├── opencode_tools.md # OpenCode tools, agent frontmatter, and permission model
│   └── cursor_tools.md  # Cursor Agent tools, skills, and session rules
└── roles/               # Role definitions (shogun, karo, ashigaru)
    ↓ build
CLAUDE.md / AGENTS.md / .github/copilot-instructions.md / .opencode/agents/*.md / .cursor/rules/*.md
  ← Generated per CLI

One source of truth, zero sync drift. Change a rule once, all CLIs get it.

Bottom-Up Skill Discovery

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.

Quick Start

Windows (WSL2)

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

./shutsujin_departure.sh

First-time only: Authentication

After first_setup.sh, run these commands once to authenticate:

# 1. Apply PATH changes
source ~/.bashrc

# 2. OAuth login + Bypass Permissions approval (one command)
claude --dangerously-skip-permissions
#    → Browser opens → Log in with Anthropic account → Return to CLI
#    → "Bypass Permissions" prompt appears → Select "Yes, I accept" (↓ to option 2, Enter)
#    → Type /exit to quit

This saves credentials to ~/.claude/ — you won't need to do it again.

Daily startup

Open an Ubuntu terminal (WSL) and run:

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

📱 Mobile Access — Dedicated Android App (Recommended)

Monitor and command 10 AI agents from your phone with the dedicated Android companion app.

Note: Android only for now. No iOS version — the developer doesn't own an iPhone. If there's demand, please open an Issue. PRs welcome!

Setup

Prerequisites:

• Shogun system running on WSL2 (or Linux server)
• SSH server started (sudo service ssh start)
• Phone and server on same network (LAN or Tailscale)

Steps:

1. Install APK

   1. Download android/release/multi-agent-shogun.apk on your phone (open the file on GitHub → "Download raw file")
   2. Tap the download notification → "Install"
   3. If "Unknown sources" warning appears → "Settings" → enable "Allow from this source" for your browser → go back → "Install"
   4. Done → "Open"

2. Configure SSH (Settings tab)

   Field	Example	Description
   SSH Host	100.xxx.xxx.xxx	Server IP (e.g., Tailscale IP)
   SSH Port	22	Usually 22
   SSH User	your_username	SSH login username
   SSH Key Path	/data/data/.../id_ed25519	Private key path on phone (*1)
   SSH Password	****	Use if no key available
   Project Path	/mnt/c/tools/multi-agent-shogun	Server-side project directory
   Shogun Session	shogun	tmux session name for Shogun
   Agent Session	multiagent	tmux session name for agents

   *1 Transfer your private key to the phone, or use password authentication

3. Save → Switch to Shogun tab → auto-connects

Using Tailscale (connect from anywhere):

# Server-side (WSL2)
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscaled &
sudo tailscale up --authkey tskey-auth-XXXXXXXXXXXX
sudo service ssh start

Install the Tailscale app on your phone, log in with the same account, and use the displayed Tailscale IP as the SSH Host in the app.

With ntfy notifications:

See ntfy setup section for push notifications from Karo on task completion.

# 1. Clone
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

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

wsl --install

After Setup

Whichever option you chose, 10 AI agents are automatically launched:

Two tmux sessions are created:

• shogun — connect here to give commands
• multiagent — Karo, Ashigaru, and Gunshi running in the background

How It Works

Step 1: Connect to the Shogun

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

Open a new terminal and connect:

tmux attach-session -t shogun

Step 2: Give your first order

The Shogun is already initialized — just give a command:

Research 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 — no waiting!

Meanwhile, the Karo distributes tasks to Ashigaru workers for parallel execution.

Step 3: Check progress

Open dashboard.md in your editor for a real-time status view:

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

Project-Unit Operation (Equivalent to Visual Studio "Solution")

Once set up, the Shogun system can handle multiple projects under the same Shogun, switching between them as needed. The unit equivalent to a Visual Studio "solution" is projects/{name}.yaml + context/{name}.md.

1. Running your first project

# (1) Connect to the Shogun (after shutsujin_departure.sh completes)
tmux attach-session -t shogun

# (2) Just give the Shogun your command — the project starts automatically
#     → Shogun writes cmd to queue/shogun_to_karo.yaml and notifies Karo
#     → Karo distributes to Ashigaru for parallel execution
#     → Results aggregate in dashboard.md

No explicit "create a project" command is needed. The Shogun attaches a project: field to the cmd when relevant, and related files are automatically separated.

2. Explicitly registering a project (optional, for long-term work)

For ongoing projects, you can place metadata in projects/{name}.yaml:

# projects/example.yaml
id: example
name: "Sample Project"
working_directory: /path/to/repo
north_star: "The ultimate goal for this project"
notes: |
  Project-specific notes, stakeholders, special rules

The Shogun and Karo reference this file and inject project context when issuing cmds.

Detailed project knowledge (requirements, design, past feedback) lives in context/{name}.md. When the Shogun issues a cmd related to the project, it automatically references this file.

3. Customizing the agent formation

The agent formation (which CLI each agent uses) lives in config/settings.yaml:

cli:
  agents:
    ashigaru1:
      type: codex          # codex / claude / copilot / kimi / opencode / antigravity
      model: gpt-5.5
    ashigaru2:
      type: claude
      model: claude-sonnet-4-6
    # Same for ashigaru3-7, gunshi, karo

OpenCode uses provider-qualified model IDs:

cli:
  agents:
    ashigaru3:
      type: opencode
      model: openrouter/openai/gpt-4o-mini
      variant: high  # optional provider-specific reasoning variant
``