[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-yohey-w--multi-agent-shogun":3,"tool-yohey-w--multi-agent-shogun":64},[4,17,27,35,43,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",138956,2,"2026-04-05T11:33:21",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},3704,"NextChat","ChatGPTNextWeb\u002FNextChat","NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。\n\n这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。\n\nNextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。",87618,"2026-04-05T07:20:52",[13,26],{"id":44,"name":45,"github_repo":46,"description_zh":47,"stars":48,"difficulty_score":23,"last_commit_at":49,"category_tags":50,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,51,52,53,15,54,26,13,55],"数据工具","视频","插件","其他","音频",{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,54],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":70,"readme_en":71,"readme_zh":72,"quickstart_zh":73,"use_case_zh":74,"hero_image_url":75,"owner_login":76,"owner_name":77,"owner_avatar_url":78,"owner_bio":79,"owner_company":79,"owner_location":80,"owner_email":79,"owner_twitter":81,"owner_website":79,"owner_url":82,"languages":83,"stars":104,"forks":105,"last_commit_at":106,"license":107,"difficulty_score":23,"env_os":108,"env_gpu":109,"env_ram":109,"env_deps":110,"category_tags":120,"github_topics":121,"view_count":23,"oss_zip_url":79,"oss_zip_packed_at":79,"status":16,"created_at":131,"updated_at":132,"faqs":133,"releases":162},3656,"yohey-w\u002Fmulti-agent-shogun","multi-agent-shogun","Samurai-inspired multi-agent system for Claude Code. Orchestrate parallel AI tasks via tmux with shogun → karo → ashigaru hierarchy.","multi-agent-shogun 是一款受日本封建军事体系启发的多智能体协作工具，旨在让开发者像“大名”指挥军队一样，高效调度多个 AI 编程助手并行工作。它支持同时运行 Claude Code、OpenAI Codex、GitHub Copilot 和 Kimi Code 等主流模型，通过独特的“将军（Shogun）→家老（Karo）→足轻（Ashigaru）”层级架构，将复杂的开发任务自动拆解并分发给多个 Agent 同步执行。\n\n该工具主要解决了传统多智能体框架中协调成本高、任务串行导致效率低下的痛点。大多数同类方案需要消耗大量 API Token 进行内部沟通，而 multi-agent-shogun 利用 tmux 终端复用技术和 YAML 配置实现零开销的任务编排，无需额外的数据库或复杂基础设施，即可让 7 个执行 Agent 与 1 个策略 Agent 实时协同，大幅缩短等待时间。\n\n其技术亮点在于基于 Shell 和 Bash 的轻量级设计，结合 Memory MCP 机制让 AI 能够跨会话记忆用户偏好。用户只需在终端输入自然语言指令（如“构建一个用户认证 RES","multi-agent-shogun 是一款受日本封建军事体系启发的多智能体协作工具，旨在让开发者像“大名”指挥军队一样，高效调度多个 AI 编程助手并行工作。它支持同时运行 Claude Code、OpenAI Codex、GitHub Copilot 和 Kimi Code 等主流模型，通过独特的“将军（Shogun）→家老（Karo）→足轻（Ashigaru）”层级架构，将复杂的开发任务自动拆解并分发给多个 Agent 同步执行。\n\n该工具主要解决了传统多智能体框架中协调成本高、任务串行导致效率低下的痛点。大多数同类方案需要消耗大量 API Token 进行内部沟通，而 multi-agent-shogun 利用 tmux 终端复用技术和 YAML 配置实现零开销的任务编排，无需额外的数据库或复杂基础设施，即可让 7 个执行 Agent 与 1 个策略 Agent 实时协同，大幅缩短等待时间。\n\n其技术亮点在于基于 Shell 和 Bash 的轻量级设计，结合 Memory MCP 机制让 AI 能够跨会话记忆用户偏好。用户只需在终端输入自然语言指令（如“构建一个用户认证 REST API\"），系统便会自动完成从任务分解到代码生成的全流程，并提供实时进度仪表盘。\n\n这款工具特别适合需要高频使用 AI 辅助编程的软件开发人员、技术团队负责人以及希望探索高效多模型工作流的极客用户。如果你厌倦了逐个等待 AI 响应，或希望在不增加额外协调成本的前提下最大化利用多个大模型的能力，multi-agent-shogun 提供了一个简洁而强大的解决方案。","\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=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_8467acee09d7.png\" alt=\"Latest translucent command session in the Shogun pane\" width=\"940\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_04a03d3125e8.png\" alt=\"Quick natural-language command in the Shogun pane\" width=\"420\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_767cf40f6cbe.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\nbash shutsujin_departure.sh  # launch all agents\n```\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=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_a4d3c917c773.png\" alt=\"Shogun Terminal\" width=\"200\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_2d6613e508df.png\" alt=\"Agents Grid\" width=\"200\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_a75f6983e5a2.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### 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=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_767cf40f6cbe.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=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_e604d0f6f395.jpg\" alt=\"Bidirectional phone communication\" width=\"300\">\n    \n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_ffc3560a7198.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=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_81c4dba5b254.jpg\" alt=\"Command completion notification\" width=\"300\">\n    \n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_c41adc414ef0.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](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_98f5f2d56754.jpg) | ![Task list v2](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_240eefe775a7.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│   └── streaks.yaml          # Streak tracking and daily progress\n│\n├── templates\u002F                # 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\u002F                   # Reusable skills (committed to repo)\n│   ├── skill-creator\u002F        # Skill creation template\n│   ├── shogun-agent-status\u002F  # Agent status display\n│   ├── shogun-model-list\u002F    # Model capability reference\n│   ├── shogun-bloom-config\u002F  # Bloom tier configurator\n│   ├── shogun-model-switch\u002F  # Live CLI\u002Fmodel switching\n│   └── shogun-readme-sync\u002F   # README sync\n│\n├── memory\u002F                   # Memory MCP persistent storage\n├── dashboard.md              # Real-time status board\n└── CLAUDE.md                 # System instructions (auto-loaded)\n```\n\n\u003C\u002Fdetails>\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\u002Fprojects.yaml          # Project list (ID, name, path, status only)\nprojects\u002F\u003Cproject_id>.yaml    # Full details for each project\n```\n\n- **`config\u002Fprojects.yaml`**: A summary list of what projects exist\n- **`projects\u002F\u003Cid>.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\u002F` is excluded from git** (contains confidential client information)\n\n### Example\n\n```yaml\n# config\u002Fprojects.yaml\nprojects:\n  - id: client_x\n    name: \"Client X Consulting\"\n    path: \"\u002Fmnt\u002Fc\u002FConsulting\u002Fclient_x\"\n    status: active\n\n# projects\u002Fclient_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>\n\u003Csummary>\u003Cb>Using npm version of Claude Code CLI?\u003C\u002Fb>\u003C\u002Fsummary>\n\nThe npm version (`npm install -g @anthropic-ai\u002Fclaude-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.\u002Ffirst_setup.sh\n\n# If npm version is detected:\n# ⚠️ npm version of Claude Code CLI detected (officially deprecated)\n# Install native version? [Y\u002Fn]:\n\n# After selecting Y, uninstall npm version:\nnpm uninstall -g @anthropic-ai\u002Fclaude-code\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>MCP tools not loading?\u003C\u002Fb>\u003C\u002Fsummary>\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\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Agents asking for permissions?\u003C\u002Fb>\u003C\u002Fsummary>\n\nAgents should start with `--dangerously-skip-permissions`. This is handled automatically by `shutsujin_departure.sh`.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Workers stuck?\u003C\u002Fb>\u003C\u002Fsummary>\n\n```bash\ntmux attach-session -t multiagent\n# Ctrl+B then 0-8 to switch panes\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Agent crashed?\u003C\u002Fb>\u003C\u002Fsummary>\n\n**Do NOT use `css`\u002F`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\u002Fdetails>\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 `~\u002F.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> **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\u002Fsettings.yaml` maps each model to its Bloom ceiling. L1–L3 → Spark (1000+ tok\u002Fs), 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- **`\u002Fshogun-model-list` skill** — Complete reference table: all CLI tools × models × subscriptions × Bloom max level. Updated for Sonnet 4.6 and Spark positioning\n- **`\u002Fshogun-bloom-config` skill** — Interactive configurator: answer 2 questions about your subscriptions → get ready-to-paste `capability_tiers` YAML\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>What was in v3.4 — Bloom→Agent Routing, E2E Tests, Stop Hook\u003C\u002Fb>\u003C\u002Fsummary>\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 `\u002Fmodel 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\u002Fsettings.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\u002Fslim_yaml.sh` archives read messages and completed commands\n\n\u003C\u002Fdetails>\n\n## What's New in v3.3.2 — GPT-5.3-Codex-Spark Support\n\n> **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\u002Fgpt-5.3-codex-spark`) instead of the generic effort level\n\n## What's New in v3.0 — Multi-CLI\n\n> **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\u002Fcli_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:\u002F\u002Fgithub.com\u002Fyuto-ts) (cli_adapter.sh), [@circlemouth](https:\u002F\u002Fgithub.com\u002Fcirclemouth) (Codex support), [@koba6316](https:\u002F\u002Fgithub.com\u002Fkoba6316) (task routing)\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>What was in v2.0\u003C\u002Fb>\u003C\u002Fsummary>\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\u002FEnter sent separately for Codex CLI). 3-phase escalation: standard nudge (0-2min) → Escape×2+nudge (2-4min) → `\u002Fclear` 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\u002Fdetails>\n\n---\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:\u002F\u002Fgithub.com\u002FAkira-Papa\u002FClaude-Code-Communication) by Akira-Papa.\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n\u003Cdiv align=\"center\">\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\u003C\u002Fdiv>\n","\u003Cdiv align=\"center\">\n\n# multi-agent-shogun\n\n**像封建时代的军阀一样指挥你的AI军团。**\n\n并行运行10个AI编码代理——**Claude Code、OpenAI Codex、GitHub Copilot、Kimi Code**——通过一个受武士文化启发的层级结构进行协调，无需任何协调开销。\n\n**专注于代码，而非氛围。对着手机说话，AI自动执行。**\n\n[![GitHub 星标](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fyohey-w\u002Fmulti-agent-shogun?style=social)](https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun)\n[![许可证：MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![v3.5 动态模型路由](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=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_8467acee09d7.png\" alt=\"Shogun面板中的最新半透明命令会话\" width=\"940\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_04a03d3125e8.png\" alt=\"Shogun面板中的快速自然语言命令\" width=\"420\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_767cf40f6cbe.png\" alt=\"Karo和Ashigaru面板并行响应\" width=\"520\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\u003Ci>一位Karo（管理者）协调7位Ashigaru（工作者）+1位Gunshi（战略家）——真实会话，无模拟数据。\u003C\u002Fi>\u003C\u002Fp>\n\n---\n\n## 快速入门\n\n**要求：** tmux、bash 4+，至少具备以下之一：[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          # 一次性设置：配置、依赖项、MCP\nbash shutsujin_departure.sh  # 启动所有代理\n```\n\n在Shogun面板中输入一条命令：\n\n> “构建一个用于用户认证的REST API”\n\nShogun将任务委派给Karo，Karo再将其分解后交由7位Ashigaru并行执行。你只需观察仪表盘即可。就这么简单。\n\n> **想深入了解吗？** 本README的其余部分将介绍架构、配置、内存设计以及多CLI的设置方法。\n\n---\n\n## 这是什么？\n\n**multi-agent-shogun** 是一个系统，能够同时运行多个AI编码CLI实例，并像日本封建军队一样对它们进行协调。支持 **Claude Code**、**OpenAI Codex**、**GitHub Copilot** 和 **Kimi Code**。\n\n**为什么使用它？**\n- 一条命令即可启动7个AI工作者和1个战略家并行执行\n- 无需等待——任务在后台运行时，你可以立即下达下一条指令\n- AI会在不同会话间记住你的偏好（Memory MCP）\n- 实时进度显示在仪表盘上\n\n```\n        您（上様 \u002F 主人）\n             │\n             ▼  下达命令\n      ┌─────────────┐\n      │   SHOGUN    │  ← 接收您的命令，立即进行委派\n      └──────┬──────┘\n             │  YAML + tmux\n      ┌──────▼──────┐\n      │    KARO     │  ← 将任务分发给工作者\n      └──────┬──────┘\n             │\n    ┌─┬─┬─┬─┴─┬─┬─┬─┬────────┐\n    │1│2│3│4│5│6│7│ GUNSHI │  ← 7位工作者 + 1位战略家\n    └─┴─┴─┴─┴─┴─┴─┴────────┘\n       ASHIGARU      軍師\n```\n\n---\n\n## 为什么是“Shogun”？\n\n大多数多智能体框架都会在协调过程中消耗API调用额度。而Shogun则不会。\n\n| | Claude Code `Task` 工具 | Claude Code Agent Teams | LangGraph | CrewAI | **multi-agent-shogun** |\n|---|---|---|---|---|---|\n| **架构** | 子代理嵌入单个进程内 | 团队负责人+队友（JSON邮箱） | 基于图的状态机 | 基于角色的代理 | 通过tmux实现的封建式层级结构 |\n| **并行性** | 顺序执行（一次一个） | 多个独立会话 | 并行节点（v0.2+） | 有限 | **8个独立代理** |\n| **协调成本** | 每个Task都需要API调用 | 需要大量Token（每个队友都是独立的上下文） | 需要API和基础设施（Postgres\u002FRedis） | 需要API和CrewAI平台 | **零**（YAML + tmux） |\n| **多CLI支持** | 仅Claude Code | 仅Claude Code | 任何LLM API | 任何LLM API | **4种CLI**（Claude\u002FCodex\u002FCopilot\u002FKimi） |\n| **可观测性** | 仅Claude日志 | tmux分屏或进程内 | LangSmith集成 | OpenTelemetry | **实时tmux面板** + 仪表盘 |\n| **技能发现** | 无 | 无 | 无 | 无 | **自下而上的自动提案** |\n| **设置** | 内置在Claude Code中 | 内置（实验性） | 较为复杂（需搭建基础设施） | pip安装 | Shell脚本 |\n\n### 它的独特之处\n\n**零协调开销** —— 代理之间通过磁盘上的YAML文件进行通信。唯一的API调用仅用于实际工作，而非调度协调。运行8个代理，只需为8个代理的工作付费。\n\n**完全透明** —— 每个代理都在可见的tmux面板中运行。每条指令、每份报告和每个决策都以纯文本YAML文件的形式存在，你可以阅读、比较差异并进行版本控制。没有任何黑箱。\n\n**经过实战检验的层级结构** —— Shogun → Karo → Ashigaru的指挥链从设计上避免了冲突：清晰的责任归属、每个代理专属的文件、事件驱动的通信机制，无需轮询。\n\n---\n\n## 为什么选择CLI（而不是API）？\n\n大多数AI编码工具按调用次数收费。通过API运行8个Opus级别的代理，每小时的成本可能高达**100美元以上**。而CLI订阅则颠覆了这一模式：\n\n| | API（按调用次数计费） | CLI（固定费率） |\n|---|---|---|\n| **8个代理 × Opus** | ~100美元+\u002F小时 | ~200美元\u002F月 |\n| **成本可预测性** | 波动难以预料 | 每月固定费用 |\n| **使用顾虑** | 每次调用都算成本 | 无限制 |\n| **实验预算** | 受限 | 可自由部署 |\n\n**“尽情地使用AI吧”** —— 有了固定费率的CLI订阅，你可以毫不犹豫地部署8个代理。无论它们运行1小时还是24小时，成本都是一样的。再也不必在“足够好”和“彻底”之间做出选择——只需运行更多的代理即可。\n\n### 多 CLI 支持\n\nShogun 并不局限于单一厂商。该系统支持 4 种 CLI 工具，每种都有其独特的优势：\n\n| CLI | 关键优势 | 默认模型 |\n|-----|-------------|---------------|\n| **Claude Code** | 经过实战检验的 tmux 集成、Memory MCP、专用文件工具（读取\u002F写入\u002F编辑\u002FGlob\u002FGrep） | Claude Sonnet 4.6 |\n| **OpenAI Codex** | 沙箱执行、JSONL 结构化输出、`codex exec` 无头模式、**按模型设置的 `--model` 标志** | gpt-5.3-codex \u002F **gpt-5.3-codex-spark** |\n| **GitHub Copilot** | 内置 GitHub MCP、4 个专业代理（探索\u002F任务\u002F计划\u002F代码评审）、`\u002Fdelegate` 命令可委派给编码代理 | Claude Sonnet 4.6 |\n| **Kimi Code** | 提供免费层级、强大的多语言支持 | Kimi k2 |\n\n统一的指令构建系统会从共享模板生成特定于 CLI 的指令文件：\n\n```\ninstructions\u002F\n├── common\u002F              # 共享规则（所有 CLI）\n├── cli_specific\u002F        # CLI 特定的工具描述\n│   ├── claude_tools.md  # Claude Code 工具与功能\n│   └── copilot_tools.md # GitHub Copilot CLI 工具与功能\n└── roles\u002F               # 角色定义（shogun、karo、ashigaru）\n    ↓ build\nCLAUDE.md \u002F AGENTS.md \u002F copilot-instructions.md  ← 按每个 CLI 生成\n```\n\n只有一个事实来源，无需同步偏差。只需更改一次规则，所有 CLI 都会自动更新。\n\n---\n\n## 自下而上的技能发现\n\n这是其他框架所不具备的功能。\n\n当 Ashigaru 执行任务时，他们会**自动识别可重用的模式**，并将其作为技能候选提交。Karo 会将这些提案汇总到 `dashboard.md` 中，然后由你——即“领主”——决定哪些技能可以晋升为永久技能。\n\n```\nAshigaru 完成一项任务\n    ↓\n注意到：“我在不同项目中已经完成了这个模式 3 次”\n    ↓\n以 YAML 格式报告：  skill_candidate:\n                     found: true\n                     name: \"api-endpoint-scaffold\"\n                     reason: \"在 3 个项目中都使用了相同的 REST 脚手架模式\"\n    ↓\n出现在 dashboard.md → 你批准 → 技能被创建在 .claude\u002Fcommands\u002F\n    ↓\n任何代理现在都可以调用 \u002Fapi-endpoint-scaffold\n```\n\n技能是从实际工作中有机生长出来的，而不是基于预定义的模板库。你的技能集合将成为你**自身工作流**的反映。\n\n---\n\n## 快速入门\n\n### Windows (WSL2)\n\n\u003Ctable>\n\u003Ctr>\n\u003Ctd width=\"60\">\n\n**步骤 1**\n\n\u003C\u002Ftd>\n\u003Ctd>\n\n📥 **下载仓库**\n\n[下载 ZIP](https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Farchive\u002Frefs\u002Fheads\u002Fmain.zip) 并解压到 `C:\\tools\\multi-agent-shogun`\n\n*或者使用 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**步骤 2**\n\n\u003C\u002Ftd>\n\u003Ctd>\n\n🖱️ **运行 `install.bat`**\n\n右键点击 → “以管理员身份运行”（如果尚未安装 WSL2）。它会自动设置 WSL2 + Ubuntu。\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\n\n**步骤 3**\n\n\u003C\u002Ftd>\n\u003Ctd>\n\n🐧 **打开 Ubuntu 并运行**（仅首次）\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**步骤 4**\n\n\u003C\u002Ftd>\n\u003Ctd>\n\n✅ **部署！**\n\n```bash\n.\u002Fshutsujin_departure.sh\n```\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n#### 仅首次：认证\n\n在运行 `first_setup.sh` 后，需执行以下命令进行一次性认证：\n\n```bash\n# 1. 应用 PATH 变更\nsource ~\u002F.bashrc\n\n# 2. OAuth 登录 + 绕过权限审批（一条命令）\nclaude --dangerously-skip-permissions\n#    → 浏览器打开 → 使用 Anthropic 账户登录 → 返回 CLI\n#    → 出现“绕过权限”提示 → 选择“是，我接受”（↓至选项 2，Enter）\n#    → 输入 \u002Fexit 退出\n```\n\n这会将凭据保存到 `~\u002F.claude\u002F` — 以后无需再次操作。\n\n#### 日常启动\n\n打开一个 **Ubuntu 终端**（WSL），并运行：\n\n```bash\ncd \u002Fmnt\u002Fc\u002Ftools\u002Fmulti-agent-shogun\n.\u002Fshutsujin_departure.sh\n```\n\n### 📱 移动访问 — 专用 Android 应用程序（推荐）\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_a4d3c917c773.png\" alt=\"Shogun Terminal\" width=\"200\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_2d6613e508df.png\" alt=\"Agents Grid\" width=\"200\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_a75f6983e5a2.png\" alt=\"Dashboard\" width=\"200\">\n\u003C\u002Fp>\n\n通过专用的 Android 伴侣应用，您可以在手机上监控并指挥 10 个 AI 代理。\n\n| 功能 | 描述 |\n|---------|-------------|\n| **Shogun Terminal** | SSH 终端 + 语音输入 + 特殊功能键栏（C-c、C-b、Tab 等） |\n| **Agents Grid** | 9 格同时监控。点击可展开全屏并发送命令 |\n| **Dashboard** | 渲染 dashboard.md，并支持完整表格文本选择和复制 |\n| **速率限制** | 在 Agents 标签页点击 FAB 按钮，即可查看 Claude Max 5h\u002F7d 的使用情况及进度条 |\n| **语音输入** | 使用 Google Speech API 进行日语连续识别，准确率高于手机键盘语音输入 |\n| **截图分享** | 通过 Android 分享菜单分享图片 → SFTP 传输至服务器 |\n\n> **注意：** 目前仅支持 Android。暂无 iOS 版本——因为开发者本人没有 iPhone。如有需求，请在 [Issue](https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Fissues) 中提出。欢迎提交 PR！\n\n#### 设置\n\n**先决条件：**\n- Shogun 系统正在 WSL2 上运行（或 Linux 服务器）\n- SSH 服务器已启动（`sudo service ssh start`）\n- 手机和服务器处于同一网络（局域网或 [Tailscale](https:\u002F\u002Ftailscale.com\u002F)）\n\n**步骤：**\n\n1. **安装 APK**\n   1. 在手机上下载 [`android\u002Frelease\u002Fmulti-agent-shogun.apk`](android\u002Frelease\u002Fmulti-agent-shogun.apk)（在 GitHub 上打开文件 → “下载原始文件”）\n   2. 点击下载通知 → “安装”\n   3. 如果出现“未知来源”警告 → 进入“设置” → 为浏览器启用“允许从此来源安装” → 返回 → “安装”\n   4. 完成后 → “打开”\n\n2. **配置 SSH**（设置标签页）\n\n   | 字段 | 示例 | 描述 |\n   |-------|---------|-------------|\n   | SSH 主机 | `100.xxx.xxx.xxx` | 服务器 IP 地址（例如 Tailscale IP） |\n   | SSH 端口 | `22` | 通常为 22 |\n   | SSH 用户 | `your_username` | SSH 登录用户名 |\n   | SSH 密钥路径 | `\u002Fdata\u002Fdata\u002F...\u002Fid_ed25519` | 手机上的私钥路径 (*1) |\n   | SSH 密码 | `****` | 如果没有密钥可用，则使用密码 |\n   | 项目路径 | `\u002Fmnt\u002Fc\u002Ftools\u002Fmulti-agent-shogun` | 服务器端的项目目录 |\n   | Shogun 会话 | `shogun` | Shogun 的 tmux 会话名称 |\n   | 代理会话 | `multiagent` | 代理的 tmux 会话名称 |\n\n   *1 将您的私钥传输到手机，或使用密码认证\n\n3. **保存 → 切换到 Shogun 标签页** → 自动连接\n\n**使用 Tailscale（随时随地连接）：**\n\n```bash\n\n# 服务器端（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\n在手机上安装 Tailscale 应用程序，使用相同的账户登录，并将显示的 Tailscale IP 地址作为应用程序中的 SSH 主机。\n\n**使用 ntfy 通知：**\n\n请参阅 [ntfy 设置部分](#-8-phone-notifications-ntfy)，了解 Karo 在任务完成后发送的推送通知。\n\n\u003Cdetails>\n\u003Csummary>📟 \u003Cb>Termux 方法（无需 Android 应用）\u003C\u002Fb>（点击展开）\u003C\u002Fsummary>\n\n通过 Termux 使用 SSH 也是可行的。虽然功能比专用应用有限，但不需要侧载 APK。\n\n**要求（全部免费）：**\n\n| 名称 | 简介 | 作用 |\n|------|--------------|------|\n| [Tailscale](https:\u002F\u002Ftailscale.com\u002F) | 从任何地方连接到你的家 | 从任何地方连接到你的家用电脑 |\n| SSH | 走这条路的脚 | 通过 Tailscale 登录到你的家用电脑 |\n| [Termux](https:\u002F\u002Ftermux.dev\u002F) | 你手机上的黑屏 | 使用 SSH 所需——只需安装即可 |\n\n**设置：**\n\n1. 在 WSL 和你的手机上都安装 Tailscale\n2. 在 WSL 中（使用认证密钥方法——无需浏览器）：\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. 在你手机的 Termux 中：\n   ```sh\n   pkg update && pkg install openssh\n   ssh youruser@your-tailscale-ip\n   css    # 连接到 Shogun\n   ```\n4. 打开一个新的 Termux 窗口（+ 按钮）用于工人：\n   ```sh\n   ssh youruser@your-tailscale-ip\n   csm    # 查看所有 9 个面板\n   ```\n\n**断开连接：** 只需滑动关闭 Termux 窗口即可。tmux 会话会继续运行——代理们会继续工作。\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>🐧 \u003Cb>Linux \u002F macOS\u003C\u002Fb>（点击展开）\u003C\u002Fsummary>\n\n### 首次设置\n\n```bash\n# 1. 克隆\ngit clone https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun.git ~\u002Fmulti-agent-shogun\ncd ~\u002Fmulti-agent-shogun\n\n# 2. 将脚本设为可执行\nchmod +x *.sh\n\n# 3. 运行首次设置\n.\u002Ffirst_setup.sh\n```\n\n### 每日启动\n\n```bash\ncd ~\u002Fmulti-agent-shogun\n.\u002Fshutsujin_departure.sh\n```\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>❓ \u003Cb>什么是 WSL2？为什么需要它？\u003C\u002Fb>（点击展开）\u003C\u002Fsummary>\n\n### 关于 WSL2\n\n**WSL2（Windows Subsystem for Linux）** 允许你在 Windows 内部运行 Linux。该系统使用 `tmux`（一种 Linux 工具）来管理多个 AI 代理，因此在 Windows 上需要 WSL2。\n\n### 如果你还没有 WSL2\n\n没关系！运行 `install.bat` 将会：\n1. 检查是否已安装 WSL2（如果未安装则自动安装）\n2. 检查是否已安装 Ubuntu（如果未安装则自动安装）\n3. 引导你完成后续步骤（运行 `first_setup.sh`）\n\n**快速安装命令**（以管理员身份运行 PowerShell）：\n```powershell\nwsl --install\n```\n\n然后重启计算机并再次运行 `install.bat`。\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>📋 \u003Cb>脚本参考\u003C\u002Fb>（点击展开）\u003C\u002Fsummary>\n\n| 脚本 | 目的 | 何时运行 |\n|--------|---------|-------------|\n| `install.bat` | Windows：WSL2 + Ubuntu 设置 | 仅首次 |\n| `first_setup.sh` | 安装 tmux、Node.js、Claude Code CLI + Memory MCP 配置 | 仅首次 |\n| `shutsujin_departure.sh` | 创建 tmux 会话 + 启动 CLI + 加载指令 + 启动 ntfy 监听器 | 每日 |\n| `scripts\u002Fswitch_cli.sh` | 实时切换代理 CLI\u002F模型（settings.yaml → \u002Fexit → 重新启动） | 根据需要 |\n\n### `install.bat` 自动执行的内容：\n- ✅ 检查是否已安装 WSL2（如果没有则引导你）\n- ✅ 检查是否已安装 Ubuntu（如果没有则引导你）\n- ✅ 显示后续步骤（如何运行 `first_setup.sh`）\n\n### `shutsujin_departure.sh` 的作用：\n- ✅ 创建 tmux 会话（shogun + multiagent）\n- ✅ 在所有代理上启动 Claude Code\n- ✅ 自动加载每个代理的指令文件\n- ✅ 重置队列文件以恢复初始状态\n- ✅ 启动 ntfy 监听器以接收手机通知（如果已配置）\n\n**运行后，所有代理都已准备好接收命令！**\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>🔧 \u003Cb>手动要求\u003C\u002Fb>（点击展开）\u003C\u002Fsummary>\n\n如果你更倾向于手动安装依赖项：\n\n| 要求 | 安装 | 备注 |\n|-------------|-------------|-------|\n| WSL2 + Ubuntu | 在 PowerShell 中运行 `wsl --install` | 仅适用于 Windows |\n| 将 Ubuntu 设置为默认 | `wsl --set-default Ubuntu` | 脚本正常运行所必需 |\n| tmux | `sudo apt install tmux` | 终端多路复用器 |\n| Node.js v20+ | `nvm install 20` | MCP 服务器所需 |\n| Claude Code CLI | `curl -fsSL https:\u002F\u002Fclaude.ai\u002Finstall.sh \\| bash` | Anthropic 官方 CLI（推荐原生版本；npm 版本已弃用） |\n\n\u003C\u002Fdetails>\n\n---\n\n### 设置完成后\n\n无论你选择哪种方式，都会自动启动 **10 个 AI 代理**：\n\n| 代理 | 角色 | 数量 |\n|-------|------|-------|\n| 🏯 Shogun | 最高指挥官——接收你的命令 | 1 |\n| 📋 Karo | 管理员——分配任务、质量检查 | 1 |\n| ⚔️ Ashigaru | 工人——并行执行实施任务 | 7 |\n| 🧠 Gunshi | 战略家——负责分析、评估和设计 | 1 |\n\n创建了两个 tmux 会话：\n- `shogun`——在这里连接以发出命令\n- `multiagent`——Karo、Ashigaru 和 Gunshi 在后台运行\n\n---\n\n## 工作原理\n\n### 第一步：连接到 Shogun\n\n运行 `shutsujin_departure.sh` 后，所有代理会自动加载他们的指令并准备就绪。\n\n打开一个新的终端并连接：\n\n```bash\ntmux attach-session -t shogun\n```\n\n### 第二步：下达你的第一个命令\n\nShogun 已经初始化完毕——只需下达一个命令：\n\n```\n研究前 5 名 JavaScript 框架，并创建一个比较表格\n```\n\nShogun 将会：\n1. 将任务写入 YAML 文件\n2. 通知 Karo（管理员）\n3. 立即返回控制权给你——无需等待！\n\n与此同时，Karo 会将任务分配给 Ashigaru 工人并行执行。\n\n### 第三步：查看进度\n\n在编辑器中打开 `dashboard.md`，即可实时查看状态：\n\n```markdown\n## 进行中\n| 工人 | 任务 | 状态 |\n|--------|------|--------|\n| Ashigaru 1 | 研究 React | 运行中 |\n| Ashigaru 2 | 研究 Vue | 运行中 |\n| Ashigaru 3 | 研究 Angular | 完成 |\n```\n\n### 详细流程\n\n```\n你： “研究前 5 名 MCP 服务器，并创建一个比较表格”\n```\n\nShogun 将任务写入 `queue\u002Fshogun_to_karo.yaml` 文件，并唤醒 Karo。控制权立即返回给你。\n\nKaro 将任务分解为子任务：\n\n| 工人 | 分配的任务 |\n|--------|-----------|\n| Ashigaru 1 | 研究 Notion MCP |\n| Ashigaru 2 | 研究 GitHub MCP |\n| Ashigaru 3 | 研究 Playwright MCP |\n| Ashigaru 4 | 研究 Memory MCP |\n| Ashigaru 5 | 研究 Sequential Thinking MCP |\n\n所有 5 名 Ashigaru 同时进行研究。你可以实时观察他们的工作：\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_767cf40f6cbe.png\" alt=\"Ashigaru 代理在 tmux 面板中并行工作\" width=\"900\">\n\u003C\u002Fp>\n\n结果会随着任务的完成而出现在 `dashboard.md` 中。\n\n---\n\n## 主要特点\n\n### ⚡ 1. 并行执行\n\n一条命令最多会启动8个并行任务：\n\n```\n你：“研究5台MCP服务器”\n→ 5名足轻同时开始研究\n→ 结果在几分钟内就能出来，而不是几小时\n```\n\n### 🔄 2. 非阻塞工作流\n\n幕府将军会立即委派任务，并将控制权交还给你：\n\n```\n你：下达命令 → 幕府将军：委派任务 → 你：立刻下达下一个命令\n                                       ↓\n                       工作人员：在后台执行\n                                       ↓\n                       仪表盘：显示结果\n```\n\n无需等待长时间的任务完成。\n\n### 🧠 3. 跨会话记忆（Memory MCP）\n\n你的AI会记住你的偏好设定：\n\n```\n会话1：告诉它“我更喜欢简单的方法”\n            → 保存到Memory MCP\n\n会话2：AI启动时加载记忆\n            → 不再建议复杂的解决方案\n```\n\n### 📡 4. 事件驱动通信（零轮询）\n\n代理之间通过写入YAML文件进行通信——就像传递纸条一样。**没有轮询循环，也没有浪费的API调用。**\n\n```\n家老想要唤醒足轻3号：\n\n步骤1：写消息          步骤2：唤醒代理\n┌──────────────────────┐           ┌──────────────────────────┐\n│ inbox_write.sh       │           │ inbox_watcher.sh         │\n│                      │           │                          │\n│ 将完整消息写入      │  文件     │ 检测文件变化           │\n│ ashigaru3.yaml中    │──改变──▶│ （inotifywait，而非轮询）│\n│ 使用flock避免竞态   │           │                          │\n└──────────────────────┘           │ 通过以下方式唤醒代理： │\n                                   │  1. 自我监听（跳过）    │\n                                   │  2. tmux send-keys       │\n                                   │     （仅发送简短提示）   │\n                                   └──────────────────────────┘\n\n步骤3：代理读取自己的收件箱\n┌──────────────────────────────────┐\n│ 足轻3号读取ashigaru3.yaml        │\n│ → 发现未读消息                   │\n│ → 处理这些消息                   │\n│ → 标记为已读                     │\n└──────────────────────────────────┘\n```\n\n**唤醒机制的工作原理：**\n\n| 优先级 | 方法 | 发生什么 | 何时使用 |\n|----------|--------|-------------|-----------|\n| 第1级 | **自我监听** | 代理监听自己的收件箱文件——自动唤醒，无需提示 | 代理运行着自己的`inotifywait` |\n| 第2级 | **停止钩子** | Claude Code代理通过`.claude\u002Fsettings.json`中的停止钩子在回合结束时检查收件箱 | 仅Claude Code代理适用 |\n| 第3级 | **tmux send-keys** | 通过`tmux send-keys`发送简短提示（文本和回车分别发送，以兼容Codex CLI） | 备用方案——在ASW阶段2及以上被禁用 |\n\n**代理自我监听（ASW）阶段**——控制系统使用`tmux send-keys`提示的激进程度：\n\n| ASW阶段 | 提示行为 | 送达方式 | 何时使用 |\n|-----------|---------------|-----------------|-------------|\n| **阶段1** | 启用正常提示 | 自我监听 + send-keys | 初始设置，混合CLI环境 |\n| **阶段2** | **忙碌→抑制，空闲→提示** | 忙碌时：停止钩子在回合结束时触发；空闲时：提示（不可避免） | 具有停止钩子的Claude Code代理（推荐） |\n| **阶段3** | `FINAL_ESCALATION_ONLY` | send-keys仅作为最后的恢复手段 | 完全稳定的环境 |\n\n阶段2使用空闲标志文件（`\u002Ftmp\u002Fshogun_idle_{agent}`）来区分忙碌与空闲的代理。停止钩子会在回合边界创建或移除该标志。这样可以在代理积极工作时避免提示干扰，同时仍能唤醒空闲的代理。\n\n> **为什么不能完全消除提示？** Claude Code的停止钩子只在回合结束时触发。一个空闲的代理（坐在提示符前）并没有回合结束，因此没有钩子来触发收件箱检查。未来如果有一个支持`idle_prompt`阻塞的`Notification`钩子，或者定期的定时器钩子，就可以解决这个问题。\n\n在`config\u002Fsettings.yaml`中配置：\n```yaml\nasw_phase: 2   # 推荐用于Claude Code设置\n```\n\n或者直接在`scripts\u002Finbox_watcher.sh`中设置默认值（`ASW_PHASE`变量）。更改后需重启inbox_watcher进程。\n\n**3阶段升级（v3.2）**——如果代理没有响应：\n\n| 阶段 | 时间 | 行动 |\n|-------|--------|--------|\n| 阶段1 | 0-2分钟 | 标准提示（“inbox3”文本+回车）——*在ASW阶段2及以上对忙碌代理跳过* |\n| 阶段2 | 2-4分钟 | 连续按两次Escape键并按C-c重置光标，然后提示 |\n| 阶段3 | 4分钟以上 | 发送`\u002Fclear`强制重置会话（每5分钟最多一次） |\n\n**关键设计选择：**\n- **消息内容绝不会通过tmux发送**——只会发送一个简短的“你有邮件”提示。代理自己读取文件。这样可以避免字符乱码和传输卡顿。\n- **空闲时CPU占用为0%**——`inotifywait`会阻塞在内核事件上（而不是轮询循环）。消息之间CPU使用率为0%。\n- **保证送达**——如果文件写入成功，消息就一定在那里。不会有消息丢失，也不需要重试。\n\n### 📊 5. 代理状态检查\n\n只需一条命令，即可立即查看哪些代理正在忙碌或空闲：\n\n```bash\n# 项目模式：包含任务\u002F收件箱信息的完整状态\nbash scripts\u002Fagent_status.sh\n\n# 独立模式：适用于任何tmux会话\nbash scripts\u002Fagent_status.sh --session mysession --lang en\n```\n\n**项目模式输出：**\n```\n代理      CLI     窗格      任务ID                                    状态     收件箱\n---------- ------- --------- ------------------------------------------ ---------- -----\nkaro       claude  待机中    ---                                        ---        0\nashigaru1  codex   运行中    subtask_042a_research                      分配       0\nashigaru2  codex   待机中    subtask_042b_review                        完成       0\ngunshi     claude  运行中    subtask_042c_analysis                      分配       0\n```\n\n**独立模式输出**（无需项目配置）：\n```\n窗格                           状态      代理ID\n------------------------------ ---------- ----------\nmultiagent:agents.0            IDLE       karo\nmultiagent:agents.1            BUSY       ashigaru1\nmultiagent:agents.8            BUSY       gunshi\n```\n\n检测功能同时适用于**Claude Code**和**Codex CLI**，通过检查每个tmux窗格底部5行中的CLI特定提示符\u002F旋转图标模式来实现。检测逻辑位于`lib\u002Fagent_status.sh`中——你可以在自己的脚本中引用它：\n\n```bash\nsource lib\u002Fagent_status.sh\nagent_is_busy_check \"multiagent:agents.3\" && echo \"busy\" || echo \"idle\"\n```\n\n### 📸 6. 截图集成\n\nVSCode的Claude Code扩展允许你粘贴截图来解释问题。这个CLI系统也提供了相同的功能：\n\n```yaml\n# 在config\u002Fsettings.yaml中设置你的截图文件夹\nscreenshot:\n  path: \"\u002Fmnt\u002Fc\u002FUsers\u002FYourName\u002FPictures\u002FScreenshots\"\n```\n\n```\n\n# 只需告诉将军：\n你：“查看最新的截图”\n你：“看看最近的两张截图”\n→ AI会立即读取并分析你的屏幕截图\n```\n\n**Windows 小贴士：** 按下 `Win + Shift + S` 即可截屏。在 `settings.yaml` 中设置保存路径，实现无缝集成。\n\n使用场景：\n- 以可视化方式说明 UI 错误\n- 展示错误信息\n- 对比前后状态\n\n### 📁 7. 上下文管理（4层架构）\n\n通过四层上下文系统实现高效的知识共享：\n\n| 层级 | 位置 | 目的 |\n|------|------|------|\n| 第1层：记忆MCP | `memory\u002Fshogun_memory.jsonl` | 跨项目、跨会话的长期记忆 |\n| 第2层：项目 | `config\u002Fprojects.yaml`、`projects\u002F\u003Cid>.yaml`、`context\u002F{project}.md` | 项目特定的信息和技术知识 |\n| 第3层：YAML队列 | `queue\u002Fshogun_to_karo.yaml`、`queue\u002Ftasks\u002F`、`queue\u002Freports\u002F` | 任务管理——指令和报告的权威来源 |\n| 第4层：会话 | CLAUDE.md、instructions\u002F*.md | 工作上下文（由 `\u002Fclear` 清除） |\n\n#### 持久化代理记忆 (`memory\u002FMEMORY.md`)\n\nShogun 在每次会话开始时都会读取 `memory\u002FMEMORY.md` 文件。其中包含主公的偏好、经验教训以及跨会话的知识——由 Shogun 编写，也由 Shogun 阅读。\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    Git 仓库                          │\n│                                                              │\n│  ┌─────────────────────┐   ┌──────────────────────────┐    │\n│  │  multi-agent-shogun │   │      shogun-private        │    │\n│  │       (公开的 OSS)  │   │   (您的私有仓库)      │    │\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  ─────┼───┼── 同一文件，在此处跟踪  │    │\n│  │     (gitignored)    │   │                            │    │\n│  └─────────────────────┘   └──────────────────────────┘    │\n│         ↑ 任何人都可以 fork        ↑ 您的数据，您的仓库      │\n└─────────────────────────────────────────────────────────────┘\n```\n\n**工作原理：** `memory\u002FMEMORY.md` 文件与 OSS 仓库位于同一工作目录中，但被排除在 OSS 的 `.gitignore` 列表之外（白名单机制）。您可以通过裸仓库技术将其单独存储在私有仓库中：\n\n```bash\n# 一次性设置（已由 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# 日常使用\nprivategit add -f memory\u002FMEMORY.md projects\u002Fmy-client.yaml\nprivategit commit -m \"更新记忆\"\nprivategit push\n```\n\nOSS 的 `.gitignore` 使用 **白名单策略**（默认排除所有内容，然后显式允许 OSS 文件）。因此，像 `memory\u002FMEMORY.md` 这样的私有文件会自动被排除，无需额外的 `.gitignore` 条目——只需不要将它们加入白名单即可。\n\n这种设计实现了：\n- 任何足轻都可以参与任何项目\n- 上下文可在不同代理之间持续传递\n- 清晰的责任划分\n- 知识可在不同会话间保留\n\n#### \u002Fclear 协议（成本优化）\n\n随着代理工作的进行，其会话上下文（第4层）会不断增长，从而增加 API 成本。执行 `\u002Fclear` 命令可以清除会话内存并重置费用。而第1至第3层的内容则以文件形式持久保存，因此不会丢失。\n\n执行 `\u002Fclear` 后的恢复成本：**约6,800个token**（相比v1版本提升了42%——CLAUDE.md的YAML转换以及仅使用英文指令使token成本降低了70%）。\n\n1. CLAUDE.md（自动加载）→识别自身为Shogun系统的一部分\n2. `tmux display-message -t \"$TMUX_PANE\" -p '#{@agent_id}'` → 确定自身的编号\n3. 读取记忆MCP → 恢复主公的偏好（约700个token）\n4. 读取任务YAML → 获取下一个任务（约800个token）\n\n关键在于：设计出**哪些内容不需要加载**，才能真正实现成本节约。\n\n#### 通用上下文模板\n\n所有项目都采用相同的7部分模板：\n\n| 部分 | 目的 |\n|------|------|\n| 是什么 | 项目概述 |\n| 为什么 | 目标和成功标准 |\n| 谁 | 利益相关者和职责 |\n| 约束 | 截止日期、预算、限制条件 |\n| 当前状态 | 进展、下一步行动、阻碍因素 |\n| 决策 | 已做出的决策及其理由 |\n| 备注 | 自由格式的观察和想法 |\n\n这一统一格式能够：\n- 让任何代理快速上手\n- 在所有项目中实现一致的信息管理\n- 方便足轻之间的交接\n\n### 📱 8. 手机通知（ntfy）\n\n手机与Shogun之间的双向通信——无需SSH、无需Tailscale、无需服务器。\n\n| 方向 | 工作原理 |\n|------|----------|\n| **手机 → Shogun** | 通过ntfy应用发送消息 → `ntfy_listener.sh` 通过流式接收 → 自动回复ACK（“📱受信: {您的消息}”）回传到手机 → Shogun自动处理 |\n| **Karo → 手机（直接）** | 当Karo更新`dashboard.md`时，它会直接通过`scripts\u002Fntfy.sh`发送推送通知——**Shogun被跳过**（Shogun用于人机交互，而非进度汇报） |\n\n```\n📱 您（在床上）          🏯 Shogun\n    │                          │\n    │  “研究React 19”     │\n    ├─────────────────────────►│\n    │    （ntfy消息）        │  → 委托给Karo → 足轻开始工作\n    │                          │\n    │  “✅ cmd_042完成”   │\n    │◄─────────────────────────┤\n    │    （推送通知）   │\n```\n\n**设置：**\n1. 在 `config\u002Fsettings.yaml` 中添加 `ntfy_topic: \"shogun-yourname\"`\n2. 在手机上安装 [ntfy app](https:\u002F\u002Fntfy.sh)，并订阅相同的主题\n3. `shutsujin_departure.sh` 会自动启动监听器——无需额外步骤\n\n**通知示例：**\n\n| 事件 | 通知 |\n|-------|-------------|\n| 命令完成 | `✅ cmd_042完成 — 5\u002F5子任务已完成` |\n| 任务失败 | `❌ 子任务042c失败 — API速率限制` |\n| 需要采取行动 | `🚨 需要行动：批准技能候选人` |\n| 连续记录更新 | `🔥 连续3天！今天完成了12\u002F12项任务` |\n\n免费使用，无需注册账户，也不需要维护服务器。使用的是 [ntfy.sh](https:\u002F\u002Fntfy.sh)——一个开源的推送通知服务。\n\n> **⚠️ 安全性：** 您的主题名称就是您的密码。任何知道该名称的人都可以阅读您的通知并向您的Shogun发送消息。请务必选择一个难以猜测的名称，并且**切勿公开分享**（例如在截图、博客文章或GitHub提交中）。\n\n**验证是否正常工作：**\n\n```bash\nprivategit status\n```\n\n# 向您的手机发送一条测试通知\nbash scripts\u002Fntfy.sh \"来自Shogun的测试通知 🏯\"\n```\n\n如果您的手机收到了通知，那么一切就绪。如果没有收到，请检查：\n- `config\u002Fsettings.yaml` 中已设置 `ntfy_topic`（非空且无额外引号）\n- 手机上的 ntfy 应用已订阅 **完全相同的主题名称**\n- 您的手机已连接互联网，并且 ntfy 通知功能已开启\n\n**通过手机发送命令：**\n\n1. 打开手机上的 ntfy 应用\n2. 点击您已订阅的主题\n3. 输入一条消息（例如：`Research React 19 best practices`），然后发送\n4. `ntfy_listener.sh` 接收到该消息后，会将其写入 `queue\u002Fntfy_inbox.yaml`，并唤醒 Shogun\n5. Shogun 读取该消息，并按照正常的 Karo → Ashigaru 流程进行处理\n\n您发送的任何文本都会变成一条命令。您可以像与 Shogun 对话一样直接书写，无需使用特殊语法。\n\n**手动启动监听器**（如果您没有使用 `shutsujin_departure.sh`）：\n\n```bash\n# 在后台启动监听器\nnohup bash scripts\u002Fntfy_listener.sh &>\u002Fdev\u002Fnull &\n\n# 检查是否正在运行\npgrep -f ntfy_listener.sh\n\n# 查看监听器日志（stderr 输出）\nbash scripts\u002Fntfy_listener.sh  # 前台运行以查看日志\n```\n\n如果连接断开，监听器会自动重新连接。`shutsujin_departure.sh` 会在部署时自动启动它——只有在您跳过了部署脚本的情况下才需要手动启动。\n\n**故障排除：**\n\n| 问题 | 解决方法 |\n|------|----------|\n| 手机未收到通知 | 检查 `settings.yaml` 和 ntfy 应用中的主题名称是否完全一致 |\n| 监听器无法启动 | 前台运行 `bash scripts\u002Fntfy_listener.sh` 查看错误信息 |\n| 手机到 Shogun 的通信不通 | 验证监听器是否正在运行：`pgrep -f ntfy_listener.sh` |\n| 消息未到达 Shogun | 检查 `queue\u002Fntfy_inbox.yaml` — 如果消息在那里，可能是 Shogun 正在忙 |\n| “ntfy_topic 未配置”错误 | 在 `config\u002Fsettings.yaml` 中添加 `ntfy_topic: \"your-topic\"` |\n| 重复通知 | 重新连接时正常现象——Shogun 会根据消息 ID 去重 |\n| 更改了主题名称但仍未收到通知 | 必须重启监听器：`pkill -f ntfy_listener.sh && nohup bash scripts\u002Fntfy_listener.sh &>\u002Fdev\u002Fnull &` |\n\n**实际通知截图：**\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_e604d0f6f395.jpg\" alt=\"双向手机通信\" width=\"300\">\n    \n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_ffc3560a7198.jpg\" alt=\"进度通知\" width=\"300\">\n\u003C\u002Fp>\n\u003Cp align=\"center\">\u003Ci>左图：双向手机 ↔ Shogun 通信 · 右图：来自 Ashigaru 的实时进度报告\u003C\u002Fi>\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_81c4dba5b254.jpg\" alt=\"命令完成通知\" width=\"300\">\n    \n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_c41adc414ef0.jpg\" alt=\"8个代理并行完成\" width=\"300\">\n\u003C\u002Fp>\n\u003Cp align=\"center\">\u003Ci>左图：命令完成通知 · 右图：8个 Ashigaru 并行完成\u003C\u002Fi>\u003C\u002Fp>\n\n> *注：截图中显示的主题名称仅为示例。请使用您自己唯一的主题名称。*\n\n#### SayTask 通知\n\n基于行为心理学的动力机制，通过您的通知流来激励您：\n\n- **连续打卡追踪**：连续完成天数会记录在 `saytask\u002Fstreaks.yaml` 中——保持连续性可以利用损失规避心理来维持动力\n- **吃掉那只青蛙** 🐸：当天最困难的任务会被标记为“青蛙”。完成它会触发特别的庆祝通知\n- **每日进度**：`今天已完成 12\u002F12 项任务`——可视化完成反馈强化了 Arbeitslust 效果（对正在进行的工作的喜悦）\n\n### 🖼️ 9. 窗格边框任务显示\n\n每个 tmux 窗格的边框上都会直接显示当前代理的任务：\n\n```\n┌ ashigaru1 Sonnet+T VF 要求 ──┬ ashigaru3 Opus+T API 研究 ──────┐\n│                                      │                                     │\n│  正在处理 SayTask 要求     │  正在研究 REST API 模式      │\n│                                      │                                     │\n├ ashigaru2 Sonnet ───────────────────┼ ashigaru4 Spark DB 模式设计 ───┤\n│                                      │                                     │\n│  (空闲 — 等待分配)     │  正在设计数据库模式          │\n│                                      │                                     │\n└──────────────────────────────────────┴─────────────────────────────────────┘\n```\n\n- **工作中**：`ashigaru1 Sonnet+T VF 要求`——显示代理名称、模型（带有思考指示器）以及任务摘要\n- **空闲中**：`ashigaru2 Sonnet`——仅显示模型名称，无任务\n- **显示名称**：Sonnet、Opus、Haiku、Codex、Spark——`+T` 后缀表示启用了扩展思考功能\n- 由 Karo 在分配或完成任务时自动更新\n- 眺望所有 9 个窗格，即可立即了解谁在做什么\n\n### 🔊 10. 呐喊模式（战斗口号）\n\n当一个 Ashigaru 完成任务时，它会在 tmux 窗格中喊出一句个性化的战斗口号——这是提醒您军队正在努力工作的视觉信号。\n\n```\n┌ ashigaru1 (Sonnet) ──────────┬ ashigaru2 (Sonnet) ──────────┐\n│                               │                               │\n│  ⚔️ 足軽1号、先陣切った！     │  🔥 足軽2号、二番槍の意地！   │\n│  八刃一志！                   │  八刃一志！                   │\n│  ❯                            │  ❯                            │\n└───────────────────────────────┴───────────────────────────────┘\n```\n\n**工作原理：**\n\nKaro 会在每个任务 YAML 文件中写入一个 `echo_message` 字段。当所有工作完成后（包括报告和收件箱通知），Ashigaru 会将 `echo` 作为其 **最后一步操作** 来执行。这条消息会一直显示在 `❯` 提示符上方。\n\n```yaml\n# 在任务 YAML 中（由 Karo 编写）\ntask:\n  task_id: subtask_001\n  description: \"创建对比表格\"\n  echo_message: \"🔥 足軽1号、先陣を切って参る！八刃一志！\"\n```\n\n**呐喊模式是默认设置。** 若要关闭（以节省 echo 调用的 API 令牌）：\n\n```bash\n.\u002Fshutsujin_departure.sh --silent    # 不喊口号\n.\u002Fshutsujin_departure.sh             # 默认：启用呐喊模式（喊口号）\n```\n\n静音模式会将 `DISPLAY_MODE=silent` 设置为 tmux 环境变量。Karo 在编写任务 YAML 时会检查此变量，并省略 `echo_message` 字段。\n\n---\n\n## 🗣️ SayTask — 专为讨厌任务管理的人打造的任务管理工具\n\n### 什么是 SayTask？\n\n**专为讨厌任务管理的人设计的任务管理工具。只需对着手机说话即可。**\n\n**用语言编码，而非氛围编码。** 把您的任务说出来，AI 就会帮您整理好。无需打字，无需打开应用，没有任何摩擦。\n\n- **目标用户**：那些曾经安装过 Todoist，但三天后就再也没打开过的人\n- 您的敌人不是其他应用——而是什么都不做。真正的竞争对象是无所作为，而不是另一个生产力工具\n- 零界面。零打字。零打开应用。只需开口说话\n\n> *\"您的敌人不是其他应用——而是什么都不做。\"*\n\n### 工作原理\n\n1. 安装 [ntfy 应用](https:\u002F\u002Fntfy.sh)（免费，无需账号）\n2. 对手机说：“明天看牙医”，“发票周五到期”\n3. AI 自动整理 → 早晨通知：“这是你今天的一天安排”\n\n```\n 🗣️ “买牛奶，明天看牙医，发票周五到期”\n       │\n       ▼\n ┌──────────────────┐\n │  ntfy → Shogun   │  AI 自动分类、解析日期、设定优先级\n └────────┬─────────┘\n          │\n          ▼\n ┌──────────────────┐\n │   tasks.yaml     │  结构化存储（本地，数据永不离开你的设备）\n └────────┬─────────┘\n          │\n          ▼\n 📱 早晨通知：\n    “今日：🐸 发票到期 · 🦷 下午3点看牙医 · 🛒 购买牛奶”\n```\n\n### 使用前\u002F后对比\n\n| 使用前 (v1) | 使用后 (v2) |\n|:-----------:|:----------:|\n| ![任务列表 v1](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_98f5f2d56754.jpg) | ![任务列表 v2](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_readme_240eefe775a7.jpg) |\n| 原始任务清单 | 干净、有序的每日总结 |\n\n> *注：截图中显示的主题名称仅为示例。请使用您自己唯一的主题名称。*\n\n### 使用场景\n\n- 🛏️ **在床上**：“明天得提交报告”——在忘记之前就记录下来，无需翻找笔记本\n- 🚗 **开车时**：“别忘了给客户A的报价单”——免提操作，眼睛始终盯着路面\n- 💻 **工作间隙**：“哦，得去买牛奶”——立即记录，保持工作流畅\n- 🌅 **醒来时**：今天的任务已出现在通知中——无需打开应用，无需查看收件箱\n- 🐸 **吃掉那只青蛙**：AI 每天早上会为你挑选最难的任务——你可以选择忽略它，也可以先完成它\n\n### 常见问题解答\n\n**问：这和其它任务管理应用有什么不同？**\n答：你完全不需要打开任何应用。只需说话即可。零摩擦。大多数任务管理应用之所以失败，是因为人们不再去打开它们。SayTask 则彻底省去了这一步。\n\n**问：我可以在没有完整 Shogun 系统的情况下使用 SayTask 吗？**\n答：SayTask 是 Shogun 的一个功能。Shogun 本身也是一个独立的多智能体开发平台——你可以在同一个系统中同时获得这两种能力。\n\n**问：那只青蛙 🐸 是什么？**\n答：每天早上，AI 会为你挑选最困难的任务——也就是你最想回避的任务。你可以选择先完成它（即“吃掉那只青蛙”的方法），也可以选择忽略。由你决定。\n\n**问：它是免费的吗？**\n答：一切都是免费且开源的。ntfy 也是免费的。无需账号、无需服务器、无需订阅。\n\n**问：我的数据存储在哪里？**\n答：数据存储在你本地的 YAML 文件中。没有任何数据会被发送到云端。你的任务永远不会离开你的设备。\n\n**问：如果我说一些模糊的话，比如“那个工作上的事”怎么办？**\n答：AI 会尽力对其进行分类和安排。你随时可以稍后再进行调整——但关键在于，在想法消失之前将其捕捉下来。\n\n### SayTask 与 cmd 流水线对比\n\nShogun 拥有两个互补的任务系统：\n\n| 功能 | SayTask（语音层） | cmd 流水线（AI 执行） |\n|---|:-:|:-:|\n| 语音输入 → 创建任务 | ✅ | — |\n| 早晨通知摘要 | ✅ | — |\n| 青蛙 🐸 选择 | ✅ | — |\n| 连续打卡追踪 | ✅ | ✅ |\n| AI 执行的任务（多步骤） | — | ✅ |\n| 8 个智能体并行执行 | — | ✅ |\n\nSayTask 负责个人生产力（捕捉 → 安排 → 提醒）。cmd 流水线则负责复杂的工作（研究、代码、多步骤任务）。两者共享连续打卡功能——完成任一类任务都会计入你的每日打卡数。\n\n---\n\n## 模型设置\n\n| 智能体 | 默认模型 | 思考模式 | 角色 |\n|-------|--------------|----------|------|\n| Shogun | Opus | **启用（高）** | 主君的战略顾问。使用 `--shogun-no-thinking` 可切换为仅中继模式 |\n| Karo | Sonnet | 启用 | 任务分配、简单质检、仪表盘管理 |\n| Gunshi | Opus | 启用 | 深度分析、设计评审、架构评估 |\n| Ashigaru 1–7 | Sonnet 4.6 | 启用 | 实施：代码、研究、文件操作 |\n\n**思考控制**：在 `config\u002Fsettings.yaml` 中为每个智能体设置 `thinking: true\u002Ffalse`。当 `thinking: false` 时，该智能体会以 `MAX_THINKING_TOKENS=0` 开始，从而禁用扩展思考功能。当启用思考功能时，面板边框会显示 `+T` 后缀（例如 `Sonnet+T`、`Opus+T`）。\n\n**实时模型切换**：使用 `\u002Fshogun-model-switch` 可以更改任意智能体的 CLI 类型、模型或思考设置，而无需重启整个系统。详情请参阅技能部分。\n\n系统根据**认知复杂度**在两个层面进行任务路由：**智能体路由**（L1–L3 由 Ashigaru 处理，L4–L6 由 Gunshi 处理）以及 **Ashigaru 内部的模型路由**，通过 `capability_tiers` 实现（详见动态模型路由部分）。\n\n### 布鲁姆认知分类法 → 智能体路由\n\n任务依据布鲁姆认知分类法进行划分，并被路由到相应的**智能体**，而非模型：\n\n| 层次 | 类别 | 描述 | 路由至 |\n|-------|----------|-------------|-----------|\n| L1 | 记忆 | 回忆事实、复制、列举 | **Ashigaru** |\n| L2 | 理解 | 解释、总结、改述 | **Ashigaru** |\n| L3 | 应用 | 执行程序、实施已知模式 | **Ashigaru** |\n| L4 | 分析 | 比较、调查、拆解 | **Gunshi** |\n| L5 | 评价 | 判断、批评、推荐 | **Gunshi** |\n| L6 | 创造 | 设计、构建、合成新方案 | **Gunshi** |\n\nKaro 会为每个子任务分配一个布鲁姆层次，并将其路由到合适的智能体。L1–L3 的任务会交给 Ashigaru 并行执行；L4–L6 的任务则会交由 Gunshi 进行更深入的分析。对于简单的 L4 任务（如小型代码审查），如果 Karo 认为合适，仍可交由 Ashigaru 处理。\n\n### 任务依赖关系（blockedBy）\n\n任务可以通过 `blockedBy` 声明对其他任务的依赖关系：\n\n```yaml\n# queue\u002Ftasks\u002Fashigaru2.yaml\ntask:\n  task_id: subtask_010b\n  blockedBy: [\"subtask_010a\"]  # 等待 ashigaru1 的任务完成\n  description: \"集成由 subtask_010a 构建的 API 客户端\"\n```\n\n当阻塞任务完成后，Karo 会自动解除依赖任务的阻塞状态，并将其分配给可用的 Ashigaru。这样可以避免空等，实现依赖工作的高效流水线处理。\n\n### 动态模型路由（capability_tiers）\n\n除了代理级别的路由之外，您还可以在 **Ashigaru 层级内配置模型级别的路由**。在 `config\u002Fsettings.yaml` 中定义一个 `capability_tiers` 表，将每个模型映射到其最大 Bloom 级别：\n\n```yaml\ncapability_tiers:\n  gpt-5.3-codex-spark:\n    max_bloom: 3       # 仅限 L1–L3：快速、高容量任务\n    cost_group: chatgpt_pro\n  gpt-5.3-codex:\n    max_bloom: 4       # L1–L4：增加分析和调试功能\n    cost_group: chatgpt_pro\n  claude-sonnet-4-6:\n    max_bloom: 5       # L1–L5：增加设计评估功能\n    cost_group: claude_max\n  claude-opus-4-6:\n    max_bloom: 6       # L1–L6：支持新型架构与战略规划\n    cost_group: claude_max\n```\n\n`cost_group` 字段将每个模型与您的订阅计划关联起来，从而避免系统将任务路由到您订阅计划未涵盖的模型。\n\n有两个内置技能可以帮助您进行配置：\n\n| 技能 | 用途 |\n|-------|---------|\n| `\u002Fshogun-model-list` | 参考表：所有模型 × 订阅计划 × Bloom 最大值 |\n| `\u002Fshogun-bloom-config` | 交互式：回答两个问题 → 获得可直接粘贴的 YAML |\n\n设置完成后，请运行 `\u002Fshogun-bloom-config` 来生成最适合您的 `capability_tiers` 配置。\n\n---\n\n## 哲学\n\n> “不要盲目执行任务。始终牢记‘最快×最佳输出’。”\n\nShogun 系统建立在五个核心原则之上：\n\n| 原则 | 描述 |\n|-----------|-------------|\n| **自主编队** | 根据任务复杂度而非模板来设计任务编队 |\n| **并行化** | 使用子代理以防止单点瓶颈 |\n| **先调研后决策** | 在做出决定之前先寻找证据 |\n| **持续学习** | 不要仅仅依赖模型的知识截止日期 |\n| **三角验证** | 多视角研究结合集成授权 |\n\n这些原则已在文档中详细说明：**[docs\u002Fphilosophy.md](docs\u002Fphilosophy.md)**\n\n---\n\n## 设计哲学\n\n### 为什么采用层级结构（Shogun → Karo → Ashigaru）？\n\n1. **即时响应**：Shogun 会立即委派任务，并将控制权交还给您。\n2. **并行执行**：Karo 会同时将任务分发给多个 Ashigaru。\n3. **单一职责**：每个角色分工明确，不会产生混淆。\n4. **可扩展性**：增加更多 Ashigaru 不会影响整体结构。\n5. **故障隔离**：一个 Ashigaru 出现故障不会影响其他 Ashigaru。\n6. **统一报告**：只有 Shogun 会与您沟通，确保信息井然有序。\n\n### 为什么使用信箱系统？\n\n为什么不直接使用代理之间的消息传递，而是采用文件方式呢？\n\n| 直接消息传递的问题 | 信箱系统如何解决 |\n|-------------------------------|----------------------|\n| 代理崩溃 → 消息丢失 | YAML 文件可在重启后恢复 |\n| 轮询浪费 API 调用 | `inotifywait` 是事件驱动的（空闲时 CPU 占用为零） |\n| 代理之间互相干扰 | 每个代理都有自己的收件箱文件 — 无交叉通信 |\n| 难以调试 | 打开任意 `.yaml` 文件即可查看完整的消息历史 |\n| 并发写入导致数据损坏 | `flock`（独占锁）会自动序列化写入操作 |\n| 交付失败（字符损坏、卡顿） | 消息内容保存在文件中 — tmux 只发送一条“有邮件”的提示 |\n\n### 代理标识 (@agent_id)\n\n每个窗格都设有 `@agent_id` tmux 用户选项（例如 `karo`、`ashigaru1`）。虽然 `pane_index` 会在窗格重新排列时发生变化，但 `@agent_id` 是在启动时由 `shutsujin_departure.sh` 设置的，且永远不会改变。\n\n代理自我识别：\n```bash\ntmux display-message -t \"$TMUX_PANE\" -p '#{@agent_id}'\n```\n其中 `-t \"$TMUX_PANE\"` 是必需的。如果省略，则会返回当前焦点窗格的值，从而导致错误识别。\n\n模型名称存储为 `@model_name`，当前任务摘要存储为 `@current_task`——两者都会显示在 `pane-border-format` 中。即使 Claude Code 覆盖了窗格标题，这些用户选项仍会保留。\n\n### 为什么只有 Karo 更新 dashboard.md？\n\n1. **单一写入者**：通过限制更新权限至一个代理，避免冲突。\n2. **信息汇总**：Karo 会接收所有 Ashigaru 的报告，因此掌握全局情况。\n3. **一致性**：所有更新都经过统一的质量审核。\n4. **不打断工作**：如果由 Shogun 更新，可能会打断主人的操作。\n\n---\n\n## 技能\n\n系统默认不包含任何技能。技能是在实际操作过程中自然产生的——您只需从 `dashboard.md` 中发现并批准合适的候选技能即可。\n\n调用技能的方式是输入 `\u002F技能名`。只需告诉 Shogun：“运行 \u002F技能名”。\n\n### 内置技能（已提交至仓库）\n\n技能随仓库一起提供，位于 `skills\u002F` 目录下。它们是领域无关的实用工具，对任何用户都很有用：\n\n| 技能 | 描述 |\n|-------|-------------|\n| `\u002Fskill-creator` | 创建新技能的模板和指南 |\n| `\u002Fshogun-agent-status` | 显示所有代理的繁忙\u002F空闲状态，以及任务和收件箱信息 |\n| `\u002Fshogun-model-list` | 参考表：所有 CLI 工具 × 模型 × 订阅计划 × Bloom 最大级别 |\n| `\u002Fshogun-bloom-config` | 交互式配置工具：回答关于您订阅计划的两个问题 → 获得可直接粘贴的 `capability_tiers` YAML |\n| `\u002Fshogun-model-switch` | 实时 CLI\u002F模型切换：更新 settings.yaml → `\u002Fexit` → 使用正确参数重新启动。支持思维开启\u002F关闭控制 |\n| `\u002Fshogun-readme-sync` | 保持 README.md 和 README_ja.md 同步 |\n\n这些工具可以帮助您配置和操作系统。而针对个人工作流程的技能，则会通过自下而上的发现过程自然成长。\n\n### 技能哲学\n\n**1. 个人技能不会提交到仓库**\n\n`.claude\u002Fcommands\u002F` 中的技能出于设计目的被排除在版本控制之外：\n- 每位用户的 workflow 都不同。\n- 不应强加通用技能，而应让每位用户根据自身需求逐步构建自己的技能体系。\n\n**2. 技能的发现过程**\n\n```\nAshigaru 在工作中注意到某种模式\n    ↓\n出现在 dashboard.md 的“技能候选”部分\n    ↓\n您（主人）审查该提案\n    ↓\n若批准，则指示 Karo 创建该技能\n```\n\n技能完全由用户驱动。如果由系统自动创建，将会导致技能膨胀，难以管理——只保留真正有用的技能即可。\n\n---\n\n## MCP 设置指南\n\nMCP（Model Context Protocol）服务器可以扩展 Claude 的功能。以下是设置步骤：\n\n### 什么是 MCP？\n\nMCP 服务器可以让 Claude 访问外部工具：\n- **Notion MCP** → 读取和写入 Notion 页面\n- **GitHub MCP** → 创建 PR、管理问题\n- **Memory MCP** → 在会话之间持久化记忆\n\n### 安装 MCP 服务器\n\n使用以下命令添加 MCP 服务器：\n\n```bash\n# 1. Notion - 连接到您的 Notion 工作区\nclaude mcp add notion -e NOTION_TOKEN=your_token_here -- npx -y @notionhq\u002Fnotion-mcp-server\n\n# 2. Playwright - 浏览器自动化\nclaude mcp add playwright -- npx @playwright\u002Fmcp@latest\n# 注意：请先运行 `npx playwright install chromium`\n\n# 3. GitHub - 仓库操作\nclaude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=your_pat_here -- npx -y @modelcontextprotocol\u002Fserver-github\n\n# 4. 顺序思维 - 针对复杂问题的逐步推理\nclaude mcp add sequential-thinking -- npx -y @modelcontextprotocol\u002Fserver-sequential-thinking\n\n# 5. 内存 - 跨会话长期记忆（推荐！）\n# ✅ 由 first_setup.sh 自动配置\n# 如需手动重新配置：\nclaude mcp add memory -e MEMORY_FILE_PATH=\"$PWD\u002Fmemory\u002Fshogun_memory.jsonl\" -- npx -y @modelcontextprotocol\u002Fserver-memory\n```\n\n### 验证安装\n\n```bash\nclaude mcp list\n```\n\n所有服务器都应显示“已连接”状态。\n\n---\n\n## 现实世界用例\n\n该系统可以管理**所有白领工作**，而不仅仅是代码相关任务。项目可以存储在你文件系统的任何位置。\n\n### 示例 1：研究冲刺\n\n```\n你：“调研前五名 AI 编程助手，并进行比较”\n\n发生过程：\n1. 将军委派给卡罗\n2. 卡罗分配：\n   - 步兵 1：调研 GitHub Copilot\n   - 步兵 2：调研 Cursor\n   - 步兵 3：调研 Claude Code\n   - 步兵 4：调研 Codeium\n   - 步兵 5：调研 Amazon CodeWhisperer\n3. 所有 5 名步兵同时开展调研\n4. 结果汇总到 dashboard.md 文件中\n```\n\n### 示例 2：PoC 准备\n\n```\n你：“为这个 Notion 页面上的项目准备一个 PoC：[URL]”\n\n发生过程：\n1. 卡罗通过 MCP 获取 Notion 内容\n2. 步兵 2 列出需要验证的事项\n3. 步兵 3 探究技术可行性\n4. 步兵 4 拟定 PoC 计划\n5. 所有结果汇总到 dashboard.md 文件中——会议准备工作完成\n```\n\n---\n\n## 配置\n\n### 语言\n\n```yaml\n# config\u002Fsettings.yaml\nlanguage: ja   # 仅使用武士日语\nlanguage: en   # 使用武士日语 + 英文翻译\n```\n\n### 截图集成\n\n```yaml\n# config\u002Fsettings.yaml\nscreenshot:\n  path: \"\u002Fmnt\u002Fc\u002FUsers\u002FYourName\u002FPictures\u002FScreenshots\"\n```\n\n只需告诉将军“查看最新的截图”，它就会读取你的屏幕截图以获取视觉上下文。（在 Windows 上使用 `Win+Shift+S` 快捷键。）\n\n### ntfy（手机通知）\n\n```yaml\n# config\u002Fsettings.yaml\nntfy_topic: \"shogun-yourname\"\n```\n\n在手机上的 [ntfy 应用](https:\u002F\u002Fntfy.sh)中订阅相同的主题。监听器会随 `shutsujin_departure.sh` 自动启动。\n\n#### ntfy 认证（自托管服务器）\n\n公共的 ntfy.sh 实例**无需认证**——上述设置即为全部所需。\n\n如果你运行的是启用了访问控制的自托管 ntfy 服务器，则需要配置认证：\n\n```bash\n# 1. 复制示例配置文件\ncp config\u002Fntfy_auth.env.sample config\u002Fntfy_auth.env\n\n# 2. 使用你的凭据编辑（选择一种方式）\n```\n\n| 方法 | 配置 | 使用场景 |\n|--------|--------|-------------|\n| **Bearer Token**（推荐） | `NTFY_TOKEN=tk_your_token_here` | 自托管 ntfy 使用令牌认证（`ntfy token add \u003Cuser>`） |\n| **Basic Auth** | `NTFY_USER=username` + `NTFY_PASS=password` | 自托管 ntfy 使用用户名\u002F密码认证 |\n| **无**（默认） | 文件留空或不创建 | 公共 ntfy.sh——无需认证 |\n\n优先级：令牌 > 基本 > 无。若两者均未设置，则不会发送认证头信息（向后兼容）。\n\n`config\u002Fntfy_auth.env` 文件不会被提交到 Git 中。详细信息请参阅 `config\u002Fntfy_auth.env.sample`。\n\n---\n\n## 进阶\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>脚本架构\u003C\u002Fb>（点击展开）\u003C\u002Fsummary>\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                    首次设置（仅需运行一次）                       │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  install.bat (Windows)                                              │\n│      │                                                              │\n│      ├── 检查并指导 WSL2 的安装                              │\n│      └── 检查并指导 Ubuntu 的安装                            │\n│                                                                     │\n│  first_setup.sh (在 Ubuntu\u002FWSL 中手动运行)                        │\n│      │                                                              │\n│      ├── 检查并安装 tmux                                         │\n│      ├── 检查并安装 Node.js v20+（通过 nvm）                      │\n│      ├── 检查并安装 Claude Code CLI（原生版本）                   │\n│      │       ※ 如果检测到 npm 版本，则建议迁移                   │\n│      └── 配置 Memory MCP 服务器                                │\n│                                                                     │\n├─────────────────────────────────────────────────────────────────────┤\n│                    每日启动（每天运行）                     │\n├─────────────────────────────────────────────────────────────────────┤\n│                                                                     │\n│  shutsujin_departure.sh                                             │\n│      │                                                              │\n│      ├──▶ 创建 tmux 会话                                          │\n│      │         • “shogun” 会话（1 个窗格）                          │\n│      │         • “multiagent” 会话（9 个窗格，3x3 格式）          │\n│      │                                                              │\n│      ├──▶ 重置队列文件和仪表板                                   │\n│      │                                                              │\n│      └──▶ 在所有代理上启动 Claude Code                          │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>shutsujin_departure.sh 的选项\u003C\u002Fb>（点击展开）\u003C\u002Fsummary>\n\n```bash\n# 默认：完整启动（tmux 会话 + 启动 Claude Code）\n.\u002Fshutsujin_departure.sh\n\n# 仅设置会话（不启动 Claude Code）\n.\u002Fshutsujin_departure.sh -s\n.\u002Fshutsujin_departure.sh --setup-only\n\n# 清理任务队列（保留命令历史）\n.\u002Fshutsujin_departure.sh -c\n.\u002Fshutsujin_departure.sh --clean\n\n# 战斗阵型：所有步兵启用 Opus（最大能力，成本较高）\n.\u002Fshutsujin_departure.sh -k\n.\u002Fshutsujin_departure.sh --kessen\n\n# 默音模式：关闭战斗口号（节省 echo 调用的 API 令牌）\n.\u002Fshutsujin_departure.sh -S\n.\u002Fshutsujin_departure.sh --silent\n\n# 完整启动 + 打开 Windows Terminal 标签页\n.\u002Fshutsujin_departure.sh -t\n.\u002Fshutsujin_departure.sh --terminal\n\n# 将军仅中继模式：禁用将军的思考（节省成本）\n.\u002Fshutsujin_departure.sh --shogun-no-thinking\n\n# 显示帮助\n.\u002Fshutsujin_departure.sh -h\n.\u002Fshutsujin_departure.sh --help\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>常见工作流程\u003C\u002Fb>（点击展开）\u003C\u002Fsummary>\n\n**日常正常使用：**\n```bash\n.\u002Fshutsujin_departure.sh          # 启动所有组件\ntmux attach-session -t shogun     # 连接并下达指令\n```\n\n**调试模式（手动控制）：**\n```bash\n.\u002Fshutsujin_departure.sh -s       # 仅创建会话\n\n# 手动在特定代理上启动 Claude Code\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**崩溃后重启：**\n```bash\n# 杀死现有会话\ntmux kill-session -t shogun\ntmux kill-session -t multiagent\n\n# 重新启动\n.\u002Fshutsujin_departure.sh\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>便捷别名\u003C\u002Fb>（点击展开）\u003C\u002Fsummary>\n\n运行 `first_setup.sh` 会自动将这些别名添加到 `~\u002F.bashrc` 文件中：\n\n```bash\nalias csst='cd \u002Fmnt\u002Fc\u002Ftools\u002Fmulti-agent-shogun && .\u002Fshutsujin_departure.sh'\nalias css='tmux attach-session -t shogun'      # 连接到 Shogun\nalias csm='tmux attach-session -t multiagent'  # 连接到 Karo + Ashigaru\n```\n\n要使别名生效，请运行 `source ~\u002F.bashrc` 或重新启动终端（PowerShell：`wsl --shutdown` 后再打开）。\n\n\u003C\u002Fdetails>\n\n---\n\n## 文件结构\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>点击展开文件结构\u003C\u002Fb>\u003C\u002Fsummary>\n\n```\nmulti-agent-shogun\u002F\n│\n│  ┌──────────────── 设置脚本 ────────────────────┐\n├── install.bat               # Windows: 首次设置\n├── first_setup.sh            # Ubuntu\u002FMac: 首次设置\n├── shutsujin_departure.sh    # 每日部署（自动加载指令）\n│  └──────────────────────────────────────────────────┘\n│\n├── instructions\u002F             # 代理行为定义\n│   ├── shogun.md             # Shogun 指令\n│   ├── karo.md               # Karo 指令\n│   ├── ashigaru.md           # Ashigaru 指令\n│   ├── gunshi.md             # Gunshi（战略家）指令\n│   └── cli_specific\u002F         # CLI 特定工具描述\n│       ├── claude_tools.md   # Claude Code 工具与功能\n│       └── copilot_tools.md  # GitHub Copilot CLI 工具与功能\n│\n├── lib\u002F\n│   ├── agent_status.sh       # 共享的繁忙\u002F空闲检测（Claude Code + Codex）\n│   ├── cli_adapter.sh        # 多 CLI 适配器（Claude\u002FCodex\u002FCopilot\u002FKimi）\n│   └── ntfy_auth.sh          # ntfy 认证辅助工具\n│\n├── scripts\u002F                  # 实用脚本\n│   ├── agent_status.sh       # 显示所有代理的繁忙\u002F空闲状态\n│   ├── inbox_write.sh        # 将消息写入代理收件箱\n│   ├── inbox_watcher.sh      # 使用 inotifywait 监控收件箱变化\n│   ├── switch_cli.sh         # 实时切换 CLI\u002F模型（\u002Fexit → 重新启动）\n│   ├── ntfy.sh               # 向手机发送推送通知\n│   └── ntfy_listener.sh      # 流式接收来自手机的消息\n│\n├── config\u002F\n│   ├── settings.yaml         # 语言、ntfy 等设置\n│   ├── ntfy_auth.env.sample  # 自托管 ntfy 认证模板\n│   └── projects.yaml         # 项目注册表\n│\n├── projects\u002F                 # 项目详细信息（不包含在 git 中，包含机密信息）\n│   └── \u003Cproject_id>.yaml    # 每个项目的完整信息（客户、任务、Notion 链接等）\n│\n├── queue\u002F                    # 通信文件\n│   ├── shogun_to_karo.yaml   # Shogun → Karo 命令\n│   ├── ntfy_inbox.yaml       # 来自手机的传入消息（ntfy）\n│   ├── inbox\u002F                # 每个代理的收件箱文件\n│   │   ├── shogun.yaml       # 发送给 Shogun 的消息\n│   │   ├── karo.yaml         # 发送给 Karo 的消息\n│   │   └── ashigaru{1-8}.yaml # 发送给每个 Ashigaru 的消息\n│   ├── tasks\u002F                # 每个工人的任务文件\n│   └── reports\u002F              # 工人报告\n│\n├── saytask\u002F                  # 基于行为心理学的激励机制\n│   └── streaks.yaml          # 连续记录和每日进度\n│\n├── templates\u002F                # 报告和上下文模板\n│   ├── integ_base.md         # 整合：基础模板\n│   ├── integ_fact.md         # 整合：事实调查\n│   ├── integ_proposal.md     # 整合：提案\n│   ├── integ_code.md         # 整合：代码审查\n│   ├── integ_analysis.md     # 整合：分析\n│   └── context_template.md   # 通用的七部分项目背景\n│\n├── skills\u002F                   # 可重用技能（已提交到仓库）\n│   ├── skill-creator\u002F        # 技能创建模板\n│   ├── shogun-agent-status\u002F  # 代理状态显示\n│   ├── shogun-model-list\u002F    # 模型能力参考\n│   ├── shogun-bloom-config\u002F  # Bloom 层级配置\n│   ├── shogun-model-switch\u002F  # 实时 CLI\u002F模型切换\n│   └── shogun-readme-sync\u002F   # README 同步\n│\n├── memory\u002F                   # 内存 MCP 持久化存储\n├── dashboard.md              # 实时状态板\n└── CLAUDE.md                 # 系统指令（自动加载）\n```\n\n\u003C\u002Fdetails>\n\n---\n\n## 项目管理\n\n该系统不仅管理自身的开发，还管理 **所有白领任务**。项目文件夹可以位于此仓库之外。\n\n### 工作原理\n\n```\nconfig\u002Fprojects.yaml          # 项目列表（仅包含 ID、名称、路径和状态）\nprojects\u002F\u003Cproject_id>.yaml    # 每个项目的完整详细信息\n```\n\n- **`config\u002Fprojects.yaml`**：一个简要的项目列表\n- **`projects\u002F\u003Cid>.yaml`**：完整的项目详情（客户信息、合同、任务、相关文件、Notion 页面等）\n- **项目文件**（源代码、文档等）存储在 `path` 指定的外部文件夹中\n- **`projects\u002F` 不包含在 git 中**（包含机密的客户信息）\n\n### 示例\n\n```yaml\n# config\u002Fprojects.yaml\nprojects:\n  - id: client_x\n    name: \"Client X Consulting\"\n    path: \"\u002Fmnt\u002Fc\u002FConsulting\u002Fclient_x\"\n    status: active\n\n# projects\u002Fclient_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: \"系统架构评审\"\n    status: in_progress\n```\n\n这种分离方式使得 Shogun 系统能够在多个外部项目之间进行协调，同时将项目细节排除在版本控制之外。\n\n---\n\n## 故障排除\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>使用 npm 版本的 Claude Code CLI？\u003C\u002Fb>\u003C\u002Fsummary>\n\nnpm 版本（`npm install -g @anthropic-ai\u002Fclaude-code`）已被官方弃用。请重新运行 `first_setup.sh` 以检测并迁移到原生版本。\n\n```bash\n# 重新运行 first_setup.sh\n.\u002Ffirst_setup.sh\n\n# 如果检测到 npm 版本：\n# ⚠️ 检测到 Claude Code CLI 的 npm 版本（已正式弃用）\n# 是否安装原生版本？[Y\u002Fn]:\n\n# 选择 Y 后，卸载 npm 版本：\nnpm uninstall -g @anthropic-ai\u002Fclaude-code\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>MCP 工具未加载？\u003C\u002Fb>\u003C\u002Fsummary>\n\nMCP 工具是惰性加载的。先搜索，再使用：\n```\nToolSearch(\"select:mcp__memory__read_graph\")\nmcp__memory__read_graph()\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>代理请求权限？\u003C\u002Fb>\u003C\u002Fsummary>\n\n代理应以 `--dangerously-skip-permissions` 参数启动。这由 `shutsujin_departure.sh` 自动处理。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>工作人员卡住？\u003C\u002Fb>\u003C\u002Fsummary>\n\n```bash\ntmux attach-session -t multiagent\n\n# 按 Ctrl+B 再按 0-8 切换窗格\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>代理崩溃了吗？\u003C\u002Fb>\u003C\u002Fsummary>\n\n**请勿在现有 tmux 会话中使用 `css`\u002F`csm` 别名来重启。** 这些别名会创建新的 tmux 会话，因此在已存在的 tmux 窗格内运行会导致会话嵌套——输入将失效，窗格也无法使用。\n\n**正确的重启方法：**\n\n```bash\n# 方法 1：直接在窗格中运行 claude\nclaude --model opus --dangerously-skip-permissions\n\n# 方法 2：Karo 通过 respawn-pane 强制重启（同时解决嵌套问题）\ntmux respawn-pane -t shogun:0.0 -k 'claude --model opus --dangerously-skip-permissions'\n```\n\n**如果您不小心嵌套了 tmux：**\n1. 按 `Ctrl+B` 然后 `d` 来分离（退出内部会话）\n2. 直接运行 `claude`（不要使用 `css`）\n3. 如果分离无效，请从另一个窗格使用 `tmux respawn-pane -k` 来强制重置\n\n\u003C\u002Fdetails>\n\n---\n\n## tmux 快速参考\n\n| 命令 | 描述 |\n|---------|-------------|\n| `tmux attach -t shogun` | 连接到 Shogun |\n| `tmux attach -t multiagent` | 连接到工作进程 |\n| `Ctrl+B` 后按 `0`–`8` | 切换窗格 |\n| `Ctrl+B` 后按 `d` | 分离（代理继续运行） |\n| `tmux kill-session -t shogun` | 停止 Shogun 会话 |\n| `tmux kill-session -t multiagent` | 停止工作进程会话 |\n\n### 鼠标支持\n\n`first_setup.sh` 会自动在 `~\u002F.tmux.conf` 中配置 `set -g mouse on`，从而启用直观的鼠标控制：\n\n| 操作 | 描述 |\n|--------|-------------|\n| 鼠标滚轮 | 在窗格内滚动（查看输出历史） |\n| 点击窗格 | 切换窗格焦点 |\n| 拖动窗格边框 | 调整窗格大小 |\n\n即使您不熟悉键盘快捷键，也可以仅使用鼠标切换、滚动和调整窗格大小。\n\n---\n\n## v3.5 新功能 — 动态模型路由\n\n> **为不同任务选择合适的模型——无需重启任何代理。** Sonnet 4.6 在 SWE-bench 上与 Opus 的差距缩小到仅 1.2pp（79.6% vs 80.8%），这使得基于任务的模型路由首次变得实用且经济高效。\n\n- **Bloom 动态模型路由** — `config\u002Fsettings.yaml` 中的 `capability_tiers` 将每个模型与其 Bloom 上限对应起来。L1–L3 → Spark（1000+ tok\u002Fs），L4 → Sonnet 4.6，L5 → Sonnet 4.6 + 扩展思考，L6 → Opus（仅用于真正新颖的设计）。路由无需重启代理——系统会根据模型能力找到合适的空闲代理。\n- **Sonnet 4.6 成为新标准** — SWE-bench 得分为 79.6%，仅比 Opus 4.6 低 1.2pp。Gunshi 已将默认模型从 Opus 更改为 Sonnet 4.6。所有 Ashigaru 默认使用 Sonnet 4.6。只需更改一行 YAML 文件，无需重启。\n- **`\u002Fshogun-model-list` 技能** — 完整参考表：所有 CLI 工具 × 模型 × 订阅 × Bloom 最大级别。针对 Sonnet 4.6 和 Spark 的定位进行了更新。\n- **`\u002Fshogun-bloom-config` 技能** — 交互式配置工具：回答关于您的订阅的两个问题→即可获得可直接粘贴的 `capability_tiers` YAML。\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>v3.4 的内容 — Bloom→代理路由、端到端测试、停止钩子\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **Bloom → 代理路由** — 用代理级别的路由取代了动态模型切换。L1–L3 任务交给 Ashigaru，L4–L6 任务交给 Gunshi。不再需要在会话中途执行 `\u002Fmodel opus` 提升操作。\n- **Gunshi（军师）作为一级代理** — 第 8 个窗格上的战略顾问。负责深度分析、设计评审、架构评估以及复杂的质量控制。\n- **端到端测试套件（19 个测试，7 种场景）** — 模拟 CLI 框架在隔离的 tmux 会话中模拟代理行为。\n- **停止钩子收件箱投递** — Claude Code 代理会在回合结束时通过 `.claude\u002Fsettings.json` 中的停止钩子自动检查收件箱。消除了 `send-keys` 中断的问题。\n- **模型默认值更新** — Karo：Opus → Sonnet。Gunshi：Opus（深度推理）。Ashigaru：Sonnet（统一层级）。\n- **Claude Code 的逃生升级被禁用** — 第二阶段升级会中断正在进行的 Claude Code 回合；改由停止钩子处理交付。\n- **Codex CLI 启动提示** — `cli_adapter.sh` 中的 `get_startup_prompt()` 将初始 `[PROMPT]` 参数传递给 Codex CLI 启动。\n- **YAML 精简工具** — `scripts\u002Fslim_yaml.sh` 会归档已读消息和已完成的命令。\n\n\u003C\u002Fdetails>\n\n## v3.3.2 新功能 — GPT-5.3-Codex-Spark 支持\n\n> **新模型，相同 YAML。** 在任何 Codex 代理的 `settings.yaml` 中添加 `model: gpt-5.3-codex-spark`。\n\n- **Codex `--model` 标志支持** — `build_cli_command()` 现在会通过 `--model` 将 `settings.yaml` 中的模型配置传递给 Codex CLI。支持 `gpt-5.3-codex-spark` 以及未来的所有 Codex 模型。\n- **独立速率限制** — Spark 使用自己的速率限制配额，与 GPT-5.3-Codex 无关。可以在不同的 Ashigaru 中并行运行这两种模型，以 **将有效吞吐量提高一倍**。\n- **启动显示** — `shutsujin_departure.sh` 现在会显示实际的模型名称（例如 `codex\u002Fgpt-5.3-codex-spark`），而不是通用的努力等级。\n\n## v3.0 新功能 — 多 CLI\n\n> **Shogun 不再仅限于 Claude。** 可以在一个团队中混合搭配 4 种 AI 编码 CLI。\n\n- **多 CLI 作为一级架构** — `lib\u002Fcli_adapter.sh` 会根据代理动态选择 CLI。只需更改 `settings.yaml` 中的一行，即可在 Claude Code、Codex、Copilot 或 Kimi 之间切换任何工作进程。\n- **OpenAI Codex CLI 集成** — GPT-5.3-codex 配合 `--dangerously-bypass-approvals-and-sandbox` 实现真正的自主执行。`--no-alt-screen` 使代理活动在 tmux 中可见。\n- **CLI 绕过标志发现** — `--full-auto` 并非完全自动（实际上是 `-a on-request`）。已记录下所有 4 种 CLI 的正确标志。\n- **混合架构** — 指挥层（Shogun + Karo）仍使用 Claude Code，以便实现 Memory MCP 和邮箱集成。工作层（Ashigaru）则与 CLI 无关。\n- **社区贡献的 CLI 适配器** — 感谢 [@yuto-ts](https:\u002F\u002Fgithub.com\u002Fyuto-ts)（cli_adapter.sh）、[@circlemouth](https:\u002F\u002Fgithub.com\u002Fcirclemouth)（Codex 支持）、[@koba6316](https:\u002F\u002Fgithub.com\u002Fkoba6316)（任务路由）。\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>v2.0 的内容\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **ntfy 双向通信** — 可以从手机发送命令，接收任务完成的推送通知。\n- **SayTask 通知** — 追踪连续完成的任务、吃掉那只青蛙、基于行为心理学的动力激励。\n- **窗格边框任务显示** — 在 tmux 窗格边框上一眼就能看到每个代理当前的任务。\n- **呐喊模式**（默认） — Ashigaru 在完成任务后会喊出个性化的战斗口号。可通过 `--silent` 关闭。\n- **代理自我监控 + 升级（v3.2）** — 每个代理使用 `inotifywait` 监控自己的收件箱文件（零轮询，即时唤醒）。备用方案：`tmux send-keys` 短促提醒（文本\u002F回车分别发送给 Codex CLI）。3 阶段升级：标准提醒（0-2 分钟）→ Escape×2+提醒（2-4 分钟）→ `\u002Fclear` 强制重置（4 分钟以上）。Linux FS 符号链接解决了 WSL2 9P inotify 问题。\n- **代理自我识别** (`@agent_id`) — 通过 tmux 用户选项实现稳定的身份，不受窗格重新排序的影响。\n- **战斗模式**（`-k` 标志） — 全部使用 Opus 形成，以达到最大能力。\n- **任务依赖系统**（`blockedBy`） — 自动解除依赖任务的阻塞。\n\n\u003C\u002Fdetails>\n\n---\n\n## 贡献\n\n欢迎提交问题和拉取请求。\n\n- **Bug 报告**：请开一个包含复现步骤的问题\n- **功能建议**：请先发起讨论\n- **技能**：技能设计为个人专属，因此不包含在本仓库中\n\n## 致谢\n\n基于 Akira-Papa 的 [Claude-Code-Communication](https:\u002F\u002Fgithub.com\u002FAkira-Papa\u002FClaude-Code-Communication)。\n\n## 许可证\n\n[MIT](LICENSE)\n\n---\n\n\u003Cdiv align=\"center\">\n\n**一条命令。八个智能体。零协调成本。**\n\n⭐ 如果你觉得这个项目有用，请给它点个星 —— 这有助于让更多人发现它。\n\n\u003C\u002Fdiv>","# multi-agent-shogun 快速上手指南\n\n**multi-agent-shogun** 是一个受日本封建军队层级启发的多智能体编排系统。它允许你通过简单的自然语言指令，并行调度多达 10 个 AI 编码助手（如 Claude Code, OpenAI Codex, GitHub Copilot, Kimi Code），实现零协调开销的高效开发。\n\n## 环境准备\n\n在开始之前，请确保你的系统满足以下要求：\n\n*   **操作系统**:\n    *   **Linux \u002F macOS**: 原生支持。\n    *   **Windows**: 必须安装 **WSL2 (Ubuntu)**。\n*   **核心依赖**:\n    *   `tmux` (终端复用器)\n    *   `bash` 4.0 或更高版本\n    *   `git`\n*   **AI 工具 (至少安装其中一个)**:\n    *   [Claude Code](https:\u002F\u002Fclaude.ai\u002Fcode) (推荐，功能最全)\n    *   OpenAI Codex CLI\n    *   GitHub Copilot CLI\n    *   Kimi Code CLI\n*   **网络环境**: 由于涉及多个 AI 服务的 API 调用，请确保网络通畅。国内用户建议使用稳定的代理工具或加速方案。\n\n## 安装步骤\n\n### 1. 克隆项目\n\n打开终端，运行以下命令下载源码：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\ncd multi-agent-shogun\n```\n\n### 2. 初始化配置\n\n运行一次性设置脚本，该脚本会自动检查依赖、配置环境变量并设置 MCP (Model Context Protocol)：\n\n```bash\nbash first_setup.sh\n```\n\n> **注意 (首次使用)**: 如果你使用的是 Claude Code，设置完成后需要运行一次认证命令：\n> ```bash\n> source ~\u002F.bashrc\n> claude --dangerously-skip-permissions\n> ```\n> 按提示在浏览器中登录 Anthropic 账号，并在终端确认授权 (\"Yes, I accept\")，最后输入 `\u002Fexit` 退出。\n\n### 3. 启动系统\n\n运行出征脚本，系统将自动启动所有配置的 Agent（包括 1 个指挥官 Karo, 7 个执行者 Ashigaru, 1 个军师 Gunshi）：\n\n```bash\nbash shutsujin_departure.sh\n```\n\n启动后，你将看到一个基于 `tmux` 的分屏仪表盘，实时显示各个智能体的工作状态。\n\n## 基本使用\n\n系统启动后，所有操作均在 **Shogun pane** (通常位于顶部或显著位置) 中进行。\n\n### 下达指令\n\n直接在 Shogun 面板中输入自然语言指令。无需编写复杂的 Prompt 或 JSON 配置。\n\n**示例：**\n\n> \"Build a REST API for user authentication\"\n> (构建一个用于用户认证的 REST API)\n\n### 工作流程\n\n1.  **接收**: Shogun 接收你的指令。\n2.  **分解**: Karo (管理者) 自动将大任务拆解为多个子任务。\n3.  **执行**: 7 个 Ashigaru (工作者) 并行执行子任务，Gunshi (军师) 提供策略支持。\n4.  **监控**: 你可以在仪表盘中实时看到每个 Agent 的输出日志和进度。\n5.  **完成**: 任务结束后，代码将直接生成在你的项目目录中。\n\n### 移动端控制 (可选)\n\n如果你需要在手机上监控或下达指令，该项目提供了专用的 Android App：\n1.  确保服务器端已开启 SSH (`sudo service ssh start`)。\n2.  在手机安装 `android\u002Frelease\u002Fmulti-agent-shogun.apk`。\n3.  在 App 设置中配置 SSH 连接信息（IP、端口、密钥\u002F密码、项目路径）。\n4.  即可通过手机语音或文字远程控制 AI 军团。\n\n---\n*现在，像封建领主一样指挥你的 AI 大军吧！*","某全栈开发团队需要在一天内为新的电商项目搭建包含用户认证、商品管理、订单处理及支付网关对接的完整后端 REST API 系统。\n\n### 没有 multi-agent-shogun 时\n- **串行开发效率低**：开发者只能依次调用单个 AI 助手，写完用户模块才能开始商品模块，整体耗时需数小时甚至更久。\n- **上下文切换频繁**：在不同任务间手动复制粘贴代码和提示词，容易出错且打断思路，难以维持全局架构的一致性。\n- **协调成本高昂**：若尝试手动运行多个终端窗口并行任务，缺乏统一指挥，导致代码冲突或逻辑重复，且无法实时监控各任务进度。\n- **资源等待浪费**：在等待一个 AI 生成代码或修复 Bug 时，开发者只能空闲等待，无法立即下达下一个指令。\n\n### 使用 multi-agent-shogun 后\n- **并行爆发式产出**：开发者只需在 Shogun 面板输入“构建电商后端 API\"，Karo 自动拆解任务，7 个 Ashigaru 代理同时并行编写不同模块，将数小时工作压缩至几分钟。\n- **层级化自动协同**：Shogun 作为总指挥统一分发指令，Gunshi（军师）负责策略校验，确保各模块接口定义一致，彻底消除人工协调带来的逻辑冲突。\n- **全景实时掌控**：通过 tmux 仪表盘可直观看到每个代理的实时编码进度和日志，开发者无需切换窗口即可掌握全局状态。\n- **零等待连续指令**：任务下发后无需等待结果，开发者可立即通过语音或文字下达优化或新增需求，AI 军队在后台持续执行，实现真正的“流式”开发。\n\nmulti-agent-shogun 将原本线性的单人辅助模式升级为并行的军团作战模式，让复杂系统开发从“手工打磨”变为“工业化量产”。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fyohey-w_multi-agent-shogun_053bf892.png","yohey-w","oshio","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fyohey-w_967c9868.png",null,"Japan","shio_shoppaize","https:\u002F\u002Fgithub.com\u002Fyohey-w",[84,88,92,96,100],{"name":85,"color":86,"percentage":87},"Shell","#89e051",75.5,{"name":89,"color":90,"percentage":91},"Kotlin","#A97BFF",18.6,{"name":93,"color":94,"percentage":95},"Python","#3572A5",4.6,{"name":97,"color":98,"percentage":99},"Batchfile","#C1F12E",0.7,{"name":101,"color":102,"percentage":103},"Makefile","#427819",0.6,1188,254,"2026-04-05T05:49:35","MIT","Linux, macOS, Windows (via WSL2)","未说明",{"notes":111,"python":109,"dependencies":112},"该工具是一个基于 Shell 脚本和 tmux 的多智能体编排系统，而非本地运行的深度学习模型，因此无需 GPU、特定 Python 版本或大型依赖库。核心要求是安装 tmux 和 Bash 4+，并至少配置一种支持的 AI CLI 工具（如 Claude Code）。Windows 用户需通过 WSL2 运行。支持通过专用 Android 应用进行移动端监控和控制，此时需在服务器端开启 SSH 服务。",[113,114,115,116,117,118,119],"tmux","bash 4+","SSH server (for mobile access)","Claude Code CLI","OpenAI Codex CLI","GitHub Copilot CLI","Kimi Code CLI",[13,26,15],[122,123,124,125,126,127,128,129,130,113],"ai-agent","anthropic","automation","claude-code","llm","multi-agent","parallel-processing","samurai","shogun","2026-03-27T02:49:30.150509","2026-04-06T07:12:44.346982",[134,139,144,149,154,158],{"id":135,"question_zh":136,"answer_zh":137,"source_url":138},16759,"macOS 上运行脚本时出现语法错误或行为异常，原因是什么？","主要原因是 macOS 默认使用旧版 bash 3.2（位于 \u002Fbin\u002Fbash），即使通过 Homebrew 安装了新版 bash，若脚本头部指定为 `#!\u002Fbin\u002Fbash` 仍会调用旧版。解决方案是将所有脚本的 Shebang 统一改为 `#!\u002Fusr\u002Fbin\u002Fenv bash`，这样会优先使用 PATH 中的新版 bash。同时，代码中需避免使用 bash 4+ 特有语法（如 mapfile），改用 POSIX 兼容写法（如 while read 循环）。","https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Fissues\u002F74",{"id":140,"question_zh":141,"answer_zh":142,"source_url":143},16760,"在 macOS 上执行 shutsujin_departure.sh 时报 'syntax error near unexpected token `>'' 错误，如何修复？","这是因为在行延续符（\\）后下一行以 `&>>` 开头，Shell 将其误解析为背景运行符。解决方法是避免在行延续后直接使用 `&>>`，改为单行书写并使用 POSIX 兼容的重定向语法：将 `&>> \"$LOG\"` 替换为 `>> \"$LOG\" 2>&1`。例如：`nohup bash script.sh ... >> \"$LOG\" 2>&1 &`。","https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Fissues\u002F21",{"id":145,"question_zh":146,"answer_zh":147,"source_url":148},16761,"项目是否支持同时使用 Claude Code、Codex 和 Copilot 等多种 AI CLI 工具？","支持。从 v3.0.0 版本开始实现了 Multi-CLI 支持。用户只需在 `settings.yaml` 中配置 `cli.default` 即可全局切换，也可针对特定 Agent 单独配置（如 `cli.agents.ashigaru5: codex`）。系统通过 `lib\u002Fcli_adapter.sh` 抽象层自动处理不同 CLI 的启动命令和指令文件加载，无需修改核心逻辑。","https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Fissues\u002F19",{"id":150,"question_zh":151,"answer_zh":152,"source_url":153},16762,"如何在不破坏现有架构的前提下引入代码审查（Review）机制？","建议分阶段实施：Phase 0（最小化方案）不新增角色，而是将“审查”作为现有足轻的任务之一，由家老在验收步骤（Step 11.7）判定结果；Phase 1 再将审查流程 YAML 化，实现“一审查一文件”。关键原则是维持 `Lord → Shogun → Karo → Ashigaru` 指挥链，审查结果通过 `inbox_write.sh` 通知，严禁绕过家老或直接操作 tmux。","https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Fissues\u002F23",{"id":155,"question_zh":156,"answer_zh":157,"source_url":138},16763,"macOS 用户遇到足轻启动失败或中途退出等不稳定现象，该如何排查？","首先检查脚本 Shebang 是否为 `#!\u002Fusr\u002Fbin\u002Fenv bash` 以确保使用正确版本的 bash。其次，在 `first_setup.sh` 或启动日志中加入 `bash --version` 和 `command -v bash` 的输出，确认实际执行的 bash 路径和版本。若仍存在问题，请检查是否使用了 bash 3.2 不支持的语法（如数组操作、正则匹配等），并替换为兼容写法。",{"id":159,"question_zh":160,"answer_zh":161,"source_url":143},16764,"如何确保脚本在不同操作系统（macOS\u002FLinux）上的兼容性？","遵循以下原则：1) 所有脚本使用 `#!\u002Fusr\u002Fbin\u002Fenv bash` 作为 Shebang；2) 避免使用 bash 4+ 特性，改用 POSIX 标准语法（如用 `>> file 2>&1` 代替 `&>> file`）；3) 行延续符（\\）后不要紧跟特殊符号（如 &、>）；4) 在 CI 中加入 macOS 环境测试；5) 关键脚本增加版本检测日志，便于定位环境问题。",[163,168,173,178,183,188,193,198,203,208,213,218,223,228,233,238,243,248,253],{"id":164,"version":165,"summary_zh":166,"released_at":167},99027,"v4.4.1","## 修复：Android 限流显示 + SSH 改进\n\n### 修复\n- Android 应用中限流显示不工作（未捕获 stderr，缺少 2>&1）\n- SSH 私钥加载问题（改为读取文件字节而非路径引用）\n- 在窄分栏面板中 Codex \u002Fstatus 数据被截断（缩放捕获）\n\n### 新增\n- 限流对话框中新增原始输出\u002FUI 切换开关，便于调试\n- 解析失败回退机制——当无法解析数据时，自动显示原始输出\n- 设置中新增 SSH 密钥文件选择器","2026-03-28T11:41:00",{"id":169,"version":170,"summary_zh":171,"released_at":172},99028,"v4.4.0","## [4.4.0] - 2026-03-28\n\n### 新增\n- karo 日志：在命令执行完毕时，自动将摘要追加到 `logs\u002Fdaily\u002FYYYY-MM-DD.md` 文件中（PR #95）\n- `.gitignore`: 将 `.claude\u002Fsettings.local.json` 添加到忽略列表中\n\n### 变更\n- `instructions\u002Fkaro.md`: 将 ntfy 通知步骤从第6步移至第7步，并在第6步插入每日日志追加功能\n- `instructions\u002Froles\u002Fkaro_role.md`: 已同步\n- 针对所有 CLI 工具重新生成自动生成的说明文件（codex\u002Fcopilot\u002Fkimi-karo.md）","2026-03-27T23:57:40",{"id":174,"version":175,"summary_zh":176,"released_at":177},99029,"v4.3.0","## 新增\n- `shutsujin_departure.sh`: 所有 Claude Code 代理程序现在默认以 `--effort max` 启动（包括 shogun、karo、ashigaru 和 gunshi）","2026-03-27T23:18:11",{"id":179,"version":180,"summary_zh":181,"released_at":182},99030,"v4.2.0","## 变更内容\n\n### 新增\n- `install.bat`: 通过 `wsl -e bash` 动态解析 WSL 的 `$HOME` 路径 — 适用于任何用户名和电脑\n- `shutsujin_departure.sh`: `csst` 别名现在使用 `$HOME\u002Fmulti-agent-shogun`\n\n### 修改\n- `install.bat`: 更新了仓库引用，将 `feature-shogun` 改为 `multi-agent-shogun`\n- `config\u002Fsettings.yaml`: 将技能\u002F日志\u002F图片的路径改为相对路径 `.\u002F`（提高可移植性）\n- `scripts\u002Fbackup_daily.sh`: cron 示例使用基于 `$HOME` 的路径\n- 重新生成了 `AGENTS.md` 和 `copilot-instructions.md`（包含 bloom_routing_rule 和 后压缩恢复功能）\n\n### 修复\n- `inbox_write.sh`: 移除了对 `xxd` 的依赖（提升 CI 兼容性）\n- `tests\u002Funit\u002Ftest_idle_flag.bats`: T-008 已更新，以匹配 v4.0.1 版本的空闲标志设计","2026-03-24T10:36:12",{"id":184,"version":185,"summary_zh":186,"released_at":187},99031,"v4.1.3","### 变更\n\n- **stop_hook**: 跳过 shogun 窗格的停止钩子（仅限对话）\n- **skill**: 为模型切换技能添加 `argument-hint`","2026-03-14T00:33:16",{"id":189,"version":190,"summary_zh":191,"released_at":192},99032,"v4.1.2","### 错误修复\n\n- **stop_hook**: 跳过 shogun 窗格（仅对话）的停止钩子 — shogun 窗格是主控的交互式会话，不应因收件箱等待而被阻塞。","2026-03-14T00:01:49",{"id":194,"version":195,"summary_zh":196,"released_at":197},99033,"v4.0","## 新功能\n\n### Android 伴侣应用 📱\n通过手机监控和控制你的 AI 助手军团。你可以在 sengoku 主题的 Android 应用中 SSH 连接到 tmux 会话、查看所有 9 个助手面板、检查仪表盘并发送命令。\n\n**下载：** [`multi-agent-shogun.apk`](https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Fraw\u002Fmain\u002Fandroid\u002Frelease\u002Fmulti-agent-shogun.apk)\n\n| 功能 | 描述 |\n|---------|-------------|\n| 将军终端 | 带有 ANSI 256 色、特殊键栏和语音输入的实时 SSH 终端 |\n| 助手网格 | 9 窗格视图（Karo + 7 Ashigaru + Gunshi），支持批量 SSH 刷新 |\n| 仪表盘 | 使用 WebView 渲染 dashboard.md，并支持表格文本选择 |\n| 速率限制监控 | Claude Max 使用情况（5 小时\u002F7 天窗口），配有进度条 |\n| 语音输入 | 日语连续语音识别，实现免提操作 |\n| 截图分享 | 通过 Android 分享菜单将截图分享到将军 |\n\n\u003Cp align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Fraw\u002Fmain\u002Fandroid\u002Fscreenshots\u002F01_shogun_terminal.png\" width=\"200\">\n\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Fraw\u002Fmain\u002Fandroid\u002Fscreenshots\u002F02_agents_grid.png\" width=\"200\">\n\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Fraw\u002Fmain\u002Fandroid\u002Fscreenshots\u002F03_dashboard.png\" width=\"200\">\n\u003C\u002Fp>\n\n### 其他改进\n- 技能创建器已重写为最新的 Claude Code SKILL.md 规范\n- 修复了收件箱监听器的空闲标志，以防止假忙死锁\n- 修复了 E2E-008 启动提示的传递问题","2026-02-28T23:35:47",{"id":199,"version":200,"summary_zh":201,"released_at":202},99034,"v3.9","## 新增内容\n\n### 技能创建器重写\n- 完全重写 `skills\u002Fskill-creator\u002FSKILL.md` 文件，使其符合最新的 Claude Code SKILL.md 规范（2026-02）\n- 涵盖所有 frontmatter 字段：`context: fork`、`agent`、`hooks`、`model`、`allowed-tools`\n- 动态特性：`$ARGUMENTS` \u002F `$0` 参数替换、`!`命令`` 预执行\n- 文档化三种执行模式：内联模式 \u002F 分叉模式 \u002F 仅手动模式\n- 包含 7 项描述质量检查清单及反模式指南\n- 符合 Agent Skills 开放标准 (agentskills.io)\n\n### 收件箱稳定性修复\n- **误忙死锁修复**：CLI 在欢迎界面现在会在监视器启动时获得初始空闲标志——防止“代理忙碌”无限循环导致提示无法送达\n- **安全网修复**：在忙碌状态且使用 Claude 代码路径时，`FIRST_UNREAD_SEEN` 现已正确初始化，从而启用过期忙碌超时机制\n- 这两项修复解决了在统一停止钩子（v3.8）之后发现的生产环境死锁问题。\n\n### 端到端测试覆盖率\n- 新增 E2E-008-F 回归测试：“Claude 在欢迎界面且无空闲标志”\n- 可捕获导致误忙死锁的精确启动竞争条件\n- 使用隔离的 `IDLE_FLAG_DIR` 目录，避免模拟数据掩盖真实缺陷。\n\n### 其他\n- `.gitignore`：排除 `.venv\u002F` 和客户端特定的规范文件\n- 在说明中匿名化客户端名称\n\n## 完整变更日志\nhttps:\u002F\u002Fgithub.com\u002Fyohey-w\u002Fmulti-agent-shogun\u002Fcompare\u002Fv3.8...v3.9","2026-02-28T03:36:09",{"id":204,"version":205,"summary_zh":206,"released_at":207},99035,"v3.8","## 新增功能\n\n### 标志文件忙碌检测 (#cmd_222)\n- 用标志文件方式替代不可靠的面板忙碌检测\n- Claude 代码停止钩子会写入\u002F删除 `\u002Ftmp\u002Fshogun_idle_{agent_id}`\n- 消除了思考过程中的误判空闲状态（此前已尝试过 48 次修复）\n- 非 Claude 的 CLI 将回退到旧版面板分析\n\n### 命令队列归档规则 (#cmd_227)\n- 活跃队列 (`shogun_to_karo.yaml`) 只保留 `pending` 和 `in_progress` 状态的任务\n- 已完成的命令会自动归档到 `shogun_to_karo_archive.yaml`\n- 统一的状态集：pending、in_progress、done、cancelled、paused\n- 将队列文件从 42K 个 token 减少到不到 500 个 token\n\n### 测试规范\n- 代理自我监控规范","2026-02-27T22:37:05",{"id":209,"version":210,"summary_zh":211,"released_at":212},99036,"v3.7","## 新增功能\n- 按 Bloom 层级范围设置显式模型优先级列表\n- 配置：bloom_model_preference: {L1-L3: [...], L4-L5: [...], L6: [...]}\n- 如果首选模型不可用，则回退到成本优先级\n- 93 个测试通过","2026-02-25T22:14:34",{"id":214,"version":215,"summary_zh":216,"released_at":217},99037,"v3.6","## What's New\n- Repo-local MEMORY.md (OSS memory pattern)\n- Private repo separation (shogun-private)\n- English instruction files + north_star field\n- macOS bash 3.2 compatibility fixes","2026-02-25T22:14:28",{"id":219,"version":220,"summary_zh":221,"released_at":222},99038,"v3.5","## What's New\n- Full Bloom Taxonomy (L1-L6) model routing\n- Dynamic model switching based on task complexity\n- shogun-bloom-config wizard skill","2026-02-25T22:14:23",{"id":224,"version":225,"summary_zh":226,"released_at":227},99039,"v3.4","## What's New\n- Bloom Taxonomy → Agent routing\n- E2E test suite with mock CLI\n- Stop hook inbox delivery","2026-02-25T22:14:18",{"id":229,"version":230,"summary_zh":231,"released_at":232},99040,"v3.3.2","## What's New\n- --model flag support for Codex CLI\n- GPT-5.3-Codex-Spark ready","2026-02-25T22:14:14",{"id":234,"version":235,"summary_zh":236,"released_at":237},99041,"v3.3.1","## What's New\n- Dismiss Codex suggestion UI before nudge\u002Freset","2026-02-25T22:14:09",{"id":239,"version":240,"summary_zh":241,"released_at":242},99042,"v3.3.0","## What's New\n- Idle polling after context reset\n- Codex suggestion UI handling\n- Watcher stability improvements","2026-02-25T22:14:05",{"id":244,"version":245,"summary_zh":246,"released_at":247},99043,"v3.2.0","## What's New\n- Agent self-watch Phase 1-3 (event-driven monitoring, timeout fallback)\n- GitHub Actions CI pipeline\n- Token cost optimization metrics","2026-02-25T22:14:00",{"id":249,"version":250,"summary_zh":251,"released_at":252},99044,"v3.1.0","## What's New\n- Eliminate tmux send-keys for nudge delivery\n- PTY direct write for \u002Fclear and \u002Fmodel commands\n- More reliable agent wake-up","2026-02-25T22:13:55",{"id":254,"version":255,"summary_zh":256,"released_at":257},99045,"v3.0.0","## What's New\n- 4 CLIs supported: Claude Code, OpenAI Codex, GitHub Copilot, Kimi Code\n- Unified instruction build system (build_instructions.sh)\n- CLI-specific tool descriptions (instructions\u002Fcli_specific\u002F)","2026-02-25T22:13:50"]