{"id":44309489,"url":"https://github.com/yohey-w/multi-agent-shogun","last_synced_at":"2026-04-19T09:02:25.283Z","repository":{"id":334845469,"uuid":"1141706975","full_name":"yohey-w/multi-agent-shogun","owner":"yohey-w","description":"Samurai-inspired multi-agent system for Claude Code. Orchestrate parallel AI tasks via tmux with shogun → karo → ashigaru hierarchy.","archived":false,"fork":false,"pushed_at":"2026-03-24T10:36:00.000Z","size":40170,"stargazers_count":1120,"open_issues_count":7,"forks_count":247,"subscribers_count":11,"default_branch":"main","last_synced_at":"2026-03-25T13:12:35.851Z","etag":null,"topics":["ai-agent","anthropic","automation","claude-code","llm","multi-agent","parallel-processing","samurai","shogun","tmux"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yohey-w.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-25T09:29:19.000Z","updated_at":"2026-03-25T13:08:25.000Z","dependencies_parsed_at":"2026-02-20T03:02:39.937Z","dependency_job_id":null,"html_url":"https://github.com/yohey-w/multi-agent-shogun","commit_stats":null,"previous_names":["yohey-w/multi-agent-shogun"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/yohey-w/multi-agent-shogun","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yohey-w%2Fmulti-agent-shogun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yohey-w%2Fmulti-agent-shogun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yohey-w%2Fmulti-agent-shogun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yohey-w%2Fmulti-agent-shogun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yohey-w","download_url":"https://codeload.github.com/yohey-w/multi-agent-shogun/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yohey-w%2Fmulti-agent-shogun/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31305971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","automation","claude-code","llm","multi-agent","parallel-processing","samurai","shogun","tmux"],"created_at":"2026-02-11T04:00:16.660Z","updated_at":"2026-04-19T09:02:25.259Z","avatar_url":"https://github.com/yohey-w.png","language":"Shell","funding_links":["https://github.com/sponsors/yohey-w"],"categories":["Shell","Multi-Agent Swarms","📚 Tools","Multi-Agent Orchestration"],"sub_categories":["🌟 What You'll Find Here:"],"readme":"\u003cdiv align=\"center\"\u003e\n\n# multi-agent-shogun\n\n**Command your AI army like a feudal warlord.**\n\nRun 10 AI coding agents in parallel — **Claude Code, OpenAI Codex, GitHub Copilot, Kimi Code** — orchestrated through a samurai-inspired hierarchy with zero coordination overhead.\n\n**Talk Coding, not Vibe Coding. Speak to your phone, AI executes.**\n\n[![GitHub Stars](https://img.shields.io/github/stars/yohey-w/multi-agent-shogun?style=social)](https://github.com/yohey-w/multi-agent-shogun)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![v3.5 Dynamic Model Routing](https://img.shields.io/badge/v3.5-Dynamic_Model_Routing-ff6600?style=flat-square\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiI+PHRleHQgeD0iMCIgeT0iMTIiIGZvbnQtc2l6ZT0iMTIiPuKalTwvdGV4dD48L3N2Zz4=)](https://github.com/yohey-w/multi-agent-shogun)\n[![Shell](https://img.shields.io/badge/Shell%2FBash-100%25-green)]()\n\n[English](README.md) | [日本語](README_ja.md)\n\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/screenshots/hero/latest-translucent-20260210-190453.png\" alt=\"Latest translucent command session in the Shogun pane\" width=\"940\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/screenshots/hero/latest-translucent-20260208-084602.png\" alt=\"Quick natural-language command in the Shogun pane\" width=\"420\"\u003e\n  \u003cimg src=\"images/company-creed-all-panes.png\" alt=\"Karo and Ashigaru panes reacting in parallel\" width=\"520\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003ci\u003eOne Karo (manager) coordinating 7 Ashigaru (workers) + 1 Gunshi (strategist) — real session, no mock data.\u003c/i\u003e\u003c/p\u003e\n\n---\n\n## Quick Start\n\n**Requirements:** tmux, bash 4+, at least one of: [Claude Code](https://claude.ai/code) / Codex / Copilot / Kimi\n\n```bash\ngit clone https://github.com/yohey-w/multi-agent-shogun\ncd multi-agent-shogun\nbash first_setup.sh                        # one-time setup: config, dependencies, MCP\nsource ~/.bashrc                           # reload PATH\nclaude --dangerously-skip-permissions      # first run only: OAuth + accept Bypass Permissions → /exit\nbash shutsujin_departure.sh                # launch all agents\n```\n\n\u003e For full install steps (incl. Windows) and the first-30-minutes walkthrough, see [🚀 Quick Start](#-quick-start) and the basic usage section below.\n\nType a command in the Shogun pane:\n\n\u003e \"Build a REST API for user authentication\"\n\nShogun delegates → Karo breaks it down → 7 Ashigaru execute in parallel.\nYou watch the dashboard. That's it.\n\n\u003e **Want to go deeper?** The rest of this README covers architecture, configuration, memory design, and multi-CLI setup.\n\n---\n\n## What is this?\n\n**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**.\n\n**Why use it?**\n- One command spawns 7 AI workers + 1 strategist executing in parallel\n- Zero wait time — give your next order while tasks run in the background\n- AI remembers your preferences across sessions (Memory MCP)\n- Real-time progress on a dashboard\n\n```\n        You (上様 / The Lord)\n             │\n             ▼  Give orders\n      ┌─────────────┐\n      │   SHOGUN    │  ← Receives your command, delegates instantly\n      └──────┬──────┘\n             │  YAML + tmux\n      ┌──────▼──────┐\n      │    KARO     │  ← Distributes tasks to workers\n      └──────┬──────┘\n             │\n    ┌─┬─┬─┬─┴─┬─┬─┬─┬────────┐\n    │1│2│3│4│5│6│7│ GUNSHI │  ← 7 workers + 1 strategist\n    └─┴─┴─┴─┴─┴─┴─┴────────┘\n       ASHIGARU      軍師\n```\n\n---\n\n## Why Shogun?\n\nMost multi-agent frameworks burn API tokens on coordination. Shogun doesn't.\n\n| | Claude Code `Task` tool | Claude Code Agent Teams | LangGraph | CrewAI | **multi-agent-shogun** |\n|---|---|---|---|---|---|\n| **Architecture** | Subagents inside one process | Team lead + teammates (JSON mailbox) | Graph-based state machine | Role-based agents | Feudal hierarchy via tmux |\n| **Parallelism** | Sequential (one at a time) | Multiple independent sessions | Parallel nodes (v0.2+) | Limited | **8 independent agents** |\n| **Coordination cost** | API calls per Task | Token-heavy (each teammate = separate context) | API + infra (Postgres/Redis) | API + CrewAI platform | **Zero** (YAML + tmux) |\n| **Multi-CLI** | Claude Code only | Claude Code only | Any LLM API | Any LLM API | **4 CLIs** (Claude/Codex/Copilot/Kimi) |\n| **Observability** | Claude logs only | tmux split-panes or in-process | LangSmith integration | OpenTelemetry | **Live tmux panes** + dashboard |\n| **Skill discovery** | None | None | None | None | **Bottom-up auto-proposal** |\n| **Setup** | Built into Claude Code | Built-in (experimental) | Heavy (infra required) | pip install | Shell scripts |\n\n### What makes this different\n\n**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.\n\n**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.\n\n**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.\n\n---\n\n## Why CLI (Not API)?\n\nMost AI coding tools charge per token. Running 8 Opus-grade agents through the API costs **$100+/hour**. CLI subscriptions flip this:\n\n| | API (Per-Token) | CLI (Flat-Rate) |\n|---|---|---|\n| **8 agents × Opus** | ~$100+/hour | ~$200/month |\n| **Cost predictability** | Unpredictable spikes | Fixed monthly bill |\n| **Usage anxiety** | Every token counts | Unlimited |\n| **Experimentation budget** | Constrained | Deploy freely |\n\n**\"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.\n\n### Multi-CLI Support\n\nShogun isn't locked to one vendor. The system supports 4 CLI tools, each with unique strengths:\n\n| CLI | Key Strength | Default Model |\n|-----|-------------|---------------|\n| **Claude Code** | Battle-tested tmux integration, Memory MCP, dedicated file tools (Read/Write/Edit/Glob/Grep) | Claude Sonnet 4.6 |\n| **OpenAI Codex** | Sandbox execution, JSONL structured output, `codex exec` headless mode, **per-model `--model` flag** | gpt-5.3-codex / **gpt-5.3-codex-spark** |\n| **GitHub Copilot** | Built-in GitHub MCP, 4 specialized agents (Explore/Task/Plan/Code-review), `/delegate` to coding agent | Claude Sonnet 4.6 |\n| **Kimi Code** | Free tier available, strong multilingual support | Kimi k2 |\n\nA unified instruction build system generates CLI-specific instruction files from shared templates:\n\n```\ninstructions/\n├── common/              # Shared rules (all CLIs)\n├── cli_specific/        # CLI-specific tool descriptions\n│   ├── claude_tools.md  # Claude Code tools \u0026 features\n│   └── copilot_tools.md # GitHub Copilot CLI tools \u0026 features\n└── roles/               # Role definitions (shogun, karo, ashigaru)\n    ↓ build\nCLAUDE.md / AGENTS.md / copilot-instructions.md  ← Generated per CLI\n```\n\nOne source of truth, zero sync drift. Change a rule once, all CLIs get it.\n\n---\n\n## Bottom-Up Skill Discovery\n\nThis is the feature no other framework has.\n\nAs 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.\n\n```\nAshigaru finishes a task\n    ↓\nNotices: \"I've done this pattern 3 times across different projects\"\n    ↓\nReports in YAML:  skill_candidate:\n                     found: true\n                     name: \"api-endpoint-scaffold\"\n                     reason: \"Same REST scaffold pattern used in 3 projects\"\n    ↓\nAppears in dashboard.md → You approve → Skill created in .claude/commands/\n    ↓\nAny agent can now invoke /api-endpoint-scaffold\n```\n\nSkills grow organically from real work — not from a predefined template library. Your skill set becomes a reflection of **your** workflow.\n\n---\n\n## Quick Start\n\n### Windows (WSL2)\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"60\"\u003e\n\n**Step 1**\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n📥 **Download the repository**\n\n[Download ZIP](https://github.com/yohey-w/multi-agent-shogun/archive/refs/heads/main.zip) and extract to `C:\\tools\\multi-agent-shogun`\n\n*Or use git:* `git clone https://github.com/yohey-w/multi-agent-shogun.git C:\\tools\\multi-agent-shogun`\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n**Step 2**\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n🖱️ **Run `install.bat`**\n\nRight-click → \"Run as Administrator\" (if WSL2 is not installed). Sets up WSL2 + Ubuntu automatically.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n**Step 3**\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n🐧 **Open Ubuntu and run** (first time only)\n\n```bash\ncd /mnt/c/tools/multi-agent-shogun\n./first_setup.sh\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n**Step 4**\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n✅ **Deploy!**\n\n```bash\n./shutsujin_departure.sh\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### First-time only: Authentication\n\nAfter `first_setup.sh`, run these commands once to authenticate:\n\n```bash\n# 1. Apply PATH changes\nsource ~/.bashrc\n\n# 2. OAuth login + Bypass Permissions approval (one command)\nclaude --dangerously-skip-permissions\n#    → Browser opens → Log in with Anthropic account → Return to CLI\n#    → \"Bypass Permissions\" prompt appears → Select \"Yes, I accept\" (↓ to option 2, Enter)\n#    → Type /exit to quit\n```\n\nThis saves credentials to `~/.claude/` — you won't need to do it again.\n\n#### Daily startup\n\nOpen an **Ubuntu terminal** (WSL) and run:\n\n```bash\ncd /mnt/c/tools/multi-agent-shogun\n./shutsujin_departure.sh\n```\n\n### 📱 Mobile Access — Dedicated Android App (Recommended)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"android/screenshots/01_shogun_terminal.png\" alt=\"Shogun Terminal\" width=\"200\"\u003e\n  \u003cimg src=\"android/screenshots/02_agents_grid.png\" alt=\"Agents Grid\" width=\"200\"\u003e\n  \u003cimg src=\"android/screenshots/03_dashboard.png\" alt=\"Dashboard\" width=\"200\"\u003e\n\u003c/p\u003e\n\nMonitor and command 10 AI agents from your phone with the dedicated Android companion app.\n\n| Feature | Description |\n|---------|-------------|\n| **Shogun Terminal** | SSH terminal + voice input + special key bar (C-c, C-b, Tab, etc.) |\n| **Agents Grid** | 9-pane simultaneous monitoring. Tap to expand fullscreen + send commands |\n| **Dashboard** | Renders dashboard.md with full table text selection/copy |\n| **Rate Limit** | Tap the FAB on the Agents tab to check Claude Max 5h/7d usage with progress bars |\n| **Voice Input** | Japanese continuous recognition via Google Speech API — higher accuracy than phone keyboard voice |\n| **Screenshot Share** | Share images via Android share menu → SFTP transfer to server |\n\n\u003e **Note:** Android only for now. No iOS version — the developer doesn't own an iPhone. If there's demand, please open an [Issue](https://github.com/yohey-w/multi-agent-shogun/issues). PRs welcome!\n\n#### Setup\n\n**Prerequisites:**\n- Shogun system running on WSL2 (or Linux server)\n- SSH server started (`sudo service ssh start`)\n- Phone and server on same network (LAN or [Tailscale](https://tailscale.com/))\n\n**Steps:**\n\n1. **Install APK**\n   1. Download [`android/release/multi-agent-shogun.apk`](android/release/multi-agent-shogun.apk) on your phone (open the file on GitHub → \"Download raw file\")\n   2. Tap the download notification → \"Install\"\n   3. If \"Unknown sources\" warning appears → \"Settings\" → enable \"Allow from this source\" for your browser → go back → \"Install\"\n   4. Done → \"Open\"\n\n2. **Configure SSH** (Settings tab)\n\n   | Field | Example | Description |\n   |-------|---------|-------------|\n   | SSH Host | `100.xxx.xxx.xxx` | Server IP (e.g., Tailscale IP) |\n   | SSH Port | `22` | Usually 22 |\n   | SSH User | `your_username` | SSH login username |\n   | SSH Key Path | `/data/data/.../id_ed25519` | Private key path on phone (*1) |\n   | SSH Password | `****` | Use if no key available |\n   | Project Path | `/mnt/c/tools/multi-agent-shogun` | Server-side project directory |\n   | Shogun Session | `shogun` | tmux session name for Shogun |\n   | Agent Session | `multiagent` | tmux session name for agents |\n\n   *1 Transfer your private key to the phone, or use password authentication\n\n3. **Save → Switch to Shogun tab** → auto-connects\n\n**Using Tailscale (connect from anywhere):**\n\n```bash\n# Server-side (WSL2)\ncurl -fsSL https://tailscale.com/install.sh | sh\nsudo tailscaled \u0026\nsudo tailscale up --authkey tskey-auth-XXXXXXXXXXXX\nsudo service ssh start\n```\n\nInstall 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.\n\n**With ntfy notifications:**\n\nSee [ntfy setup section](#-8-phone-notifications-ntfy) for push notifications from Karo on task completion.\n\n\u003cdetails\u003e\n\u003csummary\u003e📟 \u003cb\u003eTermux Method (without the Android app)\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\nSSH via Termux also works. More limited than the dedicated app, but requires no APK sideloading.\n\n**Requirements (all free):**\n\n| Name | In a nutshell | Role |\n|------|--------------|------|\n| [Tailscale](https://tailscale.com/) | A road to your home from anywhere | Connect to your home PC from anywhere |\n| SSH | The feet that walk that road | Log into your home PC through Tailscale |\n| [Termux](https://termux.dev/) | A black screen on your phone | Required to use SSH — just install it |\n\n**Setup:**\n\n1. Install Tailscale on both WSL and your phone\n2. In WSL (auth key method — browser not needed):\n   ```bash\n   curl -fsSL https://tailscale.com/install.sh | sh\n   sudo tailscaled \u0026\n   sudo tailscale up --authkey tskey-auth-XXXXXXXXXXXX\n   sudo service ssh start\n   ```\n3. In Termux on your phone:\n   ```sh\n   pkg update \u0026\u0026 pkg install openssh\n   ssh youruser@your-tailscale-ip\n   css    # Connect to Shogun\n   ```\n4. Open a new Termux window (+ button) for workers:\n   ```sh\n   ssh youruser@your-tailscale-ip\n   csm    # See all 9 panes\n   ```\n\n**Disconnect:** Just swipe the Termux window closed. tmux sessions survive — agents keep working.\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e🐧 \u003cb\u003eLinux / macOS\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n### First-time setup\n\n```bash\n# 1. Clone\ngit clone https://github.com/yohey-w/multi-agent-shogun.git ~/multi-agent-shogun\ncd ~/multi-agent-shogun\n\n# 2. Make scripts executable\nchmod +x *.sh\n\n# 3. Run first-time setup\n./first_setup.sh\n```\n\n### Daily startup\n\n```bash\ncd ~/multi-agent-shogun\n./shutsujin_departure.sh\n```\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e❓ \u003cb\u003eWhat is WSL2? Why is it needed?\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n### About WSL2\n\n**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.\n\n### If you don't have WSL2 yet\n\nNo problem! Running `install.bat` will:\n1. Check if WSL2 is installed (auto-install if not)\n2. Check if Ubuntu is installed (auto-install if not)\n3. Guide you through next steps (running `first_setup.sh`)\n\n**Quick install command** (run PowerShell as Administrator):\n```powershell\nwsl --install\n```\n\nThen restart your computer and run `install.bat` again.\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e📋 \u003cb\u003eScript Reference\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n| Script | Purpose | When to run |\n|--------|---------|-------------|\n| `install.bat` | Windows: WSL2 + Ubuntu setup | First time only |\n| `first_setup.sh` | Install tmux, Node.js, Claude Code CLI + Memory MCP config | First time only |\n| `shutsujin_departure.sh` | Create tmux sessions + launch CLI + load instructions + start ntfy listener | Daily |\n| `scripts/switch_cli.sh` | Live switch agent CLI/model (settings.yaml → /exit → relaunch) | As needed |\n\n### What `install.bat` does automatically:\n- ✅ Checks if WSL2 is installed (guides you if not)\n- ✅ Checks if Ubuntu is installed (guides you if not)\n- ✅ Shows next steps (how to run `first_setup.sh`)\n\n### What `shutsujin_departure.sh` does:\n- ✅ Creates tmux sessions (shogun + multiagent)\n- ✅ Launches Claude Code on all agents\n- ✅ Auto-loads instruction files for each agent\n- ✅ Resets queue files for a fresh state\n- ✅ Starts ntfy listener for phone notifications (if configured)\n\n**After running, all agents are ready to receive commands!**\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e🔧 \u003cb\u003eManual Requirements\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\nIf you prefer to install dependencies manually:\n\n| Requirement | Installation | Notes |\n|-------------|-------------|-------|\n| WSL2 + Ubuntu | `wsl --install` in PowerShell | Windows only |\n| Set Ubuntu as default | `wsl --set-default Ubuntu` | Required for scripts to work |\n| tmux | `sudo apt install tmux` | Terminal multiplexer |\n| Node.js v20+ | `nvm install 20` | Required for MCP servers |\n| Claude Code CLI | `curl -fsSL https://claude.ai/install.sh \\| bash` | Official Anthropic CLI (native version recommended; npm version deprecated) |\n\n\u003c/details\u003e\n\n---\n\n### After Setup\n\nWhichever option you chose, **10 AI agents** are automatically launched:\n\n| Agent | Role | Count |\n|-------|------|-------|\n| 🏯 Shogun | Supreme commander — receives your orders | 1 |\n| 📋 Karo | Manager — distributes tasks, quality checks | 1 |\n| ⚔️ Ashigaru | Workers — execute implementation tasks in parallel | 7 |\n| 🧠 Gunshi | Strategist — handles analysis, evaluation, and design | 1 |\n\nTwo tmux sessions are created:\n- `shogun` — connect here to give commands\n- `multiagent` — Karo, Ashigaru, and Gunshi running in the background\n\n---\n\n## How It Works\n\n### Step 1: Connect to the Shogun\n\nAfter running `shutsujin_departure.sh`, all agents automatically load their instructions and are ready.\n\nOpen a new terminal and connect:\n\n```bash\ntmux attach-session -t shogun\n```\n\n### Step 2: Give your first order\n\nThe Shogun is already initialized — just give a command:\n\n```\nResearch the top 5 JavaScript frameworks and create a comparison table\n```\n\nThe Shogun will:\n1. Write the task to a YAML file\n2. Notify the Karo (manager)\n3. Return control to you immediately — no waiting!\n\nMeanwhile, the Karo distributes tasks to Ashigaru workers for parallel execution.\n\n### Step 3: Check progress\n\nOpen `dashboard.md` in your editor for a real-time status view:\n\n```markdown\n## In Progress\n| Worker | Task | Status |\n|--------|------|--------|\n| Ashigaru 1 | Research React | Running |\n| Ashigaru 2 | Research Vue | Running |\n| Ashigaru 3 | Research Angular | Completed |\n```\n\n### Detailed flow\n\n```\nYou: \"Research the top 5 MCP servers and create a comparison table\"\n```\n\nThe Shogun writes the task to `queue/shogun_to_karo.yaml` and wakes the Karo. Control returns to you immediately.\n\nThe Karo breaks the task into subtasks:\n\n| Worker | Assignment |\n|--------|-----------|\n| Ashigaru 1 | Research Notion MCP |\n| Ashigaru 2 | Research GitHub MCP |\n| Ashigaru 3 | Research Playwright MCP |\n| Ashigaru 4 | Research Memory MCP |\n| Ashigaru 5 | Research Sequential Thinking MCP |\n\nAll 5 Ashigaru research simultaneously. You can watch them work in real time:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/company-creed-all-panes.png\" alt=\"Ashigaru agents working in parallel across tmux panes\" width=\"900\"\u003e\n\u003c/p\u003e\n\nResults appear in `dashboard.md` as they complete.\n\n---\n\n## Key Features\n\n### ⚡ 1. Parallel Execution\n\nOne command spawns up to 8 parallel tasks:\n\n```\nYou: \"Research 5 MCP servers\"\n→ 5 Ashigaru start researching simultaneously\n→ Results in minutes, not hours\n```\n\n### 🔄 2. Non-Blocking Workflow\n\nThe Shogun delegates instantly and returns control to you:\n\n```\nYou: Command → Shogun: Delegates → You: Give next command immediately\n                                       ↓\n                       Workers: Execute in background\n                                       ↓\n                       Dashboard: Shows results\n```\n\nNo waiting for long tasks to finish.\n\n### 🧠 3. Cross-Session Memory (Memory MCP)\n\nYour AI remembers your preferences:\n\n```\nSession 1: Tell it \"I prefer simple approaches\"\n            → Saved to Memory MCP\n\nSession 2: AI loads memory on startup\n            → Stops suggesting complex solutions\n```\n\n### 📡 4. Event-Driven Communication (Zero Polling)\n\nAgents talk to each other by writing YAML files — like passing notes. **No polling loops, no wasted API calls.**\n\n```\nKaro wants to wake Ashigaru 3:\n\nStep 1: Write the message          Step 2: Wake the agent up\n┌──────────────────────┐           ┌──────────────────────────┐\n│ inbox_write.sh       │           │ inbox_watcher.sh         │\n│                      │           │                          │\n│ Writes full message  │  file     │ Detects file change      │\n│ to ashigaru3.yaml    │──change──▶│ (inotifywait, not poll)  │\n│ with flock (no race) │           │                          │\n└──────────────────────┘           │ Wakes agent via:         │\n                                   │  1. Self-watch (skip)    │\n                                   │  2. tmux send-keys       │\n                                   │     (short nudge only)   │\n                                   └──────────────────────────┘\n\nStep 3: Agent reads its own inbox\n┌──────────────────────────────────┐\n│ Ashigaru 3 reads ashigaru3.yaml  │\n│ → Finds unread messages          │\n│ → Processes them                 │\n│ → Marks as read                  │\n└──────────────────────────────────┘\n```\n\n**How the wake-up works:**\n\n| Priority | Method | What happens | When used |\n|----------|--------|-------------|-----------|\n| 1st | **Self-Watch** | Agent watches its own inbox file — wakes itself, no nudge needed | Agent has its own `inotifywait` running |\n| 2nd | **Stop Hook** | Claude Code agents check inbox at turn end via `.claude/settings.json` Stop hook | Claude Code agents only |\n| 3rd | **tmux send-keys** | Sends short nudge via `tmux send-keys` (text and Enter sent separately for Codex CLI compatibility) | Fallback — disabled in ASW Phase 2+ |\n\n**Agent Self-Watch (ASW) Phases** — Controls how aggressively the system uses `tmux send-keys` nudges:\n\n| ASW Phase | Nudge behavior | Delivery method | When to use |\n|-----------|---------------|-----------------|-------------|\n| **Phase 1** | Normal nudges enabled | self-watch + send-keys | Initial setup, mixed CLI environments |\n| **Phase 2** | **Busy → suppressed, Idle → nudge** | busy: stop hook delivers at turn end. idle: nudge (unavoidable) | Claude Code agents with stop hook (recommended) |\n| **Phase 3** | `FINAL_ESCALATION_ONLY` | send-keys only as last-resort recovery | Fully stable environments |\n\nPhase 2 uses the idle flag file (`/tmp/shogun_idle_{agent}`) to distinguish busy vs idle agents. The Stop hook creates/removes this flag at turn boundaries. This eliminates nudge interruptions during active work while still waking idle agents.\n\n\u003e **Why can't nudges be fully eliminated?** Claude Code's Stop hook only fires at turn end. An idle agent (sitting at the prompt) has no turn ending, so there's no hook to trigger inbox checks. A future `Notification` hook with `idle_prompt` blocking support or a periodic timer hook could solve this.\n\nConfigure in `config/settings.yaml`:\n```yaml\nasw_phase: 2   # Recommended for Claude Code setups\n```\n\nOr set the default directly in `scripts/inbox_watcher.sh` (`ASW_PHASE` variable). Restart inbox_watcher processes after changing.\n\n**3-Phase Escalation (v3.2)** — If agent doesn't respond:\n\n| Phase | Timing | Action |\n|-------|--------|--------|\n| Phase 1 | 0-2 min | Standard nudge (`inbox3` text + Enter) — *skipped for busy agents in ASW Phase 2+* |\n| Phase 2 | 2-4 min | Escape×2 + C-c to reset cursor, then nudge |\n| Phase 3 | 4+ min | Send `/clear` to force session reset (max once per 5 min) |\n\n**Key design choices:**\n- **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.\n- **Zero CPU while idle** — `inotifywait` blocks on a kernel event (not a poll loop). CPU usage is 0% between messages.\n- **Guaranteed delivery** — If the file write succeeded, the message is there. No lost messages, no retries needed.\n\n### 📊 5. Agent Status Check\n\nSee which agents are busy or idle — instantly, from one command:\n\n```bash\n# Project mode: full status with task/inbox info\nbash scripts/agent_status.sh\n\n# Standalone mode: works with any tmux session\nbash scripts/agent_status.sh --session mysession --lang en\n```\n\n**Project mode output:**\n```\nAgent      CLI     Pane      Task ID                                    Status     Inbox\n---------- ------- --------- ------------------------------------------ ---------- -----\nkaro       claude  待機中    ---                                        ---        0\nashigaru1  codex   稼働中    subtask_042a_research                      assigned   0\nashigaru2  codex   待機中    subtask_042b_review                        done       0\ngunshi     claude  稼働中    subtask_042c_analysis                      assigned   0\n```\n\n**Standalone mode output** (no project config needed):\n```\nPane                           State      Agent ID\n------------------------------ ---------- ----------\nmultiagent:agents.0            IDLE       karo\nmultiagent:agents.1            BUSY       ashigaru1\nmultiagent:agents.8            BUSY       gunshi\n```\n\nDetection works for both **Claude Code** and **Codex CLI** by checking CLI-specific prompt/spinner patterns in the bottom 5 lines of each tmux pane. The detection logic lives in `lib/agent_status.sh` — source it in your own scripts:\n\n```bash\nsource lib/agent_status.sh\nagent_is_busy_check \"multiagent:agents.3\" \u0026\u0026 echo \"busy\" || echo \"idle\"\n```\n\n### 📸 6. Screenshot Integration\n\nVSCode's Claude Code extension lets you paste screenshots to explain issues. This CLI system provides the same capability:\n\n```yaml\n# Set your screenshot folder in config/settings.yaml\nscreenshot:\n  path: \"/mnt/c/Users/YourName/Pictures/Screenshots\"\n```\n\n```\n# Just tell the Shogun:\nYou: \"Check the latest screenshot\"\nYou: \"Look at the last 2 screenshots\"\n→ AI instantly reads and analyzes your screen captures\n```\n\n**Windows tip:** Press `Win + Shift + S` to take screenshots. Set the save path in `settings.yaml` for seamless integration.\n\nUse cases:\n- Explain UI bugs visually\n- Show error messages\n- Compare before/after states\n\n### 📁 7. Context Management (4-Layer Architecture)\n\nEfficient knowledge sharing through a four-layer context system:\n\n| Layer | Location | Purpose |\n|-------|----------|---------|\n| Layer 1: Memory MCP | `memory/shogun_memory.jsonl` | Cross-project, cross-session long-term memory |\n| Layer 2: Project | `config/projects.yaml`, `projects/\u003cid\u003e.yaml`, `context/{project}.md` | Project-specific information and technical knowledge |\n| Layer 3: YAML Queue | `queue/shogun_to_karo.yaml`, `queue/tasks/`, `queue/reports/` | Task management — source of truth for instructions and reports |\n| Layer 4: Session | CLAUDE.md, instructions/*.md | Working context (wiped by `/clear`) |\n\n#### Persistent Agent Memory (`memory/MEMORY.md`)\n\nShogun reads `memory/MEMORY.md` at every session start. It contains Lord's preferences, lessons learned, and cross-session knowledge — written by Shogun, read by Shogun.\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    Git Repositories                          │\n│                                                              │\n│  ┌─────────────────────┐   ┌──────────────────────────┐    │\n│  │  multi-agent-shogun │   │      shogun-private        │    │\n│  │       (public OSS)  │   │   (your private repo)      │    │\n│  │                     │   │                            │    │\n│  │ scripts/            │   │ projects/client.yaml  ←──┐ │    │\n│  │ instructions/       │   │ context/my-notes.md   ←──┤ │    │\n│  │ lib/                │   │ queue/shogun_to_karo.yaml │ │    │\n│  │ memory/             │   │ memory/MEMORY.md      ←──┘ │    │\n│  │  ├─ MEMORY.md.sample│   │ config/settings.yaml       │    │\n│  │  └─ MEMORY.md  ─────┼───┼── same file, tracked here  │    │\n│  │     (gitignored)    │   │                            │    │\n│  └─────────────────────┘   └──────────────────────────┘    │\n│         ↑ anyone can fork        ↑ your data, your repo      │\n└─────────────────────────────────────────────────────────────┘\n```\n\n**How it works:** `memory/MEMORY.md` lives in the same working directory as the OSS repo, but is excluded from the OSS `.gitignore` (whitelist-based). You track it in a separate private repo using a bare git repo technique:\n\n```bash\n# One-time setup (already done by first_setup.sh)\ngit init --bare ~/.shogun-private.git\nalias privategit='git --git-dir=$HOME/.shogun-private.git --work-tree=/path/to/multi-agent-shogun'\nprivategit remote add origin https://github.com/YOU/shogun-private.git\n\n# Daily use\nprivategit add -f memory/MEMORY.md projects/my-client.yaml\nprivategit commit -m \"update memory\"\nprivategit push\n```\n\nThe OSS `.gitignore` uses a **whitelist approach** (default: exclude everything, then explicitly allow OSS files). So private files like `memory/MEMORY.md` are automatically excluded without needing explicit `gitignore` entries — just don't add them to the whitelist.\n\nThis design enables:\n- Any Ashigaru can work on any project\n- Context persists across agent switches\n- Clear separation of concerns\n- Knowledge survives across sessions\n\n#### /clear Protocol (Cost Optimization)\n\nAs 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.\n\nRecovery cost after `/clear`: **~6,800 tokens** (42% improved from v1 — CLAUDE.md YAML conversion + English-only instructions reduced token cost by 70%)\n\n1. CLAUDE.md (auto-loaded) → recognizes itself as part of the Shogun System\n2. `tmux display-message -t \"$TMUX_PANE\" -p '#{@agent_id}'` → identifies its own number\n3. Memory MCP read → restores the Lord's preferences (~700 tokens)\n4. Task YAML read → picks up the next assignment (~800 tokens)\n\nThe key insight: designing **what not to load** is what drives cost savings.\n\n#### Universal Context Template\n\nAll projects use the same 7-section template:\n\n| Section | Purpose |\n|---------|---------|\n| What | Project overview |\n| Why | Goals and success criteria |\n| Who | Stakeholders and responsibilities |\n| Constraints | Deadlines, budgets, limitations |\n| Current State | Progress, next actions, blockers |\n| Decisions | Decisions made and their rationale |\n| Notes | Free-form observations and ideas |\n\nThis unified format enables:\n- Quick onboarding for any agent\n- Consistent information management across all projects\n- Easy handoff between Ashigaru workers\n\n### 📱 8. Phone Notifications (ntfy)\n\nTwo-way communication between your phone and the Shogun — no SSH, no Tailscale, no server needed.\n\n| Direction | How it works |\n|-----------|-------------|\n| **Phone → Shogun** | Send a message from the ntfy app → `ntfy_listener.sh` receives it via streaming → auto-ACK reply (`📱受信: {your message}`) sent back to your phone → Shogun processes automatically |\n| **Karo → Phone (direct)** | When Karo updates `dashboard.md`, it sends push notifications directly via `scripts/ntfy.sh` — **Shogun is bypassed** (Shogun is for human interaction, not progress reporting) |\n\n```\n📱 You (from bed)          🏯 Shogun\n    │                          │\n    │  \"Research React 19\"     │\n    ├─────────────────────────►│\n    │    (ntfy message)        │  → Delegates to Karo → Ashigaru work\n    │                          │\n    │  \"✅ cmd_042 complete\"   │\n    │◄─────────────────────────┤\n    │    (push notification)   │\n```\n\n**Setup:**\n1. Add `ntfy_topic: \"shogun-yourname\"` to `config/settings.yaml`\n2. Install the [ntfy app](https://ntfy.sh) on your phone and subscribe to the same topic\n3. `shutsujin_departure.sh` automatically starts the listener — no extra steps\n\n**Notification examples:**\n\n| Event | Notification |\n|-------|-------------|\n| Command completed | `✅ cmd_042 complete — 5/5 subtasks done` |\n| Task failed | `❌ subtask_042c failed — API rate limit` |\n| Action required | `🚨 Action needed: approve skill candidate` |\n| Streak update | `🔥 3-day streak! 12/12 tasks today` |\n\nFree, no account required, no server to maintain. Uses [ntfy.sh](https://ntfy.sh) — an open-source push notification service.\n\n\u003e **⚠️ 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).\n\n**Verify it works:**\n\n```bash\n# Send a test notification to your phone\nbash scripts/ntfy.sh \"Test notification from Shogun 🏯\"\n```\n\nIf your phone receives the notification, you're all set. If not, check:\n- `config/settings.yaml` has `ntfy_topic` set (not empty, no extra quotes)\n- The ntfy app on your phone is subscribed to **the exact same topic name**\n- Your phone has internet access and ntfy notifications are enabled\n\n**Sending commands from your phone:**\n\n1. Open the ntfy app on your phone\n2. Tap your subscribed topic\n3. Type a message (e.g., `Research React 19 best practices`) and send\n4. `ntfy_listener.sh` receives it, writes to `queue/ntfy_inbox.yaml`, and wakes the Shogun\n5. The Shogun reads the message and processes it through the normal Karo → Ashigaru pipeline\n\nAny text you send becomes a command. Write it like you'd talk to the Shogun — no special syntax needed.\n\n**Manual listener start** (if not using `shutsujin_departure.sh`):\n\n```bash\n# Start the listener in the background\nnohup bash scripts/ntfy_listener.sh \u0026\u003e/dev/null \u0026\n\n# Check if it's running\npgrep -f ntfy_listener.sh\n\n# View listener logs (stderr output)\nbash scripts/ntfy_listener.sh  # Run in foreground to see logs\n```\n\nThe 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.\n\n**Troubleshooting:**\n\n| Problem | Fix |\n|---------|-----|\n| No notifications on phone | Check topic name matches exactly in `settings.yaml` and ntfy app |\n| Listener not starting | Run `bash scripts/ntfy_listener.sh` in foreground to see errors |\n| Phone → Shogun not working | Verify listener is running: `pgrep -f ntfy_listener.sh` |\n| Messages not reaching Shogun | Check `queue/ntfy_inbox.yaml` — if message is there, Shogun may be busy |\n| \"ntfy_topic not configured\" error | Add `ntfy_topic: \"your-topic\"` to `config/settings.yaml` |\n| Duplicate notifications | Normal on reconnect — Shogun deduplicates by message ID |\n| Changed topic name but no notifications | The listener must be restarted: `pkill -f ntfy_listener.sh \u0026\u0026 nohup bash scripts/ntfy_listener.sh \u0026\u003e/dev/null \u0026` |\n\n**Real-world notification screenshots:**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/screenshots/masked/ntfy_saytask_rename.jpg\" alt=\"Bidirectional phone communication\" width=\"300\"\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"images/screenshots/masked/ntfy_cmd043_progress.jpg\" alt=\"Progress notification\" width=\"300\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003ci\u003eLeft: Bidirectional phone ↔ Shogun communication · Right: Real-time progress report from Ashigaru\u003c/i\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/screenshots/masked/ntfy_bloom_oc_test.jpg\" alt=\"Command completion notification\" width=\"300\"\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"images/screenshots/masked/ntfy_persona_eval_complete.jpg\" alt=\"8-agent parallel completion\" width=\"300\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003ci\u003eLeft: Command completion notification · Right: All 8 Ashigaru completing in parallel\u003c/i\u003e\u003c/p\u003e\n\n\u003e *Note: Topic names shown in screenshots are examples. Use your own unique topic name.*\n\n#### SayTask Notifications\n\nBehavioral psychology-driven motivation through your notification feed:\n\n- **Streak tracking**: Consecutive completion days counted in `saytask/streaks.yaml` — maintaining streaks leverages loss aversion to sustain momentum\n- **Eat the Frog** 🐸: The hardest task of the day is marked as the \"Frog.\" Completing it triggers a special celebration notification\n- **Daily progress**: `12/12 tasks today` — visual completion feedback reinforces the Arbeitslust effect (joy of work-in-progress)\n\n### 🖼️ 9. Pane Border Task Display\n\nEach tmux pane shows the agent's current task directly on its border:\n\n```\n┌ ashigaru1 Sonnet+T VF requirements ──┬ ashigaru3 Opus+T API research ──────┐\n│                                      │                                     │\n│  Working on SayTask requirements     │  Researching REST API patterns      │\n│                                      │                                     │\n├ ashigaru2 Sonnet ───────────────────┼ ashigaru4 Spark DB schema design ───┤\n│                                      │                                     │\n│  (idle — waiting for assignment)     │  Designing database schema          │\n│                                      │                                     │\n└──────────────────────────────────────┴─────────────────────────────────────┘\n```\n\n- **Working**: `ashigaru1 Sonnet+T VF requirements` — agent name, model (with Thinking indicator), and task summary\n- **Idle**: `ashigaru2 Sonnet` — model name only, no task\n- **Display names**: Sonnet, Opus, Haiku, Codex, Spark — `+T` suffix = Extended Thinking enabled\n- Updated automatically by the Karo when assigning or completing tasks\n- Glance at all 9 panes to instantly know who's doing what\n\n### 🔊 10. Shout Mode (Battle Cries)\n\nWhen an Ashigaru completes a task, it shouts a personalized battle cry in the tmux pane — a visual reminder that your army is working hard.\n\n```\n┌ ashigaru1 (Sonnet) ──────────┬ ashigaru2 (Sonnet) ──────────┐\n│                               │                               │\n│  ⚔️ 足軽1号、先陣切った！     │  🔥 足軽2号、二番槍の意地！   │\n│  八刃一志！                   │  八刃一志！                   │\n│  ❯                            │  ❯                            │\n└───────────────────────────────┴───────────────────────────────┘\n```\n\n**How it works:**\n\nThe 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.\n\n```yaml\n# In the task YAML (written by Karo)\ntask:\n  task_id: subtask_001\n  description: \"Create comparison table\"\n  echo_message: \"🔥 足軽1号、先陣を切って参る！八刃一志！\"\n```\n\n**Shout mode is the default.** To disable (saves API tokens on the echo call):\n\n```bash\n./shutsujin_departure.sh --silent    # No battle cries\n./shutsujin_departure.sh             # Default: shout mode (battle cries enabled)\n```\n\nSilent mode sets `DISPLAY_MODE=silent` as a tmux environment variable. The Karo checks this when writing task YAMLs and omits the `echo_message` field.\n\n---\n\n## 🗣️ SayTask — Task Management for People Who Hate Task Management\n\n### What is SayTask?\n\n**Task management for people who hate task management. Just speak to your phone.**\n\n**Talk Coding, not Vibe Coding.** Speak your tasks, AI organizes them. No typing, no opening apps, no friction.\n\n- **Target audience**: People who installed Todoist but stopped opening it after 3 days\n- Your enemy isn't other apps — it's doing nothing. The competition is inaction, not another productivity tool\n- Zero UI. Zero typing. Zero app-opening. Just talk\n\n\u003e *\"Your enemy isn't other apps — it's doing nothing.\"*\n\n### How it Works\n\n1. Install the [ntfy app](https://ntfy.sh) (free, no account needed)\n2. Speak to your phone: *\"dentist tomorrow\"*, *\"invoice due Friday\"*\n3. AI auto-organizes → morning notification: *\"here's your day\"*\n\n```\n 🗣️ \"Buy milk, dentist tomorrow, invoice due Friday\"\n       │\n       ▼\n ┌──────────────────┐\n │  ntfy → Shogun   │  AI auto-categorize, parse dates, set priorities\n └────────┬─────────┘\n          │\n          ▼\n ┌──────────────────┐\n │   tasks.yaml     │  Structured storage (local, never leaves your machine)\n └────────┬─────────┘\n          │\n          ▼\n 📱 Morning notification:\n    \"Today: 🐸 Invoice due · 🦷 Dentist 3pm · 🛒 Buy milk\"\n```\n\n### Before / After\n\n| Before (v1) | After (v2) |\n|:-----------:|:----------:|\n| ![Task list v1](images/screenshots/masked/ntfy_tasklist_v1_before.jpg) | ![Task list v2](images/screenshots/masked/ntfy_tasklist_v2_aligned.jpg) |\n| Raw task dump | Clean, organized daily summary |\n\n\u003e *Note: Topic names shown in screenshots are examples. Use your own unique topic name.*\n\n### Use Cases\n\n- 🛏️ **In bed**: *\"Gotta submit the report tomorrow\"* — captured before you forget, no fumbling for a notebook\n- 🚗 **While driving**: *\"Don't forget the estimate for client A\"* — hands-free, eyes on the road\n- 💻 **Mid-work**: *\"Oh, need to buy milk\"* — dump it instantly and stay in flow\n- 🌅 **Wake up**: Today's tasks already waiting in your notifications — no app to open, no inbox to check\n- 🐸 **Eat the Frog**: AI picks your hardest task each morning — ignore it or conquer it first\n\n### FAQ\n\n**Q: How is this different from other task apps?**\nA: You never open an app. Just speak. Zero friction. Most task apps fail because people stop opening them. SayTask removes that step entirely.\n\n**Q: Can I use SayTask without the full Shogun system?**\nA: SayTask is a feature of Shogun. Shogun also works as a standalone multi-agent development platform — you get both capabilities in one system.\n\n**Q: What's the Frog 🐸?**\nA: 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.\n\n**Q: Is it free?**\nA: Everything is free and open-source. ntfy is free too. No account, no server, no subscription.\n\n**Q: Where is my data stored?**\nA: Local YAML files on your machine. Nothing is sent to the cloud. Your tasks never leave your device.\n\n**Q: What if I say something vague like \"that thing for work\"?**\nA: AI does its best to categorize and schedule it. You can always refine later — but the point is capturing the thought before it disappears.\n\n### SayTask vs cmd Pipeline\n\nShogun has two complementary task systems:\n\n| Capability | SayTask (Voice Layer) | cmd Pipeline (AI Execution) |\n|---|:-:|:-:|\n| Voice input → task creation | ✅ | — |\n| Morning notification digest | ✅ | — |\n| Eat the Frog 🐸 selection | ✅ | — |\n| Streak tracking | ✅ | ✅ |\n| AI-executed tasks (multi-step) | — | ✅ |\n| 8-agent parallel execution | — | ✅ |\n\nSayTask 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.\n\n---\n\n## Model Settings\n\n| Agent | Default Model | Thinking | Role |\n|-------|--------------|----------|------|\n| Shogun | Opus | **Enabled (high)** | Strategic advisor to the Lord. Use `--shogun-no-thinking` for relay-only mode |\n| Karo | Sonnet | Enabled | Task distribution, simple QC, dashboard management |\n| Gunshi | Opus | Enabled | Deep analysis, design review, architecture evaluation |\n| Ashigaru 1–7 | Sonnet 4.6 | Enabled | Implementation: code, research, file operations |\n\n**Thinking control**: Set `thinking: true/false` per agent in `config/settings.yaml`. When `thinking: false`, the agent starts with `MAX_THINKING_TOKENS=0` to disable Extended Thinking. Pane borders show `+T` suffix when Thinking is enabled (e.g., `Sonnet+T`, `Opus+T`).\n\n**Live model switching**: Use `/shogun-model-switch` to change any agent's CLI type, model, or Thinking setting without restarting the entire system. See the Skills section for details.\n\nThe system routes work by **cognitive complexity** at two levels: **Agent routing** (Ashigaru for L1–L3, Gunshi for L4–L6) and **Model routing within Ashigaru** via `capability_tiers` (see Dynamic Model Routing below).\n\n### Bloom's Taxonomy → Agent Routing\n\nTasks are classified using Bloom's Taxonomy and routed to the appropriate **agent**, not model:\n\n| Level | Category | Description | Routed To |\n|-------|----------|-------------|-----------|\n| L1 | Remember | Recall facts, copy, list | **Ashigaru** |\n| L2 | Understand | Explain, summarize, paraphrase | **Ashigaru** |\n| L3 | Apply | Execute procedures, implement known patterns | **Ashigaru** |\n| L4 | Analyze | Compare, investigate, deconstruct | **Gunshi** |\n| L5 | Evaluate | Judge, critique, recommend | **Gunshi** |\n| L6 | Create | Design, build, synthesize new solutions | **Gunshi** |\n\nThe Karo assigns each subtask a Bloom level and routes it to the appropriate agent. L1–L3 tasks go to Ashigaru for parallel execution; L4–L6 tasks go to the Gunshi for deeper analysis. Simple L4 tasks (e.g., small code review) may still go to Ashigaru when the Karo judges it appropriate.\n\n### Task Dependencies (blockedBy)\n\nTasks can declare dependencies on other tasks using `blockedBy`:\n\n```yaml\n# queue/tasks/ashigaru2.yaml\ntask:\n  task_id: subtask_010b\n  blockedBy: [\"subtask_010a\"]  # Waits for ashigaru1's task to complete\n  description: \"Integrate the API client built by subtask_010a\"\n```\n\nWhen 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.\n\n### Dynamic Model Routing (capability_tiers)\n\nBeyond agent-level routing, you can configure **model-level routing within the Ashigaru tier**. Define a `capability_tiers` table in `config/settings.yaml` mapping each model to its maximum Bloom level:\n\n```yaml\ncapability_tiers:\n  gpt-5.3-codex-spark:\n    max_bloom: 3       # L1–L3 only: fast, high-volume tasks\n    cost_group: chatgpt_pro\n  gpt-5.3-codex:\n    max_bloom: 4       # L1–L4: + analysis and debugging\n    cost_group: chatgpt_pro\n  claude-sonnet-4-6:\n    max_bloom: 5       # L1–L5: + design evaluation\n    cost_group: claude_max\n  claude-opus-4-6:\n    max_bloom: 6       # L1–L6: + novel architecture, strategy\n    cost_group: claude_max\n```\n\nThe `cost_group` field links each model to your subscription plan, enabling the system to avoid routing tasks to models your plan doesn't cover.\n\nTwo built-in skills help you configure this:\n\n| Skill | Purpose |\n|-------|---------|\n| `/shogun-model-list` | Reference table: all models × subscriptions × Bloom max |\n| `/shogun-bloom-config` | Interactive: answer 2 questions → get ready-to-paste YAML |\n\nRun `/shogun-bloom-config` after setup to generate your optimal `capability_tiers` configuration.\n\n---\n\n## Philosophy\n\n\u003e \"Don't execute tasks mindlessly. Always keep 'fastest × best output' in mind.\"\n\nThe Shogun System is built on five core principles:\n\n| Principle | Description |\n|-----------|-------------|\n| **Autonomous Formation** | Design task formations based on complexity, not templates |\n| **Parallelization** | Use subagents to prevent single-point bottlenecks |\n| **Research First** | Search for evidence before making decisions |\n| **Continuous Learning** | Don't rely solely on model knowledge cutoffs |\n| **Triangulation** | Multi-perspective research with integrated authorization |\n\nThese principles are documented in detail: **[docs/philosophy.md](docs/philosophy.md)**\n\n---\n\n## Design Philosophy\n\n### Why a hierarchy (Shogun → Karo → Ashigaru)?\n\n1. **Instant response**: The Shogun delegates immediately, returning control to you\n2. **Parallel execution**: The Karo distributes to multiple Ashigaru simultaneously\n3. **Single responsibility**: Each role is clearly separated — no confusion\n4. **Scalability**: Adding more Ashigaru doesn't break the structure\n5. **Fault isolation**: One Ashigaru failing doesn't affect the others\n6. **Unified reporting**: Only the Shogun communicates with you, keeping information organized\n\n### Why Mailbox System?\n\nWhy use files instead of direct messaging between agents?\n\n| Problem with direct messaging | How mailbox solves it |\n|-------------------------------|----------------------|\n| Agent crashes → message lost | YAML files survive restarts |\n| Polling wastes API calls | `inotifywait` is event-driven (zero CPU while idle) |\n| Agents interrupt each other | Each agent has its own inbox file — no cross-talk |\n| Hard to debug | Open any `.yaml` file to see exact message history |\n| Concurrent writes corrupt data | `flock` (exclusive lock) serializes writes automatically |\n| Delivery failures (character corruption, hangs) | Message content stays in files — only a short \"you have mail\" nudge is sent through tmux |\n\n### Agent Identification (@agent_id)\n\nEach 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.\n\nAgent self-identification:\n```bash\ntmux display-message -t \"$TMUX_PANE\" -p '#{@agent_id}'\n```\nThe `-t \"$TMUX_PANE\"` is required. Omitting it returns the active pane's value (whichever pane you're focused on), causing misidentification.\n\nModel 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.\n\n### Why only the Karo updates dashboard.md\n\n1. **Single writer**: Prevents conflicts by limiting updates to one agent\n2. **Information aggregation**: The Karo receives all Ashigaru reports, so it has the full picture\n3. **Consistency**: All updates pass through a single quality gate\n4. **No interruptions**: If the Shogun updated it, it could interrupt the Lord's input\n\n---\n\n## Skills\n\nNo skills are included out of the box. Skills emerge organically during operation — you approve candidates from `dashboard.md` as they're discovered.\n\nInvoke skills with `/skill-name`. Just tell the Shogun: \"run /skill-name\".\n\n### Included Skills (committed to repo)\n\nSkills ship with the repository in `skills/`. They are domain-agnostic utilities useful for any user:\n\n| Skill | Description |\n|-------|-------------|\n| `/skill-creator` | Template and guide for creating new skills |\n| `/shogun-agent-status` | Show busy/idle status of all agents with task and inbox info |\n| `/shogun-model-list` | Reference table: all CLI tools × models × subscriptions × Bloom max level |\n| `/shogun-bloom-config` | Interactive configurator: answer 2 questions about your subscriptions → get ready-to-paste `capability_tiers` YAML |\n| `/shogun-model-switch` | Live CLI/model switching: settings.yaml update → `/exit` → relaunch with correct flags. Supports Thinking ON/OFF control |\n| `/shogun-readme-sync` | Keep README.md and README_ja.md in sync |\n\nThese help you configure and operate the system. Personal workflow skills grow organically through the bottom-up discovery process.\n\n### Skill Philosophy\n\n**1. Personal skills are not committed to the repo**\n\nSkills in `.claude/commands/` are excluded from version control by design:\n- Every user's workflow is different\n- Rather than imposing generic skills, each user grows their own skill set\n\n**2. How skills are discovered**\n\n```\nAshigaru notices a pattern during work\n    ↓\nAppears in dashboard.md under \"Skill Candidates\"\n    ↓\nYou (the Lord) review the proposal\n    ↓\nIf approved, instruct the Karo to create the skill\n```\n\nSkills are user-driven. Automatic creation would lead to unmanageable bloat — only keep what you find genuinely useful.\n\n---\n\n## MCP Setup Guide\n\nMCP (Model Context Protocol) servers extend Claude's capabilities. Here's how to set them up:\n\n### What is MCP?\n\nMCP servers give Claude access to external tools:\n- **Notion MCP** → Read and write Notion pages\n- **GitHub MCP** → Create PRs, manage issues\n- **Memory MCP** → Persist memory across sessions\n\n### Installing MCP Servers\n\nAdd MCP servers with these commands:\n\n```bash\n# 1. Notion - Connect to your Notion workspace\nclaude mcp add notion -e NOTION_TOKEN=your_token_here -- npx -y @notionhq/notion-mcp-server\n\n# 2. Playwright - Browser automation\nclaude mcp add playwright -- npx @playwright/mcp@latest\n# Note: Run `npx playwright install chromium` first\n\n# 3. GitHub - Repository operations\nclaude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=your_pat_here -- npx -y @modelcontextprotocol/server-github\n\n# 4. Sequential Thinking - Step-by-step reasoning for complex problems\nclaude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking\n\n# 5. Memory - Cross-session long-term memory (recommended!)\n# ✅ Auto-configured by first_setup.sh\n# To reconfigure manually:\nclaude mcp add memory -e MEMORY_FILE_PATH=\"$PWD/memory/shogun_memory.jsonl\" -- npx -y @modelcontextprotocol/server-memory\n```\n\n### Verify installation\n\n```bash\nclaude mcp list\n```\n\nAll servers should show \"Connected\" status.\n\n---\n\n## Real-World Use Cases\n\nThis system manages **all white-collar tasks**, not just code. Projects can live anywhere on your filesystem.\n\n### Example 1: Research sprint\n\n```\nYou: \"Research the top 5 AI coding assistants and compare them\"\n\nWhat happens:\n1. Shogun delegates to Karo\n2. Karo assigns:\n   - Ashigaru 1: Research GitHub Copilot\n   - Ashigaru 2: Research Cursor\n   - Ashigaru 3: Research Claude Code\n   - Ashigaru 4: Research Codeium\n   - Ashigaru 5: Research Amazon CodeWhisperer\n3. All 5 research simultaneously\n4. Results compiled in dashboard.md\n```\n\n### Example 2: PoC preparation\n\n```\nYou: \"Prepare a PoC for the project on this Notion page: [URL]\"\n\nWhat happens:\n1. Karo fetches Notion content via MCP\n2. Ashigaru 2: Lists items to verify\n3. Ashigaru 3: Investigates technical feasibility\n4. Ashigaru 4: Drafts a PoC plan\n5. All results compiled in dashboard.md — meeting prep done\n```\n\n---\n\n## Configuration\n\n### Language\n\n```yaml\n# config/settings.yaml\nlanguage: ja   # Samurai Japanese only\nlanguage: en   # Samurai Japanese + English translation\n```\n\n### Screenshot integration\n\n```yaml\n# config/settings.yaml\nscreenshot:\n  path: \"/mnt/c/Users/YourName/Pictures/Screenshots\"\n```\n\nTell the Shogun \"check the latest screenshot\" and it reads your screen captures for visual context. (`Win+Shift+S` on Windows.)\n\n### ntfy (Phone Notifications)\n\n```yaml\n# config/settings.yaml\nntfy_topic: \"shogun-yourname\"\n```\n\nSubscribe to the same topic in the [ntfy app](https://ntfy.sh) on your phone. The listener starts automatically with `shutsujin_departure.sh`.\n\n#### ntfy Authentication (Self-Hosted Servers)\n\nThe public ntfy.sh instance requires **no authentication** — the setup above is all you need.\n\nIf you run a self-hosted ntfy server with access control enabled, configure authentication:\n\n```bash\n# 1. Copy the sample config\ncp config/ntfy_auth.env.sample config/ntfy_auth.env\n\n# 2. Edit with your credentials (choose one method)\n```\n\n| Method | Config | When to use |\n|--------|--------|-------------|\n| **Bearer Token** (recommended) | `NTFY_TOKEN=tk_your_token_here` | Self-hosted ntfy with token auth (`ntfy token add \u003cuser\u003e`) |\n| **Basic Auth** | `NTFY_USER=username` + `NTFY_PASS=password` | Self-hosted ntfy with user/password |\n| **None** (default) | Leave file empty or don't create it | Public ntfy.sh — no auth needed |\n\nPriority: Token \u003e Basic \u003e None. If neither is set, no auth headers are sent (backward compatible).\n\n`config/ntfy_auth.env` is excluded from git. See `config/ntfy_auth.env.sample` for details.\n\n---\n\n## Advanced\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eScript Architecture\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                    First-Time Setup (run once)                       │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  install.bat (Windows)                                              │\n│      │                                                              │\n│      ├── Check/guide WSL2 installation                              │\n│      └── Check/guide Ubuntu installation                            │\n│                                                                     │\n│  first_setup.sh (run manually in Ubuntu/WSL)                        │\n│      │                                                              │\n│      ├── Check/install tmux                                         │\n│      ├── Check/install Node.js v20+ (via nvm)                      │\n│      ├── Check/install Claude Code CLI (native version)             │\n│      │       ※ Proposes migration if npm version detected           │\n│      └── Configure Memory MCP server                                │\n│                                                                     │\n├─────────────────────────────────────────────────────────────────────┤\n│                    Daily Startup (run every day)                     │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  shutsujin_departure.sh                                             │\n│      │                                                              │\n│      ├──▶ Create tmux sessions                                      │\n│      │         • \"shogun\" session (1 pane)                          │\n│      │         • \"multiagent\" session (9 panes, 3x3 grid)          │\n│      │                                                              │\n│      ├──▶ Reset queue files and dashboard                           │\n│      │                                                              │\n│      └──▶ Launch Claude Code on all agents                          │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eshutsujin_departure.sh Options\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n```bash\n# Default: Full startup (tmux sessions + Claude Code launch)\n./shutsujin_departure.sh\n\n# Session setup only (no Claude Code launch)\n./shutsujin_departure.sh -s\n./shutsujin_departure.sh --setup-only\n\n# Clean task queues (preserves command history)\n./shutsujin_departure.sh -c\n./shutsujin_departure.sh --clean\n\n# Battle formation: All Ashigaru on Opus (max capability, higher cost)\n./shutsujin_departure.sh -k\n./shutsujin_departure.sh --kessen\n\n# Silent mode: Disable battle cries (saves API tokens on echo calls)\n./shutsujin_departure.sh -S\n./shutsujin_departure.sh --silent\n\n# Full startup + open Windows Terminal tabs\n./shutsujin_departure.sh -t\n./shutsujin_departure.sh --terminal\n\n# Shogun relay-only mode: Disable Shogun's thinking (cost savings)\n./shutsujin_departure.sh --shogun-no-thinking\n\n# Show help\n./shutsujin_departure.sh -h\n./shutsujin_departure.sh --help\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCommon Workflows\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n**Normal daily use:**\n```bash\n./shutsujin_departure.sh          # Launch everything\ntmux attach-session -t shogun     # Connect and give commands\n```\n\n**Debug mode (manual control):**\n```bash\n./shutsujin_departure.sh -s       # Create sessions only\n\n# Manually launch Claude Code on specific agents\ntmux send-keys -t shogun:0 'claude --dangerously-skip-permissions' Enter\ntmux send-keys -t multiagent:0.0 'claude --dangerously-skip-permissions' Enter\n```\n\n**Restart after crash:**\n```bash\n# Kill existing sessions\ntmux kill-session -t shogun\ntmux kill-session -t multiagent\n\n# Fresh start\n./shutsujin_departure.sh\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eConvenient Aliases\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\nRunning `first_setup.sh` automatically adds these aliases to `~/.bashrc`:\n\n```bash\nalias csst='cd /mnt/c/tools/multi-agent-shogun \u0026\u0026 ./shutsujin_departure.sh'\nalias css='tmux attach-session -t shogun'      # Connect to Shogun\nalias csm='tmux attach-session -t multiagent'  # Connect to Karo + Ashigaru\n```\n\nTo apply aliases: run `source ~/.bashrc` or restart your terminal (PowerShell: `wsl --shutdown` then reopen).\n\n\u003c/details\u003e\n\n---\n\n## File Structure\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClick to expand file structure\u003c/b\u003e\u003c/summary\u003e\n\n```\nmulti-agent-shogun/\n│\n│  ┌──────────────── Setup Scripts ────────────────────┐\n├── install.bat               # Windows: First-time setup\n├── first_setup.sh            # Ubuntu/Mac: First-time setup\n├── shutsujin_departure.sh    # Daily deployment (auto-loads instructions)\n│  └──────────────────────────────────────────────────┘\n│\n├── instructions/             # Agent behavior definitions\n│   ├── shogun.md             # Shogun instructions\n│   ├── karo.md               # Karo instructions\n│   ├── ashigaru.md           # Ashigaru instructions\n│   ├── gunshi.md             # Gunshi (strategist) instructions\n│   └── cli_specific/         # CLI-specific tool descriptions\n│       ├── claude_tools.md   # Claude Code tools \u0026 features\n│       └── copilot_tools.md  # GitHub Copilot CLI tools \u0026 features\n│\n├── lib/\n│   ├── agent_status.sh       # Shared busy/idle detection (Claude Code + Codex)\n│   ├── cli_adapter.sh        # Multi-CLI adapter (Claude/Codex/Copilot/Kimi)\n│   └── ntfy_auth.sh          # ntfy authentication helper\n│\n├── scripts/                  # Utility scripts\n│   ├── agent_status.sh       # Show busy/idle status of all agents\n│   ├── inbox_write.sh        # Write messages to agent inbox\n│   ├── inbox_watcher.sh      # Watch inbox changes via inotifywait\n│   ├── switch_cli.sh         # Live CLI/model switching (/exit → relaunch)\n│   ├── ntfy.sh               # Send push notifications to phone\n│   └── ntfy_listener.sh      # Stream incoming messages from phone\n│\n├── config/\n│   ├── settings.yaml         # Language, ntfy, and other settings\n│   ├── ntfy_auth.env.sample  # ntfy authentication template (self-hosted)\n│   └── projects.yaml         # Project registry\n│\n├── projects/                 # Project details (excluded from git, contains confidential info)\n│   └── \u003cproject_id\u003e.yaml    # Full info per project (clients, tasks, Notion links, etc.)\n│\n├── queue/                    # Communication files\n│   ├── shogun_to_karo.yaml   # Shogun → Karo commands\n│   ├── ntfy_inbox.yaml       # Incoming messages from phone (ntfy)\n│   ├── inbox/                # Per-agent inbox files\n│   │   ├── shogun.yaml       # Messages to Shogun\n│   │   ├── karo.yaml         # Messages to Karo\n│   │   └── ashigaru{1-8}.yaml # Messages to each Ashigaru\n│   ├── tasks/                # Per-worker task files\n│   └── reports/              # Worker reports\n│\n├── saytask/                  # Behavioral psychology-driven motivation\n│   └── streaks.yaml          # Streak tracking and daily progress\n│\n├── templates/                # Report and context templates\n│   ├── integ_base.md         # Integration: base template\n│   ├── integ_fact.md         # Integration: fact-finding\n│   ├── integ_proposal.md     # Integration: proposal\n│   ├── integ_code.md         # Integration: code review\n│   ├── integ_analysis.md     # Integration: analysis\n│   └── context_template.md   # Universal 7-section project context\n│\n├── skills/                   # Reusable skills (committed to repo)\n│   ├── skill-creator/        # Skill creation template\n│   ├── shogun-agent-status/  # Agent status display\n│   ├── shogun-model-list/    # Model capability reference\n│   ├── shogun-bloom-config/  # Bloom tier configurator\n│   ├── shogun-model-switch/  # Live CLI/model switching\n│   └── shogun-readme-sync/   # README sync\n│\n├── memory/                   # Memory MCP persistent storage\n├── dashboard.md              # Real-time status board\n└── CLAUDE.md                 # System instructions (auto-loaded)\n```\n\n\u003c/details\u003e\n\n---\n\n## Project Management\n\nThis system manages not just its own development, but **all white-collar tasks**. Project folders can be located outside this repository.\n\n### How it works\n\n```\nconfig/projects.yaml          # Project list (ID, name, path, status only)\nprojects/\u003cproject_id\u003e.yaml    # Full details for each project\n```\n\n- **`config/projects.yaml`**: A summary list of what projects exist\n- **`projects/\u003cid\u003e.yaml`**: Complete details (client info, contracts, tasks, related files, Notion pages, etc.)\n- **Project files** (source code, documents, etc.) live in the external folder specified by `path`\n- **`projects/` is excluded from git** (contains confidential client information)\n\n### Example\n\n```yaml\n# config/projects.yaml\nprojects:\n  - id: client_x\n    name: \"Client X Consulting\"\n    path: \"/mnt/c/Consulting/client_x\"\n    status: active\n\n# projects/client_x.yaml\nid: client_x\nclient:\n  name: \"Client X\"\n  company: \"X Corporation\"\ncontract:\n  fee: \"monthly\"\ncurrent_tasks:\n  - id: task_001\n    name: \"System Architecture Review\"\n    status: in_progress\n```\n\nThis separation lets the Shogun System coordinate across multiple external projects while keeping project details out of version control.\n\n---\n\n## Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eUsing npm version of Claude Code CLI?\u003c/b\u003e\u003c/summary\u003e\n\nThe npm version (`npm install -g @anthropic-ai/claude-code`) is officially deprecated. Re-run `first_setup.sh` to detect and migrate to the native version.\n\n```bash\n# Re-run first_setup.sh\n./first_setup.sh\n\n# If npm version is detected:\n# ⚠️ npm version of Claude Code CLI detected (officially deprecated)\n# Install native version? [Y/n]:\n\n# After selecting Y, uninstall npm version:\nnpm uninstall -g @anthropic-ai/claude-code\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMCP tools not loading?\u003c/b\u003e\u003c/summary\u003e\n\nMCP tools are lazy-loaded. Search first, then use:\n```\nToolSearch(\"select:mcp__memory__read_graph\")\nmcp__memory__read_graph()\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAgents asking for permissions?\u003c/b\u003e\u003c/summary\u003e\n\nAgents should start with `--dangerously-skip-permissions`. This is handled automatically by `shutsujin_departure.sh`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWorkers stuck?\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ntmux attach-session -t multiagent\n# Ctrl+B then 0-8 to switch panes\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAgent crashed?\u003c/b\u003e\u003c/summary\u003e\n\n**Do NOT use `css`/`csm` aliases to restart inside an existing tmux session.** These aliases create tmux sessions, so running them inside an existing tmux pane causes session nesting — your input breaks and the pane becomes unusable.\n\n**Correct restart methods:**\n\n```bash\n# Method 1: Run claude directly in the pane\nclaude --model opus --dangerously-skip-permissions\n\n# Method 2: Karo force-restarts via respawn-pane (also fixes nesting)\ntmux respawn-pane -t shogun:0.0 -k 'claude --model opus --dangerously-skip-permissions'\n```\n\n**If you accidentally nested tmux:**\n1. Press `Ctrl+B` then `d` to detach (exits the inner session)\n2. Run `claude` directly (don't use `css`)\n3. If detach doesn't work, use `tmux respawn-pane -k` from another pane to force-reset\n\n\u003c/details\u003e\n\n---\n\n## tmux Quick Reference\n\n| Command | Description |\n|---------|-------------|\n| `tmux attach -t shogun` | Connect to the Shogun |\n| `tmux attach -t multiagent` | Connect to workers |\n| `Ctrl+B` then `0`–`8` | Switch panes |\n| `Ctrl+B` then `d` | Detach (agents keep running) |\n| `tmux kill-session -t shogun` | Stop the Shogun session |\n| `tmux kill-session -t multiagent` | Stop the worker session |\n\n### Mouse Support\n\n`first_setup.sh` automatically configures `set -g mouse on` in `~/.tmux.conf`, enabling intuitive mouse control:\n\n| Action | Description |\n|--------|-------------|\n| Mouse wheel | Scroll within a pane (view output history) |\n| Click a pane | Switch focus between panes |\n| Drag pane border | Resize panes |\n\nEven if you're not comfortable with keyboard shortcuts, you can switch, scroll, and resize panes using just the mouse.\n\n---\n\n## What's New in v3.5 — Dynamic Model Routing\n\n\u003e **Right model for the right task — without restarting any agent.** Sonnet 4.6 closes the gap with Opus to just 1.2pp on SWE-bench (79.6% vs 80.8%), making per-task model routing practical and cost-effective for the first time.\n\n- **Bloom Dynamic Model Routing** — `capability_tiers` in `config/settings.yaml` maps each model to its Bloom ceiling. L1–L3 → Spark (1000+ tok/s), L4 → Sonnet 4.6, L5 → Sonnet 4.6 + extended thinking, L6 → Opus (genuinely novel design only). Routing happens without agent restarts — the system finds the right idle agent by model capability\n- **Sonnet 4.6 as the new standard** — SWE-bench 79.6%, only 1.2pp below Opus 4.6. Gunshi downgraded Opus → Sonnet 4.6. All Ashigaru default to Sonnet 4.6. One YAML line change, no restarts required\n- **`/shogun-model-list` skill** — Complete reference table: all CLI tools × models × subscriptions × Bloom max level. Updated for Sonnet 4.6 and Spark positioning\n- **`/shogun-bloom-config` skill** — Interactive configurator: answer 2 questions about your subscriptions → get ready-to-paste `capability_tiers` YAML\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWhat was in v3.4 — Bloom→Agent Routing, E2E Tests, Stop Hook\u003c/b\u003e\u003c/summary\u003e\n\n- **Bloom → Agent routing** — Replaced dynamic model switching with agent-level routing. L1–L3 tasks go to Ashigaru, L4–L6 tasks go to Gunshi. No more mid-session `/model opus` promotions\n- **Gunshi (軍師) as first-class agent** — Strategic advisor on pane 8. Handles deep analysis, design review, architecture evaluation, and complex QC\n- **E2E test suite (19 tests, 7 scenarios)** — Mock CLI framework simulates agent behavior in isolated tmux sessions\n- **Stop hook inbox delivery** — Claude Code agents automatically check inbox at turn end via `.claude/settings.json` Stop hook. Eliminates the `send-keys` interruption problem\n- **Model defaults updated** — Karo: Opus → Sonnet. Gunshi: Opus (deep reasoning). Ashigaru: Sonnet (uniform tier)\n- **Escape escalation disabled for Claude Code** — Phase 2 escalation was interrupting active Claude Code turns; Stop hook handles delivery instead\n- **Codex CLI startup prompt** — `get_startup_prompt()` in `cli_adapter.sh` passes initial `[PROMPT]` argument to Codex CLI launch\n- **YAML slimming utility** — `scripts/slim_yaml.sh` archives read messages and completed commands\n\n\u003c/details\u003e\n\n## What's New in v3.3.2 — GPT-5.3-Codex-Spark Support\n\n\u003e **New model, same YAML.** Add `model: gpt-5.3-codex-spark` to any Codex agent in `settings.yaml`.\n\n- **Codex `--model` flag support** — `build_cli_command()` now passes `settings.yaml` model config to the Codex CLI via `--model`. Supports `gpt-5.3-codex-spark` and any future Codex models\n- **Separate rate limit** — Spark runs on its own rate limit quota, independent of GPT-5.3-Codex. Run both models in parallel across different Ashigaru to **double your effective throughput**\n- **Startup display** — `shutsujin_departure.sh` now shows the actual model name (e.g., `codex/gpt-5.3-codex-spark`) instead of the generic effort level\n\n## What's New in v3.0 — Multi-CLI\n\n\u003e **Shogun is no longer Claude-only.** Mix and match 4 AI coding CLIs in a single army.\n\n- **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\n- **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\n- **CLI bypass flag discovery** — `--full-auto` is NOT fully automatic (it's `-a on-request`). Documented the correct flags for all 4 CLIs\n- **Hybrid architecture** — Command layer (Shogun + Karo) stays on Claude Code for Memory MCP and mailbox integration. Worker layer (Ashigaru) is CLI-agnostic\n- **Community-contributed CLI adapters** — Thanks to [@yuto-ts](https://github.com/yuto-ts) (cli_adapter.sh), [@circlemouth](https://github.com/circlemouth) (Codex support), [@koba6316](https://github.com/koba6316) (task routing)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWhat was in v2.0\u003c/b\u003e\u003c/summary\u003e\n\n- **ntfy bidirectional communication** — Send commands from your phone, receive push notifications for task completion\n- **SayTask notifications** — Streak tracking, Eat the Frog, behavioral psychology-driven motivation\n- **Pane border task display** — See each agent's current task at a glance on the tmux pane border\n- **Shout mode** (default) — Ashigaru shout personalized battle cries after completing tasks. Disable with `--silent`\n- **Agent self-watch + escalation (v3.2)** — Each agent monitors its own inbox file with `inotifywait` (zero-polling, instant wake-up). Fallback: `tmux send-keys` short nudge (text/Enter sent separately for Codex CLI). 3-phase escalation: standard nudge (0-2min) → Escape×2+nudge (2-4min) → `/clear` force reset (4min+). Linux FS symlink resolves WSL2 9P inotify issues.\n- **Agent self-identification** (`@agent_id`) — Stable identity via tmux user options, immune to pane reordering\n- **Battle mode** (`-k` flag) — All-Opus formation for maximum capability\n- **Task dependency system** (`blockedBy`) — Automatic unblocking of dependent tasks\n\n\u003c/details\u003e\n\n---\n\n## Sponsors\n\nThis project is funded by sponsors. Your support keeps it free and actively maintained.\n\n\u003ca href=\"https://github.com/sponsors/yohey-w\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa?style=for-the-badge\u0026logo=github-sponsors\" alt=\"Sponsor\"\u003e\n\u003c/a\u003e\n\n| Tier | Perks |\n|------|-------|\n| ☕ $5/mo | Name in sponsors section |\n| 🏯 $25/mo | Early access to new releases |\n| ⚔️ $100/mo | Priority issue/PR response (48h) |\n| 🎖️ $500/mo | Monthly 1:1 consultation |\n| 🏛️ $1,000/mo | Logo in README + quarterly strategy session |\n\n## Contributing\n\nIssues and pull requests are welcome.\n\n- **Bug reports**: Open an issue with reproduction steps\n- **Feature ideas**: Open a discussion first\n- **Skills**: Skills are personal by design and not included in this repo\n\n## Credits\n\nBased on [Claude-Code-Communication](https://github.com/Akira-Papa/Claude-Code-Communication) by Akira-Papa.\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**One command. Eight agents. Zero coordination cost.**\n\n⭐ Star this repo if you find it useful — it helps others discover it.\n\n💖 [Sponsor this project](https://github.com/sponsors/yohey-w) to keep it free.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyohey-w%2Fmulti-agent-shogun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyohey-w%2Fmulti-agent-shogun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyohey-w%2Fmulti-agent-shogun/lists"}