[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74914":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":14,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":35,"readmeContent":36,"aiSummary":37,"trendingCount":15,"starSnapshotCount":15,"syncStatus":38,"lastSyncTime":39,"discoverSource":40},74914,"multi-agent-shogun","yohey-w\u002Fmulti-agent-shogun","yohey-w","Samurai-inspired multi-agent system for Claude Code. Orchestrate parallel AI tasks via tmux with shogun → karo → ashigaru hierarchy.",null,"Shell",1335,277,9,4,0,17,73,12,79.13,"MIT License",false,"main",true,[25,26,27,28,29,30,31,32,33,34],"ai-agent","anthropic","automation","claude-code","llm","multi-agent","parallel-processing","samurai","shogun","tmux","2026-06-12 04:01:16","\u003Cdiv align=\"center\">\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:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fyohey-w\u002Fmulti-agent-shogun?style=social)](https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![v3.5 Dynamic Model Routing](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fv3.5-Dynamic_Model_Routing-ff6600?style=flat-square&logo=data:image\u002Fsvg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiI+PHRleHQgeD0iMCIgeT0iMTIiIGZvbnQtc2l6ZT0iMTIiPuKalTwvdGV4dD48L3N2Zz4=)](https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun)\n[![Shell](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FShell%2FBash-100%25-green)]()\n\n[English](README.md) | [日本語](README_ja.md)\n\n\u003C\u002Fdiv>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"images\u002Fscreenshots\u002Fhero\u002Flatest-translucent-20260210-190453.png\" alt=\"Latest translucent command session in the Shogun pane\" width=\"940\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"images\u002Fscreenshots\u002Fhero\u002Flatest-translucent-20260208-084602.png\" alt=\"Quick natural-language command in the Shogun pane\" width=\"420\">\n  \u003Cimg src=\"images\u002Fcompany-creed-all-panes.png\" alt=\"Karo and Ashigaru panes reacting in parallel\" width=\"520\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\u003Ci>One Karo (manager) coordinating 7 Ashigaru (workers) + 1 Gunshi (strategist) — real session, no mock data.\u003C\u002Fi>\u003C\u002Fp>\n\n---\n\n## Quick Start\n\n**Requirements:** tmux, bash 4+, at least one of: [Claude Code](https:\u002F\u002Fclaude.ai\u002Fcode) \u002F Codex \u002F Copilot \u002F Kimi\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\ncd multi-agent-shogun\nbash first_setup.sh                        # one-time setup: config, dependencies, MCP\nsource ~\u002F.bashrc                           # reload PATH\nclaude --dangerously-skip-permissions      # first run only: OAuth + accept Bypass Permissions → \u002Fexit\nbash shutsujin_departure.sh                # launch all agents\n```\n\n> 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> \"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> **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 (上様 \u002F 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\u002FRedis) | API + CrewAI platform | **Zero** (YAML + tmux) |\n| **Multi-CLI** | Claude Code only | Claude Code only | Any LLM API | Any LLM API | **4 CLIs** (Claude\u002FCodex\u002FCopilot\u002FKimi) |\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+\u002Fhour**. CLI subscriptions flip this:\n\n| | API (Per-Token) | CLI (Flat-Rate) |\n|---|---|---|\n| **8 agents × Opus** | ~$100+\u002Fhour | ~$200\u002Fmonth |\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\u002FWrite\u002FEdit\u002FGlob\u002FGrep) | Claude Sonnet 4.6 |\n| **OpenAI Codex** | Sandbox execution, JSONL structured output, `codex exec` headless mode, **per-model `--model` flag** | gpt-5.3-codex \u002F **gpt-5.3-codex-spark** |\n| **GitHub Copilot** | Built-in GitHub MCP, 4 specialized agents (Explore\u002FTask\u002FPlan\u002FCode-review), `\u002Fdelegate` 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\u002F\n├── common\u002F              # Shared rules (all CLIs)\n├── cli_specific\u002F        # CLI-specific tool descriptions\n│   ├── claude_tools.md  # Claude Code tools & features\n│   └── copilot_tools.md # GitHub Copilot CLI tools & features\n└── roles\u002F               # Role definitions (shogun, karo, ashigaru)\n    ↓ build\nCLAUDE.md \u002F AGENTS.md \u002F 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\u002Fcommands\u002F\n    ↓\nAny agent can now invoke \u002Fapi-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>\n\u003Ctr>\n\u003Ctd width=\"60\">\n\n**Step 1**\n\n\u003C\u002Ftd>\n\u003Ctd>\n\n📥 **Download the repository**\n\n[Download ZIP](https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Farchive\u002Frefs\u002Fheads\u002Fmain.zip) and extract to `C:\\tools\\multi-agent-shogun`\n\n*Or use git:* `git clone https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun.git C:\\tools\\multi-agent-shogun`\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\n\n**Step 2**\n\n\u003C\u002Ftd>\n\u003Ctd>\n\n🖱️ **Run `install.bat`**\n\nRight-click → \"Run as Administrator\" (if WSL2 is not installed). Sets up WSL2 + Ubuntu automatically.\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\n\n**Step 3**\n\n\u003C\u002Ftd>\n\u003Ctd>\n\n🐧 **Open Ubuntu and run** (first time only)\n\n```bash\ncd \u002Fmnt\u002Fc\u002Ftools\u002Fmulti-agent-shogun\n.\u002Ffirst_setup.sh\n```\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\n\n**Step 4**\n\n\u003C\u002Ftd>\n\u003Ctd>\n\n✅ **Deploy!**\n\n```bash\n.\u002Fshutsujin_departure.sh\n```\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\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 ~\u002F.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 \u002Fexit to quit\n```\n\nThis saves credentials to `~\u002F.claude\u002F` — you won't need to do it again.\n\n#### Daily startup\n\nOpen an **Ubuntu terminal** (WSL) and run:\n\n```bash\ncd \u002Fmnt\u002Fc\u002Ftools\u002Fmulti-agent-shogun\n.\u002Fshutsujin_departure.sh\n```\n\n### 📱 Mobile Access — Dedicated Android App (Recommended)\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"android\u002Fscreenshots\u002F01_shogun_terminal.png\" alt=\"Shogun Terminal\" width=\"200\">\n  \u003Cimg src=\"android\u002Fscreenshots\u002F02_agents_grid.png\" alt=\"Agents Grid\" width=\"200\">\n  \u003Cimg src=\"android\u002Fscreenshots\u002F03_dashboard.png\" alt=\"Dashboard\" width=\"200\">\n\u003C\u002Fp>\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\u002Fcopy |\n| **Rate Limit** | Tap the FAB on the Agents tab to check Claude Max 5h\u002F7d 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> **Note:** Android only for now. No iOS version — the developer doesn't own an iPhone. If there's demand, please open an [Issue](https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Fissues). 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:\u002F\u002Ftailscale.com\u002F))\n\n**Steps:**\n\n1. **Install APK**\n   1. Download [`android\u002Frelease\u002Fmulti-agent-shogun.apk`](android\u002Frelease\u002Fmulti-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 | `\u002Fdata\u002Fdata\u002F...\u002Fid_ed25519` | Private key path on phone (*1) |\n   | SSH Password | `****` | Use if no key available |\n   | Project Path | `\u002Fmnt\u002Fc\u002Ftools\u002Fmulti-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:\u002F\u002Ftailscale.com\u002Finstall.sh | sh\nsudo tailscaled &\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>\n\u003Csummary>📟 \u003Cb>Termux Method (without the Android app)\u003C\u002Fb> (click to expand)\u003C\u002Fsummary>\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:\u002F\u002Ftailscale.com\u002F) | 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:\u002F\u002Ftermux.dev\u002F) | 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:\u002F\u002Ftailscale.com\u002Finstall.sh | sh\n   sudo tailscaled &\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 && 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\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>🐧 \u003Cb>Linux \u002F macOS\u003C\u002Fb> (click to expand)\u003C\u002Fsummary>\n\n### First-time setup\n\n```bash\n# 1. Clone\ngit clone https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun.git ~\u002Fmulti-agent-shogun\ncd ~\u002Fmulti-agent-shogun\n\n# 2. Make scripts executable\nchmod +x *.sh\n\n# 3. Run first-time setup\n.\u002Ffirst_setup.sh\n```\n\n### Daily startup\n\n```bash\ncd ~\u002Fmulti-agent-shogun\n.\u002Fshutsujin_departure.sh\n```\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>❓ \u003Cb>What is WSL2? Why is it needed?\u003C\u002Fb> (click to expand)\u003C\u002Fsummary>\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\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>📋 \u003Cb>Script Reference\u003C\u002Fb> (click to expand)\u003C\u002Fsummary>\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\u002Fswitch_cli.sh` | Live switch agent CLI\u002Fmodel (settings.yaml → \u002Fexit → 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\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>🔧 \u003Cb>Manual Requirements\u003C\u002Fb> (click to expand)\u003C\u002Fsummary>\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:\u002F\u002Fclaude.ai\u002Finstall.sh \\| bash` | Official Anthropic CLI (native version recommended; npm version deprecated) |\n\n\u003C\u002Fdetails>\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### Project-Unit Operation (Equivalent to Visual Studio \"Solution\")\n\nOnce set up, the Shogun system can handle **multiple projects under the same Shogun**, switching between them as needed. The unit equivalent to a Visual Studio \"solution\" is `projects\u002F{name}.yaml` + `context\u002F{name}.md`.\n\n#### 1. Running your first project\n\n```bash\n# (1) Connect to the Shogun (after shutsujin_departure.sh completes)\ntmux attach-session -t shogun\n\n# (2) Just give the Shogun your command — the project starts automatically\n#     → Shogun writes cmd to queue\u002Fshogun_to_karo.yaml and notifies Karo\n#     → Karo distributes to Ashigaru for parallel execution\n#     → Results aggregate in dashboard.md\n```\n\nNo explicit \"create a project\" command is needed. The Shogun attaches a `project:` field to the cmd when relevant, and related files are automatically separated.\n\n#### 2. Explicitly registering a project (optional, for long-term work)\n\nFor ongoing projects, you can place metadata in `projects\u002F{name}.yaml`:\n\n```yaml\n# projects\u002Fexample.yaml\nid: example\nname: \"Sample Project\"\nworking_directory: \u002Fpath\u002Fto\u002Frepo\nnorth_star: \"The ultimate goal for this project\"\nnotes: |\n  Project-specific notes, stakeholders, special rules\n```\n\nThe Shogun and Karo reference this file and inject project context when issuing cmds.\n\nDetailed project knowledge (requirements, design, past feedback) lives in `context\u002F{name}.md`. When the Shogun issues a cmd related to the project, it automatically references this file.\n\n#### 3. Customizing the agent formation\n\nThe agent formation (which CLI each agent uses) lives in `config\u002Fsettings.yaml`:\n\n```yaml\nagents:\n  cli_assignments:\n    ashigaru1:\n      type: codex          # codex \u002F claude \u002F copilot \u002F kimi\n      model: gpt-5.5\n    ashigaru2:\n      type: claude\n      model: claude-sonnet-4-6\n    # Same for ashigaru3-7, gunshi, karo\n```\n\nTo switch on the fly, use `scripts\u002Fswitch_cli.sh`:\n\n```bash\nbash scripts\u002Fswitch_cli.sh ashigaru3 --type claude --model claude-sonnet-4-6\n```\n\n#### 4. Switching or closing a project\n\nThere is no explicit \"close project\" command. **Issuing the next project's cmd automatically switches context.**\n\n- Pause temporarily: do nothing. Old cmds remain in `queue\u002F` as history, and the Shogun restores state when resumed\n- Fully retire: delete `projects\u002F{name}.yaml`, or add an `archived: true` flag\n- Run in parallel: use the `project:` field in cmds to keep concurrent projects distinct\n\n#### 5. Carrying experience and settings between projects\n\nWhat carries forward to future projects:\n\n| What carries forward | Stored in | Referenced when |\n|----------------------|-----------|-----------------|\n| Lord's preferences and lessons | Memory MCP (persistent) | All agents at Session Start |\n| Project-specific knowledge | `context\u002F{name}.md` | When running the project's cmds |\n| Past cmd history | `queue\u002Fshogun_to_karo.yaml` | When the Shogun needs it |\n| Custom skills | `~\u002F.claude\u002Fskills\u002F`, `skills\u002F` | When matching triggers fire |\n| Agent formation | `config\u002Fsettings.yaml` | At shutsujin startup |\n\n**Memory MCP** is the heart of \"experience.\" When you tell the Shogun \"don't do X next time\" or \"remember Y,\" the Shogun records it in Memory MCP, and all future projects see it.\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\u002Fshogun_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\">\n  \u003Cimg src=\"images\u002Fcompany-creed-all-panes.png\" alt=\"Ashigaru agents working in parallel across tmux panes\" width=\"900\">\n\u003C\u002Fp>\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\u002Fsettings.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 (`\u002Ftmp\u002Fshogun_idle_{agent}`) to distinguish busy vs idle agents. The Stop hook creates\u002Fremoves this flag at turn boundaries. This eliminates nudge interruptions during active work while still waking idle agents.\n\n> **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\u002Fsettings.yaml`:\n```yaml\nasw_phase: 2   # Recommended for Claude Code setups\n```\n\nOr set the default directly in `scripts\u002Finbox_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 `\u002Fclear` 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\u002Finbox info\nbash scripts\u002Fagent_status.sh\n\n# Standalone mode: works with any tmux session\nbash scripts\u002Fagent_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\u002Fspinner patterns in the bottom 5 lines of each tmux pane. The detection logic lives in `lib\u002Fagent_status.sh` — source it in your own scripts:\n\n```bash\nsource lib\u002Fagent_status.sh\nagent_is_busy_check \"multiagent:agents.3\" && 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\u002Fsettings.yaml\nscreenshot:\n  path: \"\u002Fmnt\u002Fc\u002FUsers\u002FYourName\u002FPictures\u002FScreenshots\"\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\u002Fafter 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\u002Fshogun_memory.jsonl` | Cross-project, cross-session long-term memory |\n| Layer 2: Project | `config\u002Fprojects.yaml`, `projects\u002F\u003Cid>.yaml`, `context\u002F{project}.md` | Project-specific information and technical knowledge |\n| Layer 3: YAML Queue | `queue\u002Fshogun_to_karo.yaml`, `queue\u002Ftasks\u002F`, `queue\u002Freports\u002F` | Task management — source of truth for instructions and reports |\n| Layer 4: Session | CLAUDE.md, instructions\u002F*.md | Working context (wiped by `\u002Fclear`) |\n\n#### Persistent Agent Memory (`memory\u002FMEMORY.md`)\n\nShogun reads `memory\u002FMEMORY.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\u002F            │   │ projects\u002Fclient.yaml  ←──┐ │    │\n│  │ instructions\u002F       │   │ context\u002Fmy-notes.md   ←──┤ │    │\n│  │ lib\u002F                │   │ queue\u002Fshogun_to_karo.yaml │ │    │\n│  │ memory\u002F             │   │ memory\u002FMEMORY.md      ←──┘ │    │\n│  │  ├─ MEMORY.md.sample│   │ config\u002Fsettings.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\u002FMEMORY.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 ~\u002F.shogun-private.git\nalias privategit='git --git-dir=$HOME\u002F.shogun-private.git --work-tree=\u002Fpath\u002Fto\u002Fmulti-agent-shogun'\nprivategit remote add origin https:\u002F\u002Fgithub.com\u002FYOU\u002Fshogun-private.git\n\n# Daily use\nprivategit add -f memory\u002FMEMORY.md projects\u002Fmy-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\u002FMEMORY.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#### \u002Fclear Protocol (Cost Optimization)\n\nAs agents work, their session context (Layer 4) grows, increasing API costs. `\u002Fclear` wipes session memory and resets costs. Layers 1–3 persist as files, so nothing is lost.\n\nRecovery cost after `\u002Fclear`: **~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\u002Fntfy.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\u002Fsettings.yaml`\n2. Install the [ntfy app](https:\u002F\u002Fntfy.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\u002F5 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\u002F12 tasks today` |\n\nFree, no account required, no server to maintain. Uses [ntfy.sh](https:\u002F\u002Fntfy.sh) — an open-source push notification service.\n\n> **⚠️ 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\u002Fntfy.sh \"Test notification from Shogun 🏯\"\n```\n\nIf your phone receives the notification, you're all set. If not, check:\n- `config\u002Fsettings.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\u002Fntfy_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\u002Fntfy_listener.sh &>\u002Fdev\u002Fnull &\n\n# Check if it's running\npgrep -f ntfy_listener.sh\n\n# View listener logs (stderr output)\nbash scripts\u002Fntfy_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\u002Fntfy_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\u002Fntfy_inbox.yaml` — if message is there, Shogun may be busy |\n| \"ntfy_topic not configured\" error | Add `ntfy_topic: \"your-topic\"` to `config\u002Fsettings.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 && nohup bash scripts\u002Fntfy_listener.sh &>\u002Fdev\u002Fnull &` |\n\n**Real-world notification screenshots:**\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"images\u002Fscreenshots\u002Fmasked\u002Fntfy_saytask_rename.jpg\" alt=\"Bidirectional phone communication\" width=\"300\">\n    \n  \u003Cimg src=\"images\u002Fscreenshots\u002Fmasked\u002Fntfy_cmd043_progress.jpg\" alt=\"Progress notification\" width=\"300\">\n\u003C\u002Fp>\n\u003Cp align=\"center\">\u003Ci>Left: Bidirectional phone ↔ Shogun communication · Right: Real-time progress report from Ashigaru\u003C\u002Fi>\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"images\u002Fscreenshots\u002Fmasked\u002Fntfy_bloom_oc_test.jpg\" alt=\"Command completion notification\" width=\"300\">\n    \n  \u003Cimg src=\"images\u002Fscreenshots\u002Fmasked\u002Fntfy_persona_eval_complete.jpg\" alt=\"8-agent parallel completion\" width=\"300\">\n\u003C\u002Fp>\n\u003Cp align=\"center\">\u003Ci>Left: Command completion notification · Right: All 8 Ashigaru completing in parallel\u003C\u002Fi>\u003C\u002Fp>\n\n> *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\u002Fstreaks.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\u002F12 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.\u002Fshutsujin_departure.sh --silent    # No battle cries\n.\u002Fshutsujin_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> *\"Your enemy isn't other apps — it's doing nothing.\"*\n\n### How it Works\n\n1. Install the [ntfy app](https:\u002F\u002Fntfy.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 \u002F After\n\n| Before (v1) | After (v2) |\n|:-----------:|:----------:|\n| ![Task list v1](images\u002Fscreenshots\u002Fmasked\u002Fntfy_tasklist_v1_before.jpg) | ![Task list v2](images\u002Fscreenshots\u002Fmasked\u002Fntfy_tasklist_v2_aligned.jpg) |\n| Raw task dump | Clean, organized daily summary |\n\n> *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\u002Ffalse` per agent in `config\u002Fsettings.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 `\u002Fshogun-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\u002Ftasks\u002Fashigaru2.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\u002Fsettings.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| `\u002Fshogun-model-list` | Reference table: all models × subscriptions × Bloom max |\n| `\u002Fshogun-bloom-config` | Interactive: answer 2 questions → get ready-to-paste YAML |\n\nRun `\u002Fshogun-bloom-config` after setup to generate your optimal `capability_tiers` configuration.\n\n---\n\n## Philosophy\n\n> \"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\u002Fphilosophy.md](docs\u002Fphilosophy.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 `\u002Fskill-name`. Just tell the Shogun: \"run \u002Fskill-name\".\n\n### Included Skills (committed to repo)\n\nSkills ship with the repository in `skills\u002F`. They are domain-agnostic utilities useful for any user:\n\n| Skill | Description |\n|-------|-------------|\n| `\u002Fskill-creator` | Template and guide for creating new skills |\n| `\u002Fshogun-agent-status` | Show busy\u002Fidle status of all agents with task and inbox info |\n| `\u002Fshogun-model-list` | Reference table: all CLI tools × models × subscriptions × Bloom max level |\n| `\u002Fshogun-bloom-config` | Interactive configurator: answer 2 questions about your subscriptions → get ready-to-paste `capability_tiers` YAML |\n| `\u002Fshogun-model-switch` | Live CLI\u002Fmodel switching: settings.yaml update → `\u002Fexit` → relaunch with correct flags. Supports Thinking ON\u002FOFF control |\n| `\u002Fshogun-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\u002Fcommands\u002F` 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\u002Fnotion-mcp-server\n\n# 2. Playwright - Browser automation\nclaude mcp add playwright -- npx @playwright\u002Fmcp@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\u002Fserver-github\n\n# 4. Sequential Thinking - Step-by-step reasoning for complex problems\nclaude mcp add sequential-thinking -- npx -y @modelcontextprotocol\u002Fserver-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\u002Fmemory\u002Fshogun_memory.jsonl\" -- npx -y @modelcontextprotocol\u002Fserver-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\u002Fsettings.yaml\nlanguage: ja   # Samurai Japanese only\nlanguage: en   # Samurai Japanese + English translation\n```\n\n### Screenshot integration\n\n```yaml\n# config\u002Fsettings.yaml\nscreenshot:\n  path: \"\u002Fmnt\u002Fc\u002FUsers\u002FYourName\u002FPictures\u002FScreenshots\"\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\u002Fsettings.yaml\nntfy_topic: \"shogun-yourname\"\n```\n\nSubscribe to the same topic in the [ntfy app](https:\u002F\u002Fntfy.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\u002Fntfy_auth.env.sample config\u002Fntfy_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>`) |\n| **Basic Auth** | `NTFY_USER=username` + `NTFY_PASS=password` | Self-hosted ntfy with user\u002Fpassword |\n| **None** (default) | Leave file empty or don't create it | Public ntfy.sh — no auth needed |\n\nPriority: Token > Basic > None. If neither is set, no auth headers are sent (backward compatible).\n\n`config\u002Fntfy_auth.env` is excluded from git. See `config\u002Fntfy_auth.env.sample` for details.\n\n---\n\n## Advanced\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Script Architecture\u003C\u002Fb> (click to expand)\u003C\u002Fsummary>\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                    First-Time Setup (run once)                       │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  install.bat (Windows)                                              │\n│      │                                                              │\n│      ├── Check\u002Fguide WSL2 installation                              │\n│      └── Check\u002Fguide Ubuntu installation                            │\n│                                                                     │\n│  first_setup.sh (run manually in Ubuntu\u002FWSL)                        │\n│      │                                                              │\n│      ├── Check\u002Finstall tmux                                         │\n│      ├── Check\u002Finstall Node.js v20+ (via nvm)                      │\n│      ├── Check\u002Finstall 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\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>shutsujin_departure.sh Options\u003C\u002Fb> (click to expand)\u003C\u002Fsummary>\n\n```bash\n# Default: Full startup (tmux sessions + Claude Code launch)\n.\u002Fshutsujin_departure.sh\n\n# Session setup only (no Claude Code launch)\n.\u002Fshutsujin_departure.sh -s\n.\u002Fshutsujin_departure.sh --setup-only\n\n# Clean task queues (preserves command history)\n.\u002Fshutsujin_departure.sh -c\n.\u002Fshutsujin_departure.sh --clean\n\n# Battle formation: All Ashigaru on Opus (max capability, higher cost)\n.\u002Fshutsujin_departure.sh -k\n.\u002Fshutsujin_departure.sh --kessen\n\n# Silent mode: Disable battle cries (saves API tokens on echo calls)\n.\u002Fshutsujin_departure.sh -S\n.\u002Fshutsujin_departure.sh --silent\n\n# Full startup + open Windows Terminal tabs\n.\u002Fshutsujin_departure.sh -t\n.\u002Fshutsujin_departure.sh --terminal\n\n# Shogun relay-only mode: Disable Shogun's thinking (cost savings)\n.\u002Fshutsujin_departure.sh --shogun-no-thinking\n\n# Show help\n.\u002Fshutsujin_departure.sh -h\n.\u002Fshutsujin_departure.sh --help\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Common Workflows\u003C\u002Fb> (click to expand)\u003C\u002Fsummary>\n\n**Normal daily use:**\n```bash\n.\u002Fshutsujin_departure.sh          # Launch everything\ntmux attach-session -t shogun     # Connect and give commands\n```\n\n**Debug mode (manual control):**\n```bash\n.\u002Fshutsujin_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.\u002Fshutsujin_departure.sh\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Convenient Aliases\u003C\u002Fb> (click to expand)\u003C\u002Fsummary>\n\nRunning `first_setup.sh` automatically adds these aliases to `~\u002F.bashrc`:\n\n```bash\nalias csst='cd \u002Fmnt\u002Fc\u002Ftools\u002Fmulti-agent-shogun && .\u002Fshutsujin_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 ~\u002F.bashrc` or restart your terminal (PowerShell: `wsl --shutdown` then reopen).\n\n\u003C\u002Fdetails>\n\n---\n\n## File Structure\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Click to expand file structure\u003C\u002Fb>\u003C\u002Fsummary>\n\n```\nmulti-agent-shogun\u002F\n│\n│  ┌──────────────── Setup Scripts ────────────────────┐\n├── install.bat               # Windows: First-time setup\n├── first_setup.sh            # Ubuntu\u002FMac: First-time setup\n├── shutsujin_departure.sh    # Daily deployment (auto-loads instructions)\n│  └──────────────────────────────────────────────────┘\n│\n├── instructions\u002F             # 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\u002F         # CLI-specific tool descriptions\n│       ├── claude_tools.md   # Claude Code tools & features\n│       └── copilot_tools.md  # GitHub Copilot CLI tools & features\n│\n├── lib\u002F\n│   ├── agent_status.sh       # Shared busy\u002Fidle detection (Claude Code + Codex)\n│   ├── cli_adapter.sh        # Multi-CLI adapter (Claude\u002FCodex\u002FCopilot\u002FKimi)\n│   └── ntfy_auth.sh          # ntfy authentication helper\n│\n├── scripts\u002F                  # Utility scripts\n│   ├── agent_status.sh       # Show busy\u002Fidle 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\u002Fmodel switching (\u002Fexit → relaunch)\n│   ├── ntfy.sh               # Send push notifications to phone\n│   └── ntfy_listener.sh      # Stream incoming messages from phone\n│\n├── config\u002F\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\u002F                 # Project details (excluded from git, contains confidential info)\n│   └── \u003Cproject_id>.yaml    # Full info per project (clients, tasks, Notion links, etc.)\n│\n├── queue\u002F                    # Communication files\n│   ├── shogun_to_karo.yaml   # Shogun → Karo commands\n│   ├── ntfy_inbox.yaml       # Incoming messages from phone (ntfy)\n│   ├── inbox\u002F                # 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\u002F                # Per-worker task files\n│   └── reports\u002F              # Worker reports\n│\n├── saytask\u002F                  # Behavioral psychology-driven motivation\n│ ","multi-agent-shogun 是一个用于并行运行多个 AI 编码代理的系统，通过 tmux 以类似日本封建军队的层级结构（大将 → 家老 → 足轻）进行管理。其核心功能包括支持 Claude Code、OpenAI Codex、GitHub Copilot 和 Kimi Code 等多种 AI 编码工具，并能够同时启动7个执行任务的工人代理和1个策略制定者，实现零协调开销下的高效协作。该项目采用 Shell 脚本编写，适合需要快速开发或处理大量编码任务的场景，如构建 REST API 或其他复杂软件项目时使用，极大地提高了开发效率。",2,"2026-06-11 03:51:23","high_star"]