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

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 8 AI workers 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│8│  ← 8 workers execute in parallel
    └─┴─┴─┴─┴─┴─┴─┴─┘
         ASHIGARU

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.

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.

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

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.

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.

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

./shutsujin_departure.sh

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.

Open an Ubuntu terminal (WSL) and run:

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

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

Requirements (all free):

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.

Even simpler: With ntfy configured, you can receive notifications and send commands directly from the ntfy app — no SSH required.

# 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

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

Two tmux sessions are created:

• shogun — connect here to give commands
• multiagent — workers running in the background

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

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.

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 |

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.

The Karo breaks the task into subtasks:

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

Results appear in dashboard.md as they complete.

One command spawns up to 8 parallel tasks:

You: "Research 5 MCP servers"
→ 5 Ashigaru start researching simultaneously
→ Results in minutes, not hours

The Shogun delegates instantly and returns control to you:

You: Command → Shogun: Delegates → You: Give next command immediately
                                       ↓
                       Workers: Execute in background
                                       ↓
                       Dashboard: Shows results

No waiting for long tasks to finish.

Your AI remembers your preferences:

Session 1: Tell it "I prefer simple approaches"
            → Saved to Memory MCP

Session 2: AI loads memory on startup
            → Stops suggesting complex solutions

Agents talk to each other by writing YAML files — like passing notes. No polling loops, no wasted API calls.

Karo wants to wake Ashigaru 3:

Step 1: Write the message          Step 2: Wake the agent up
┌──────────────────────┐           ┌──────────────────────────┐
│ inbox_write.sh       │           │ inbox_watcher.sh         │
│                      │           │                          │
│ Writes full message  │  file     │ Detects file change      │
│ to ashigaru3.yaml    │──change──▶│ (inotifywait, not poll)  │
│ with flock (no race) │           │                          │
└──────────────────────┘           │ Wakes agent via:         │
                                   │  1. Self-watch (skip)    │
                                   │  2. tmux send-keys       │
                                   │     (short nudge only)   │
                                   └──────────────────────────┘

Step 3: Agent reads its own inbox
┌──────────────────────────────────┐
│ Ashigaru 3 reads ashigaru3.yaml  │
│ → Finds unread messages          │
│ → Processes them                 │
│ → Marks as read                  │
└──────────────────────────────────┘

How the wake-up works:

3-Phase Escalation (v3.2) — If agent doesn't respond to nudge:

Key design choices:

• Message content is never sent through tmux — only a short "you have mail" nudge. The agent reads its own file. This eliminates character corruption and transmission hangs.
• Zero CPU while idle — inotifywait blocks on a kernel event (not a poll loop). CPU usage is 0% between messages.
• Guaranteed delivery — If the file write succeeded, the message is there. No lost messages, no retries needed.

VSCode's Claude Code extension lets you paste screenshots to explain issues. This CLI system provides the same capability:

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

# Just tell the Shogun:
You: "Check the latest screenshot"
You: "Look at the last 2 screenshots"
→ AI instantly reads and analyzes your screen captures

Windows tip: Press Win + Shift + S to take screenshots. Set the save path in settings.yaml for seamless integration.

Use cases:

• Explain UI bugs visually
• Show error messages
• Compare before/after states

Efficient knowledge sharing through a four-layer context system:

This design enables:

• Any Ashigaru can work on any project
• Context persists across agent switches
• Clear separation of concerns
• Knowledge survives across sessions

As agents work, their session context (Layer 4) grows, increasing API costs. /clear wipes session memory and resets costs. Layers 1–3 persist as files, so nothing is lost.

Recovery cost after /clear: ~6,800 tokens (42% improved from v1 — CLAUDE.md YAML conversion + English-only instructions reduced token cost by 70%)

1. CLAUDE.md (auto-loaded) → recognizes itself as part of the Shogun System
2. tmux display-message -t "$TMUX_PANE" -p '#{@agent_id}' → identifies its own number
3. Memory MCP read → restores the Lord's preferences (~700 tokens)
4. Task YAML read → picks up the next assignment (~800 tokens)

The key insight: designing what not to load is what drives cost savings.

All projects use the same 7-section template:

This unified format enables:

• Quick onboarding for any agent
• Consistent information management across all projects
• Easy handoff between Ashigaru workers

Two-way communication between your phone and the Shogun — no SSH, no Tailscale, no server needed.

📱 You (from bed)          🏯 Shogun
    │                          │
    │  "Research React 19"     │
    ├─────────────────────────►│
    │    (ntfy message)        │  → Delegates to Karo → Ashigaru work
    │                          │
    │  "✅ cmd_042 complete"   │
    │◄─────────────────────────┤
    │    (push notification)   │

Setup:

1. Add ntfy_topic: "shogun-yourname" to config/settings.yaml
2. Install the ntfy app on your phone and subscribe to the same topic
3. shutsujin_departure.sh automatically starts the listener — no extra steps

Notification examples:

Free, no account required, no server to maintain. Uses ntfy.sh — an open-source push notification service.

⚠️ Security: Your topic name is your password. Anyone who knows it can read your notifications and send messages to your Shogun. Choose a hard-to-guess name and never share it publicly (e.g., in screenshots, blog posts, or GitHub commits).

Verify it works:

# Send a test notification to your phone
bash scripts/ntfy.sh "Test notification from Shogun 🏯"

If your phone receives the notification, you're all set. If not, check:

• config/settings.yaml has ntfy_topic set (not empty, no extra quotes)
• The ntfy app on your phone is subscribed to the exact same topic name
• Your phone has internet access and ntfy notifications are enabled

Sending commands from your phone:

1. Open the ntfy app on your phone
2. Tap your subscribed topic
3. Type a message (e.g., Research React 19 best practices) and send
4. ntfy_listener.sh receives it, writes to queue/ntfy_inbox.yaml, and wakes the Shogun
5. The Shogun reads the message and processes it through the normal Karo → Ashigaru pipeline

Any text you send becomes a command. Write it like you'd talk to the Shogun — no special syntax needed.

Manual listener start (if not using shutsujin_departure.sh):

# Start the listener in the background
nohup bash scripts/ntfy_listener.sh &>/dev/null &

# Check if it's running
pgrep -f ntfy_listener.sh

# View listener logs (stderr output)
bash scripts/ntfy_listener.sh  # Run in foreground to see logs

The listener automatically reconnects if the connection drops. shutsujin_departure.sh starts it automatically on deployment — you only need manual start if you skipped the deployment script.

Troubleshooting:

Real-world notification screenshots:

Left: Bidirectional phone ↔ Shogun communication · Right: Real-time progress report from Ashigaru

Left: Command completion notification · Right: All 8 Ashigaru completing in parallel

Note: Topic names shown in screenshots are examples. Use your own unique topic name.

Behavioral psychology-driven motivation through your notification feed:

• Streak tracking: Consecutive completion days counted in saytask/streaks.yaml — maintaining streaks leverages loss aversion to sustain momentum
• Eat the Frog 🐸: The hardest task of the day is marked as the "Frog." Completing it triggers a special celebration notification
• Daily progress: 12/12 tasks today — visual completion feedback reinforces the Arbeitslust effect (joy of work-in-progress)

Each tmux pane shows the agent's current task directly on its border:

┌ ashigaru1 (Sonnet) VF requirements ─┬ ashigaru3 (Opus) API research ──────┐
│                                      │                                     │
│  Working on SayTask requirements     │  Researching REST API patterns      │
│                                      │                                     │
├ ashigaru2 (Sonnet) ─────────────────┼ ashigaru4 (Opus) DB schema design ──┤
│                                      │                                     │
│  (idle — waiting for assignment)     │  Designing database schema          │
│                                      │                                     │
└──────────────────────────────────────┴─────────────────────────────────────┘

• Working: ashigaru1 (Sonnet) VF requirements — agent name, model, and task summary
• Idle: ashigaru1 (Sonnet) — model name only, no task
• Updated automatically by the Karo when assigning or completing tasks
• Glance at all 9 panes to instantly know who's doing what

When an Ashigaru completes a task, it shouts a personalized battle cry in the tmux pane — a visual reminder that your army is working hard.

┌ ashigaru1 (Sonnet) ──────────┬ ashigaru2 (Sonnet) ──────────┐
│                               │                               │
│  ⚔️ 足軽1号、先陣切った！     │  🔥 足軽2号、二番槍の意地！   │
│  八刃一志！                   │  八刃一志！                   │
│  ❯                            │  ❯                            │
└───────────────────────────────┴───────────────────────────────┘

How it works:

The Karo writes an echo_message field in each task YAML. After completing all work (report + inbox notification), the Ashigaru runs echo as its final action. The message stays visible above the ❯ prompt.

# In the task YAML (written by Karo)
task:
  task_id: subtask_001
  description: "Create comparison table"
  echo_message: "🔥 足軽1号、先陣を切って参る！八刃一志！"

Shout mode is the default. To disable (saves API tokens on the echo call):

./shutsujin_departure.sh --silent    # No battle cries
./shutsujin_departure.sh             # Default: shout mode (battle cries enabled)

Silent mode sets DISPLAY_MODE=silent as a tmux environment variable. The Karo checks this when writing task YAMLs and omits the echo_message field.

Task management for people who hate task management. Just speak to your phone.

Talk Coding, not Vibe Coding. Speak your tasks, AI organizes them. No typing, no opening apps, no friction.

• Target audience: People who installed Todoist but stopped opening it after 3 days
• Your enemy isn't other apps — it's doing nothing. The competition is inaction, not another productivity tool
• Zero UI. Zero typing. Zero app-opening. Just talk

"Your enemy isn't other apps — it's doing nothing."

1. Install the ntfy app (free, no account needed)
2. Speak to your phone: "dentist tomorrow", "invoice due Friday"
3. AI auto-organizes → morning notification: "here's your day"

 🗣️ "Buy milk, dentist tomorrow, invoice due Friday"
       │
       ▼
 ┌──────────────────┐
 │  ntfy → Shogun   │  AI auto-categorize, parse dates, set priorities
 └────────┬─────────┘
          │
          ▼
 ┌──────────────────┐
 │   tasks.yaml     │  Structured storage (local, never leaves your machine)
 └────────┬─────────┘
          │
          ▼
 📱 Morning notification:
    "Today: 🐸 Invoice due · 🦷 Dentist 3pm · 🛒 Buy milk"

Before (v1)	After (v2)
Raw task dump	Clean, organized daily summary

Note: Topic names shown in screenshots are examples. Use your own unique topic name.

• 🛏️ In bed: "Gotta submit the report tomorrow" — captured before you forget, no fumbling for a notebook
• 🚗 While driving: "Don't forget the estimate for client A" — hands-free, eyes on the road
• 💻 Mid-work: "Oh, need to buy milk" — dump it instantly and stay in flow
• 🌅 Wake up: Today's tasks already waiting in your notifications — no app to open, no inbox to check
• 🐸 Eat the Frog: AI picks your hardest task each morning — ignore it or conquer it first

Q: How is this different from other task apps? A: You never open an app. Just speak. Zero friction. Most task apps fail because people stop opening them. SayTask removes that step entirely.

Q: Can I use SayTask without the full Shogun system? A: SayTask is a feature of Shogun. Shogun also works as a standalone multi-agent development platform — you get both capabilities in one system.

Q: What's the Frog 🐸? A: Every morning, AI picks your hardest task — the one you'd rather avoid. Tackle it first (the "Eat the Frog" method) or ignore it. Your call.

Q: Is it free? A: Everything is free and open-source. ntfy is free too. No account, no server, no subscription.

Q: Where is my data stored? A: Local YAML files on your machine. Nothing is sent to the cloud. Your tasks never leave your device.

Q: What if I say something vague like "that thing for work"? A: AI does its best to categorize and schedule it. You can always refine later — but the point is capturing the thought before it disappears.

Shogun has two complementary task systems:

SayTask handles personal productivity (capture → schedule → remind). The cmd pipeline handles complex work (research, code, multi-step tasks). Both share streak tracking — completing either type of task counts toward your daily streak.

The Shogun serves as the Lord's strategic advisor — not just a task relay. Strategic discussions, research analysis, and policy design are Bloom's Taxonomy Level 4–6 (analysis, evaluation, creation), requiring Thinking mode enabled. For relay-only use, disable with --shogun-no-thinking.

Half the squad runs on the cheaper Sonnet model by default. When it's crunch time, switch to Battle formation with -k (--kessen) for all-Opus maximum capability. The Karo can also promote individual Ashigaru mid-session with /model opus when a specific task demands it.

Tasks are classified using Bloom's Taxonomy to optimize model assignment:

The Karo assigns each subtask a Bloom level and routes it to the appropriate agent tier. This ensures cost-efficient execution: routine work goes to Sonnet, while complex reasoning goes to Opus.

Tasks can declare dependencies on other tasks using blockedBy:

# queue/tasks/ashigaru2.yaml
task:
  task_id: subtask_010b
  blockedBy: ["subtask_010a"]  # Waits for ashigaru1's task to complete
  description: "Integrate the API client built by subtask_010a"

When a blocking task completes, the Karo automatically unblocks dependent tasks and assigns them to available Ashigaru. This prevents idle waiting and enables efficient pipelining of dependent work.

"Don't execute tasks mindlessly. Always keep 'fastest × best output' in mind."

The Shogun System is built on five core principles:

These principles are documented in detail: docs/philosophy.md

1. Instant response: The Shogun delegates immediately, returning control to you
2. Parallel execution: The Karo distributes to multiple Ashigaru simultaneously
3. Single responsibility: Each role is clearly separated — no confusion
4. Scalability: Adding more Ashigaru doesn't break the structure
5. Fault isolation: One Ashigaru failing doesn't affect the others
6. Unified reporting: Only the Shogun communicates with you, keeping information organized

Why use files instead of direct messaging between agents?

Each pane has a @agent_id tmux user option (e.g., karo, ashigaru1). While pane_index can shift when panes are rearranged, @agent_id is set at startup by shutsujin_departure.sh and never changes.

Agent self-identification:

tmux display-message -t "$TMUX_PANE" -p '#{@agent_id}'

The -t "$TMUX_PANE" is required. Omitting it returns the active pane's value (whichever pane you're focused on), causing misidentification.

Model names are stored as @model_name and current task summaries as @current_task — both displayed in the pane-border-format. Even if Claude Code overwrites the pane title, these user options persist.

1. Single writer: Prevents conflicts by limiting updates to one agent
2. Information aggregation: The Karo receives all Ashigaru reports, so it has the full picture
3. Consistency: All updates pass through a single quality gate
4. No interruptions: If the Shogun updated it, it could interrupt the Lord's input

No skills are included out of the box. Skills emerge organically during operation — you approve candidates from dashboard.md as they're discovered.

Invoke skills with /skill-name. Just tell the Shogun: "run /skill-name".

1. Skills are not committed to the repo

Skills in .claude/commands/ are excluded from version control by design:

• Every user's workflow is different
• Rather than imposing generic skills, each user grows their own skill set

2. How skills are discovered

Ashigaru notices a pattern during work
    ↓
Appears in dashboard.md under "Skill Candidates"
    ↓
You (the Lord) review the proposal
    ↓
If approved, instruct the Karo to create the skill

Skills are user-driven. Automatic creation would lead to unmanageable bloat — only keep what you find genuinely useful.

MCP (Model Context Protocol) servers extend Claude's capabilities. Here's how to set them up:

MCP servers give Claude access to external tools:

• Notion MCP → Read and write Notion pages
• GitHub MCP → Create PRs, manage issues
• Memory MCP → Persist memory across sessions

Add MCP servers with these commands:

# 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 - Cross-session long-term memory (recommended!)
# ✅ Auto-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

claude mcp list

All servers should show "Connected" status.

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

You: "Research the top 5 AI coding assistants and compare them"

What happens:
1. Shogun delegates to Karo
2. Karo 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

You: "Prepare a PoC for the project on this Notion page: [URL]"

What happens:
1. Karo fetches Notion content via MCP
2. Ashigaru 2: Lists items to verify
3. Ashigaru 3: Investigates technical feasibility
4. Ashigaru 4: Drafts a PoC plan
5. All results compiled in dashboard.md — meeting prep done

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

# 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.)

# config/settings.yaml
ntfy_topic: "shogun-yourname"

Subscribe to the same topic in the ntfy app on your phone. The listener starts automatically with shutsujin_departure.sh.

The public ntfy.sh instance requires no authentication — the setup above is all you need.

If you run a self-hosted ntfy server with access control enabled, configure authentication:

# 1. Copy the sample config
cp config/ntfy_auth.env.sample config/ntfy_auth.env

# 2. Edit with your credentials (choose one method)

Priority: Token > Basic > None. If neither is set, no auth headers are sent (backward compatible).

config/ntfy_auth.env is excluded from git. See config/ntfy_auth.env.sample for details.

┌─────────────────────────────────────────────────────────────────────┐
│                    First-Time Setup (run once)                       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  install.bat (Windows)                                              │
│      │                                                              │
│      ├── Check/guide WSL2 installation                              │
│      └── Check/guide Ubuntu installation                            │
│                                                                     │
│  first_setup.sh (run manually in Ubuntu/WSL)                        │
│      │                                                              │
│      ├── Check/install tmux                                         │
│      ├── Check/install Node.js v20+ (via nvm)                      │
│      ├── Check/install Claude Code CLI (native version)             │
│      │       ※ Proposes migration if npm version detected           │
│      └── Configure Memory MCP server                                │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│                    Daily Startup (run every day)                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  shutsujin_departure.sh                                             │
│      │                                                              │
│      ├──▶ Create tmux sessions                                      │
│      │         • "shogun" session (1 pane)                          │
│      │         • "multiagent" session (9 panes, 3x3 grid)          │
│      │                                                              │
│      ├──▶ Reset queue files and dashboard                           │
│      │                                                              │
│      └──▶ Launch Claude Code on all agents                          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

# Default: Full startup (tmux sessions + Claude Code launch)
./shutsujin_departure.sh

# Session setup only (no Claude Code launch)
./shutsujin_departure.sh -s
./shutsujin_departure.sh --setup-only

# Clean task queues (preserves command history)
./shutsujin_departure.sh -c
./shutsujin_departure.sh --clean

# Battle formation: All Ashigaru on Opus (max capability, higher cost)
./shutsujin_departure.sh -k
./shutsujin_departure.sh --kessen

# Silent mode: Disable battle cries (saves API tokens on echo calls)
./shutsujin_departure.sh -S
./shutsujin_departure.sh --silent

# Full startup + open Windows Terminal tabs
./shutsujin_departure.sh -t
./shutsujin_departure.sh --terminal

# Shogun relay-only mode: Disable Shogun's thinking (cost savings)
./shutsujin_departure.sh --shogun-no-thinking

# Show help
./shutsujin_departure.sh -h
./shutsujin_departure.sh --help

./shutsujin_departure.sh          # Launch everything
tmux attach-session -t shogun     # Connect and give commands

./shutsujin_departure.sh -s       # Create sessions only

# Manually launch Claude Code on specific agents
tmux send-keys -t shogun:0 'claude --dangerously-skip-permissions' Enter
tmux send-keys -t multiagent:0.0 'claude --dangerously-skip-permissions' Enter

# Kill existing sessions
tmux kill-session -t shogun
tmux kill-session -t multiagent

# Fresh start
./shutsujin_departure.sh

alias csst='cd /mnt/c/tools/multi-agent-shogun && ./shutsujin_departure.sh'
alias css='tmux attach-session -t shogun'      # Connect to Shogun
alias csm='tmux attach-session -t multiagent'  # Connect to Karo + Ashigaru

multi-agent-shogun/
│
│  ┌──────────────── Setup Scripts ────────────────────┐
├── install.bat               # Windows: First-time setup
├── first_setup.sh            # Ubuntu/Mac: First-time setup
├── shutsujin_departure.sh    # Daily deployment (auto-loads instructions)
│  └──────────────────────────────────────────────────┘
│
├── instructions/             # Agent behavior definitions
│   ├── shogun.md             # Shogun instructions
│   ├── karo.md               # Karo instructions
│   ├── ashigaru.md           # Ashigaru instructions
│   └── cli_specific/         # CLI-specific tool descriptions
│       ├── claude_tools.md   # Claude Code tools & features
│       └── copilot_tools.md  # GitHub Copilot CLI tools & features
│
├── lib/
│   ├── cli_adapter.sh        # Multi-CLI adapter (Claude/Codex/Copilot/Kimi)
│   └── ntfy_auth.sh          # ntfy authentication helper
│
├── scripts/                  # Utility scripts
│   ├── inbox_write.sh        # Write messages to agent inbox
│   ├── inbox_watcher.sh      # Watch inbox changes via inotifywait
│   ├── ntfy.sh               # Send push notifications to phone
│   └── ntfy_listener.sh      # Stream incoming messages from phone
│
├── config/
│   ├── settings.yaml         # Language, ntfy, and other settings
│   ├── ntfy_auth.env.sample  # ntfy authentication template (self-hosted)
│   └── projects.yaml         # Project registry
│
├── projects/                 # Project details (excluded from git, contains confidential info)
│   └── <project_id>.yaml    # Full info per project (clients, tasks, Notion links, etc.)
│
├── queue/                    # Communication files
│   ├── shogun_to_karo.yaml   # Shogun → Karo commands
│   ├── ntfy_inbox.yaml       # Incoming messages from phone (ntfy)
│   ├── inbox/                # Per-agent inbox files
│   │   ├── shogun.yaml       # Messages to Shogun
│   │   ├── karo.yaml         # Messages to Karo
│   │   └── ashigaru{1-8}.yaml # Messages to each Ashigaru
│   ├── tasks/                # Per-worker task files
│   └── reports/              # Worker reports
│
├── saytask/                  # Behavioral psychology-driven motivation
│   └── streaks.yaml          # Streak tracking and daily progress
│
├── templates/                # Report and context templates
│   ├── integ_base.md         # Integration: base template
│   ├── integ_fact.md         # Integration: fact-finding
│   ├── integ_proposal.md     # Integration: proposal
│   ├── integ_code.md         # Integration: code review
│   ├── integ_analysis.md     # Integration: analysis
│   └── context_template.md   # Universal 7-section project context
│
├── memory/                   # Memory MCP persistent storage
├── dashboard.md              # Real-time status board
└── CLAUDE.md                 # System instructions (auto-loaded)

This system manages not just its own development, but all white-collar tasks. Project folders can be located outside this repository.

config/projects.yaml          # Project list (ID, name, path, status only)
projects/<project_id>.yaml    # Full details for each project

• config/projects.yaml: A summary list of what projects exist
• projects/<id>.yaml: Complete details (client info, contracts, tasks, related files, Notion pages, etc.)
• Project files (source code, documents, etc.) live in the external folder specified by path
• projects/ is excluded from git (contains confidential client information)

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

# projects/client_x.yaml
id: client_x
client:
  name: "Client X"
  company: "X Corporation"
contract:
  fee: "monthly"
current_tasks:
  - id: task_001
    name: "System Architecture Review"
    status: in_progress

This separation lets the Shogun System coordinate across multiple external projects while keeping project details out of version control.

# Re-run first_setup.sh
./first_setup.sh

# If npm version is detected:
# ⚠️ npm version of Claude Code CLI detected (officially deprecated)
# Install native version? [Y/n]:

# After selecting Y, uninstall npm version:
npm uninstall -g @anthropic-ai/claude-code

ToolSearch("select:mcp__memory__read_graph")
mcp__memory__read_graph()

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

# Method 1: Run claude directly in the pane
claude --model opus --dangerously-skip-permissions

# Method 2: Karo force-restarts via respawn-pane (also fixes nesting)
tmux respawn-pane -t shogun:0.0 -k 'claude --model opus --dangerously-skip-permissions'

first_setup.sh automatically configures set -g mouse on in ~/.tmux.conf, enabling intuitive mouse control:

Even if you're not comfortable with keyboard shortcuts, you can switch, scroll, and resize panes using just the mouse.

Shogun is no longer Claude-only. Mix and match 4 AI coding CLIs in a single army.

• Multi-CLI as first-class architecture — lib/cli_adapter.sh dynamically selects CLI per agent. Change one line in settings.yaml to swap any worker between Claude Code, Codex, Copilot, or Kimi
• OpenAI Codex CLI integration — GPT-5.3-codex with --dangerously-bypass-approvals-and-sandbox for true autonomous execution. --no-alt-screen makes agent activity visible in tmux
• CLI bypass flag discovery — --full-auto is NOT fully automatic (it's -a on-request). Documented the correct flags for all 4 CLIs
• Hybrid architecture — Command layer (Shogun + Karo) stays on Claude Code for Memory MCP and mailbox integration. Worker layer (Ashigaru) is CLI-agnostic
• Community-contributed CLI adapters — Thanks to @yuto-ts (cli_adapter.sh), @circlemouth (Codex support), @koba6316 (task routing)

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