以日本封建武士阶层为隐喻的多智能体 AI 编码编排系统，通过 tmux 并行运行多个 AI CLI 实例，基于 YAML 文件通信实现零 token 编排开销。
multi-agent-shogun 是一个基于 Bash 和 tmux 的多智能体编排系统，采用日本封建武士阶层隐喻设计代理层级：Shogun（将军）接收用户命令，Karo（家老）分解任务，7 个 Ashigaru（足轻）并行执行实现任务，Gunshi（军师）负责分析评估，共计 10 个 AI 代理协同工作。
系统核心设计理念是零协调开销——代理间通过磁盘上的 YAML 文件通信，配合 inotifywait 事件驱动唤醒和 flock 文件锁防竞态，编排过程完全不消耗 API token。这一设计使得在 CLI 固定费率订阅模式下，可以同时运行 8 个 Opus 级代理而无需担心按 token 计费。
在 CLI 适配方面，系统构建了统一的指令模板体系（instructions/ 目录），从共享规则、CLI 专用工具描述和角色定义三层模板自动生成各 CLI 的指令文件（CLAUDE.md、AGENTS.md、copilot-instructions.md 等），通过 lib/cli_adapter.sh 屏蔽不同 CLI 的参数差异，实现同一套编排逻辑对 Claude Code、OpenAI Codex、GitHub Copilot、Kimi Code 四种 CLI 的统一支持。
系统具备自底向上的技能发现机制：Ashigaru 在执行任务时自动识别可复用模式并提议为 skill，经用户批准后成为永久技能，沉淀到 skills/ 目录。Memory MCP 机制则实现了偏好和上下文的跨会话持久化。运行时通过 dashboard.md 和 dash 命令提供实时进度视图，用户也可通过 Android 伴侣应用经 SSH 远程监控和语音指挥所有代理。
架构概览#
用户 (上様 / The Lord)
│
▼ 下达命令
┌─────────────┐
│ SHOGUN │ ← 接收命令，立即委派
└──────┬──────┘
│ YAML + tmux
┌──────▼──────┐
│ KARO │ ← 分配任务给工作者
└──────┬──────┘
│
┌─┬─┬─┬─┴─┬─┬─┬─┬────────┐
│1│2│3│4│5│6│7│ GUNSHI │ ← 7 工作者 + 1 军师
└─┴─┴─┴─┴─┴─┴─┴────────┘
ASHIGARU 軍師
进程管理与通信#
- 载体：tmux 会话 + 窗格，每个代理独占一个 tmux 窗格
- 会话划分：
shogun会话（用户交互入口）与multiagent会话（Karo + 7×Ashigaru + Gunshi 后台面板）分离 - 消息格式：YAML 文件，流向为 Shogun →
queue/shogun_to_karo.yaml→ Karo → 各 Ashigaru inbox YAML - 写入安全：
scripts/inbox_write.sh通过flock实现文件锁 - 消费唤醒：
scripts/inbox_watcher.sh使用inotifywait监听文件事件，触发tmux send-keys唤醒目标代理
快速开始#
前置要求：tmux、bash 4+、至少一个 AI CLI（Claude Code / Codex / Copilot / Kimi）
git clone https://github.com/yohey-w/multi-agent-shogun
cd multi-agent-shogun
bash first_setup.sh
source ~/.bashrc
claude --dangerously-skip-permissions
bash shutsujin_departure.sh
Windows (WSL2) 用户可下载 ZIP 后以管理员身份运行 install.bat 自动配置 WSL2 + Ubuntu。
典型应用场景#
- 并行代码生成：如同时实现 REST API 的多个端点
- 批量调研：多个 Ashigaru 同时调研不同主题并汇总
- 多 CLI 互补：不同任务分配给不同 CLI（Claude Code 做 tmux 集成、Codex 做沙盒执行、Copilot 做 GitHub 集成）
- 远程/移动指挥：通过 Android 应用 SSH 连接，语音下达命令并监控代理面板
待确认信息#
- 作者 yohey-w 的身份和所属组织未公开
- 是否存在独立文档站待确认，当前以 GitHub README 为主要文档来源
- 与 LangGraph/CrewAI 的对比缺乏独立基准测试数据
- 当前代理角色和数量为固定配置，是否支持动态扩缩容待确认
- 非 Claude Code CLI 的实际兼容完整度待验证