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, and Kimi Code.

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.

| | Claude Code Task tool | Claude Code Agent Teams | LangGraph | CrewAI | multi-agent-shogun | |---|---|---|---|---|---| | Architecture | Subagents inside one process | Team lead + teammates (JSON mailbox) | Graph-based state machine | Role-based agents | Feudal hierarchy via tmux | | Parallelism | Sequential (one at a time) | Multiple independent sessions | Parallel nodes (v0.2+) | Limited | 8 independent agents | | Coordination cost | API calls per Task | Token-heavy (each teammate = separate context) | API + infra (Postgres/Redis) | API + CrewAI platform | Zero (YAML + tmux) | | Multi-CLI | Claude Code only | Claude Code only | Any LLM API | Any LLM API | 4 CLIs (Claude/Codex/Copilot/Kimi) | | Observability | Claude logs only | tmux split-panes or in-process | LangSmith integration | OpenTelemetry | Live tmux panes + dashboard | | Skill discovery | None | None | None | None | Bottom-up auto-proposal | | Setup | Built into Claude Code | Built-in (experimental) | Heavy (infra required) | pip install | Shell scripts |

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:

| | API (Per-Token) | CLI (Flat-Rate) | |---|---|---| | 8 agents × Opus | ~$100+/hour | ~$200/month | | Cost predictability | Unpredictable spikes | Fixed monthly bill | | Usage anxiety | Every token counts | Unlimited | | Experimentation budget | Constrained | Deploy freely |

"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 4 CLI tools, each with unique strengths:

| CLI | Key Strength | Default Model | |-----|-------------|---------------| | Claude Code | Battle-tested tmux integration, Memory MCP, dedicated file tools (Read/Write/Edit/Glob/Grep) | Claude Sonnet 4.6 | | OpenAI Codex | Sandbox execution, JSONL structured output, codex exec headless mode, per-model --model flag | gpt-5.3-codex / gpt-5.3-codex-spark | | GitHub Copilot | Built-in GitHub MCP, 4 specialized agents (Explore/Task/Plan/Code-review), /delegate to coding agent | Claude Sonnet 4.6 | | Kimi Code | Free tier available, strong multilingual support | Kimi k2 |

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
└── roles/               # Role definitions (shogun, karo, ashigaru)
    ↓ build
CLAUDE.md / AGENTS.md / copilot-instructions.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)

Step 1

📥 Download the 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 → "Run as Administrator" (if WSL2 is not installed). Sets up WSL2 + Ubuntu automatically.

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

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.

| Feature | Description | |---------|-------------| | Shogun Terminal | SSH terminal + voice input + special key bar