multi-agent-shogun Agent工作流

Task Dependencies (blockedBy)

Tasks can declare dependencies on other tasks using blockedBy:

```yaml

First-time setup

```bash

3. Run first-time setup

./first_setup.sh ```

What `install.bat` does automatically:

• ✅ Checks if WSL2 is installed (guides you if not)
• ✅ Checks if Ubuntu is installed (guides you if not)
• ✅ Shows next steps (how to run first_setup.sh)

After Setup

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

Two tmux sessions are created: - shogun — connect here to give commands - multiagent — Karo, Ashigaru, and Gunshi running in the background

---

One-time setup (already done by first_setup.sh)

git init --bare ~/.shogun-private.git alias privategit='git --git-dir=$HOME/.shogun-private.git --work-tree=/path/to/multi-agent-shogun' privategit remote add origin https://github.com/YOU/shogun-private.git

MCP Setup Guide

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

Installing MCP Servers

Add MCP servers with these commands:

```bash

Note: Run `npx playwright install chromium` first

Quick Start

Requirements: tmux, bash 4+, at least one of: Claude Code / Codex / Copilot / Kimi / OpenCode / Antigravity

git clone https://github.com/yohey-w/multi-agent-shogun
cd multi-agent-shogun
bash first_setup.sh                        # one-time setup: config, dependencies, MCP
source ~/.bashrc                           # reload PATH
claude --dangerously-skip-permissions      # first run only: OAuth + accept Bypass Permissions → /exit
bash shutsujin_departure.sh                # launch all agents

For full install steps (incl. Windows) and the first-30-minutes walkthrough, see 🚀 Quick Start and the basic usage section below.

Type a command in the Shogun pane:

"Build a REST API for user authentication"

Shogun delegates → Karo breaks it down → 7 Ashigaru execute in parallel. You watch the dashboard. That's it.

Want to go deeper? The rest of this README covers architecture, configuration, memory design, and multi-CLI setup.

---

Quick Start

projects/example.yaml

id: example name: "Sample Project" working_directory: /path/to/repo north_star: "The ultimate goal for this project" notes: | Project-specific notes, stakeholders, special rules

The Shogun and Karo reference this file and inject project context when issuing cmds.

Detailed project knowledge (requirements, design, past feedback) lives in `context/{name}.md`. When the Shogun issues a cmd related to the project, it automatically references this file.

#### 3. Customizing the agent formation

The agent formation (which CLI each agent uses) lives in `config/settings.yaml`:

OpenCode uses provider-qualified model IDs:

OpenRouter setup has two separate pieces:

1. **Model routing** goes in `config/settings.yaml` as shown above (`type: opencode`, `model: openrouter/...`).
2. **Provider authentication** is configured in OpenCode, not in `settings.yaml`. Run OpenCode once as the same OS user that will launch Shogun, then use `/connect` → `OpenRouter` and paste the API key. OpenCode stores provider credentials in its own user data under that OS user (for example under `~/.local/share/opencode/`; the exact file/database is OpenCode-internal). For headless deployments that use environment-based provider credentials, make sure the shell that runs `shutsujin_departure.sh` has `OPENROUTER_API_KEY` loaded.

Do not put API keys in `config/settings.yaml`, `config/opencode-tui.json`, or `.opencode/agents/*.md`. Those files only describe routing, tmux-safe keybindings, and generated agent definitions.

When OpenCode is selected, `lib/cli_adapter.sh` launches it with `--agent <agent_id>` and the repository-pinned `OPENCODE_TUI_CONFIG=config/opencode-tui.json`. The TUI command does not accept `--variant`; if `variant:` is configured, `scripts/build_instructions.sh` and `scripts/switch_cli.sh` synchronize `model:` / `variant:` into a git-ignored `.opencode/agents/<agent_id>-runtime.md`, which OpenCode loads via `--agent <agent_id>-runtime`.

To switch on the fly, use `scripts/switch_cli.sh`:

4. Switching or closing a project

There is no explicit "close project" command. Issuing the next project's cmd automatically switches context.

• Pause temporarily: do nothing. Old cmds remain in queue/ as history, and the Shogun restores state when resumed
• Fully retire: delete projects/{name}.yaml, or add an archived: true flag
• Run in parallel: use the project: field in cmds to keep concurrent projects distinct

5. Carrying experience and settings between projects

What carries forward to future projects:

Memory MCP is the heart of "experience." When you tell the Shogun "don't do X next time" or "remember Y," the Shogun records it in Memory MCP, and all future projects see it.

Use Cases

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

→ "Bypass Permissions" prompt appears → Select "Yes, I accept" (↓ to option 2, Enter)

Set your screenshot folder in config/settings.yaml

screenshot: path: "/mnt/c/Users/YourName/Pictures/Screenshots"

Model Settings

Thinking control: Set thinking: true/false per agent in config/settings.yaml. When thinking: false, the agent starts with MAX_THINKING_TOKENS=0 to disable Extended Thinking. Pane borders show +T suffix when Thinking is enabled (e.g., Sonnet+T, Opus+T).

Live model switching: Use /shogun-model-switch to change any agent's CLI type, model, or Thinking setting without restarting the entire system. See the Skills section for details.

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

Why CLI (Not API)?

Most AI coding tools charge per token. Running 8 Opus-grade agents through the API costs $100+/hour. CLI subscriptions flip this:

"Use AI recklessly" — With flat-rate CLI subscriptions, deploy 8 agents without hesitation. The cost is the same whether they work 1 hour or 24 hours. No more choosing between "good enough" and "thorough" — just run more agents.

Multi-CLI Support

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

OpenCode sessions load the agent-specific .opencode/agents/<agent_id>.md definition via --agent and keep automation resets on /new; model changes require a relaunch. Automation uses the repository-provided config/opencode-tui.json via OPENCODE_TUI_CONFIG, which disables app_exit and pins session_interrupt/input_clear to known bindings. Role boundaries are embedded in the generated agent frontmatter: Shogun can read queue/reports/* for oversight but cannot write them, Karo is limited to coordination files plus report aggregation, Ashigaru only touch their own task/report pair, and Gunshi reads ashigaru reports but only writes gunshi_report.yaml.

Antigravity sessions launch with agy --dangerously-skip-permissions. Shogun treats type: antigravity, type: agy, and legacy type: gemini as Antigravity. Authentication and default model selection stay in the host user's Antigravity CLI setup; settings.yaml may optionally pass a concrete model, but auto uses the host default or last-used model.

A unified instruction build system generates CLI-specific instruction files from shared templates:

instructions/
├── common/              # Shared rules (all CLIs)
├── cli_specific/        # CLI-specific tool descriptions
│   ├── claude_tools.md  # Claude Code tools & features
│   ├── copilot_tools.md # GitHub Copilot CLI tools & features
│   ├── opencode_tools.md # OpenCode tools, agent frontmatter, and permission model
│   └── cursor_tools.md  # Cursor Agent tools, skills, and session rules
└── roles/               # Role definitions (shogun, karo, ashigaru)
    ↓ build
CLAUDE.md / AGENTS.md / .github/copilot-instructions.md / .opencode/agents/*.md / .cursor/rules/*.md
  ← Generated per CLI

One source of truth, zero sync drift. Change a rule once, all CLIs get it.

---

🔄 2. Non-Blocking Workflow

The Shogun delegates instantly and returns control to you:

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

No waiting for long tasks to finish.

📸 6. Screenshot Integration

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

```yaml

SayTask vs cmd Pipeline

Shogun has two complementary task systems:

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

---

FAQ

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

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

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

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

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

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