Shogun Multi-Agent Command
A tmux-based command hierarchy for running multiple coding CLIs on parallel development tasks.
- Source repo
- yohey-w/multi-agent-shogun
- Stars
- ★ 1.4k
- Last updated
- 3mo ago
- License
- MIT
- Primary language
- Shell
- FA score
- 48/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A solo developer using Claude Code or Codex CLI who wants API implementation, tests, and documentation handled in parallel sessions.
- Not a fit if
- Users without a tmux, Bash, and Linux/WSL terminal environment
- Teams unwilling to accept --dangerously-skip-permissions bypass mode
- Users who need an iOS companion app
- Source review
- 48/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
multi-agent-shogun is a Shell and tmux orchestration system that routes a user command from Shogun through Karo to seven Ashigaru workers and one Gunshi strategist. Rather than relying on a single hosted API, it can configure Claude Code, OpenAI Codex, GitHub Copilot, Kimi Code, OpenCode, Cursor, and Antigravity CLI sessions by role. Tasks, inboxes, and reports are persisted as YAML files, while Karo aggregates outcomes into dashboard.md and tmux panes expose each running session. It also documents project-scoped context files, Memory MCP, screenshot paths, ntfy notifications, and an Android SSH companion app. It is best suited to developers prepared to operate a local or WSL/Linux terminal environment with several authenticated coding CLI sessions.
After first_setup.sh configures dependencies, shutsujin_departure.sh creates the shogun and multiagent tmux sessions and launches each configured role from config/settings.yaml. A command entered in the Shogun pane is written to queue/shogun_to_karo.yaml; Karo writes subtasks to queue/tasks/, while Ashigaru and Gunshi complete work in their panes and write results to queue/reports/. inbox_write.sh and inbox_watcher.sh deliver work through file changes and short tmux nudges, and Karo aggregates reports, updates dashboard.md, and manages blockedBy dependencies. scripts/switch_cli.sh changes a role's CLI or model during operation, while scripts/agent_status.sh reports pane, task, and inbox state.
- A solo developer using Claude Code or Codex CLI who wants API implementation, tests, and documentation handled in parallel sessions.
- A Windows developer working through WSL2 who wants a live tmux view of a Shogun, manager, and multiple coding workers.
- An engineering lead who needs to assign Claude Code, Codex, Copilot, or OpenCode to different roles in one operating model.
- A developer running several long-lived codebases who wants project context stored in projects/{name}.yaml and context/{name}.md.
- A developer who wants to monitor tmux over SSH from Android or receive task-completion notifications through ntfy.
How do you install or deploy this agent?
Requirements are tmux, Bash 4+, and at least one supported coding CLI. On Linux or macOS:
git clone https://github.com/yohey-w/multi-agent-shogun.git ~/multi-agent-shogun
cd ~/multi-agent-shogun
chmod +x *.sh
./first_setup.shReload PATH with source ~/.bashrc. For Claude Code, the documented first-run authentication is claude --dangerously-skip-permissions, followed by OAuth, accepting Bypass Permissions, and /exit. On Windows, place the repository at C:\tools\multi-agent-shogun, run install.bat, then run ./first_setup.sh in WSL Ubuntu.
How do you use this agent?
From the repository directory, run ./shutsujin_departure.sh. In another terminal, run tmux attach-session -t shogun and enter a development request such as "Build a REST API for user authentication." The command is delegated to Karo and split across workers; inspect dashboard.md for aggregated progress or run bash scripts/agent_status.sh for status. To change a role's CLI and model, use a documented command such as: bash scripts/switch_cli.sh ashigaru3 --type opencode --model openrouter/openai/gpt-4o-mini.
What are this agent's strengths and limitations?
- Uses a defined Shogun→Karo→Ashigaru/Gunshi chain of responsibility and separate tmux sessions for visible parallel work.
- Persists commands, inboxes, tasks, and reports as YAML, making the coordination trail inspectable and recoverable from files.
- Supports role-level selection across seven documented coding CLIs, with a unified process for generating CLI-specific instructions.
- Includes operational features beyond dispatch: project context, blockedBy dependencies, dashboard.md, status checks, ntfy, and Android remote access.
- Its operating model depends on tmux, Bash, a filesystem, and interactive coding CLIs; Windows use requires WSL2.
- Every selected CLI must be installed and authenticated separately, with the relevant subscription or provider credentials; OpenCode also requires provider authentication.
- The documented Claude Code first-run flow uses --dangerously-skip-permissions and asks the user to accept Bypass Permissions, which requires a deliberate local security review.
- The companion application is Android-only; the documentation explicitly states that there is no iOS version.
- Parallel execution consumes multiple CLI sessions at once, so available capacity, model access, and usage limits remain dependent on the configured providers.
How does this agent compare with similar options?
The repository contrasts its design with Claude Code Task, Claude Code Agent Teams, LangGraph, and CrewAI. Its approach is separate tmux CLI sessions coordinated through YAML files, with direct pane visibility and multi-CLI support; local Shell scripts consequently carry the deployment and session-management responsibility.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Shogun Multi-Agent Command This agent | 48 · Major gaps | CLIFree + model costs | ★ 1.4k | 3mo ago | Shell | Codex · Claude Code |
| Oh My OpenAgent | 49 · Major gaps | Agent plugin / skillFree + model costs | ★ 71k | today | TypeScript | Claude Code |
| Agent Deck | 76 · Good | CLIFree + model costs | ★ 1.2k | today | Go | Codex · Claude Code |
| CLI Agent Orchestrator | 65 · Some gaps | CLIFree + model costs | ★ 1.5k | today | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README describes an architecture based on YAML file communication and emphasizes transparency (each agent runs in a visible tmux pane). SECURITY.md provides security best practices, including using environment variables for secrets, avoiding hardcoded tokens, using strong ntfy topics, and excluding sensitive directories via .gitignore. However, there is no evidence of least privilege mechanisms (e.g., agents can access all files) or user confirmation mechanisms (e.g., requesting approval before executing commands). Data flow transparency is partially supported because YAML files are readable and version-controllable, but there is no explicit handling of sensitive data. Dependency security is only partially supported via pyyaml in requirements.txt and shellcheck in CI. External effects (e.g., ntfy notifications) are documented, but no rollback mechanism is provided. Source attribution is only partially supported via MIT license and author name.
Evidence shows: README and CI workflow indicate the existence of a test suite (bats tests, E2E tests), but no test results are provided. Dependency availability is partially supported because dependencies are listed (tmux, bash, CLI tools), but no version pinning is provided. Failure messages are partially supported because CI workflow includes error output, but no user-friendly error handling is provided.
Evidence shows: README describes multiple usage scenarios (Windows/WSL2, Linux/macOS, mobile access) and provides detailed installation instructions. Capability boundaries are partially supported through role definitions (Shogun, Karo, Ashigaru, Gunshi), but limitations are not explicitly stated. Trigger precision is partially supported because commands are passed via YAML files, but no precise trigger conditions are provided. Environment fit is supported through support for multiple CLIs and operating systems.
Evidence shows: README provides clear information architecture (directory structure, script reference). Installation notes are detailed, including Windows and Linux/macOS. Naming stability is partially supported because version tags exist (v5.1.0), but no changelog is provided. Examples and FAQ are partially supported because README includes examples and common questions. Known limitations are partially supported because limitations are mentioned in SECURITY.md and README (e.g., Android-only app). License is MIT, versioning is partially supported via Git tags, and maintenance responsibility is partially supported via security policy in SECURITY.md.
Evidence shows: README claims output is YAML files, readable and version-controllable, supporting output usability. Marginal value is supported through comparison with other frameworks, claiming zero coordination overhead. Cost-benefit is supported through comparison of CLI subscriptions vs API pricing.
Evidence shows: Claims in README (e.g., zero coordination overhead, 8 independent agents) are not verified through reproducible tests or benchmarks. Cross-source corroboration is limited because only a single source is provided. Fact-inference separation is partially supported because README distinguishes feature descriptions from performance claims, but not explicitly labeled.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Unverified publisher identity: Publisher is not verified in the FollowAgents enterprise registry, treat as unknown.
- Lack of least privilege and user confirmation: Agents may have broad filesystem access, and there is no mechanism to request user approval before executing commands.
- Limited dependency security: Only pyyaml is listed, no version pinning or vulnerability scanning.
- No rollback mechanism: No evidence of ability to rollback agent actions.
- Test results not provided: CI workflow exists, but no test results are provided, so reliability claims cannot be verified.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v5.1.0 v5.1.0 - Karo as Traffic Controller
Release notes excerpt
Changed - Clarified Karo as a workflow traffic controller instead of an execution bottleneck - Moved qualitative review ownership to Gunshi for QC, evidence review, RCA, adoption/drop decisions, and deploy blocker classification - Reframed E2E ownership: Karo reviews the plan, checks prerequisites, and makes the final pass/fail decision while execution is delegated by default - Regenerated Claude, Codex, Copilot, Kimi, and OpenCode instruction files from the updated role definitions Fixed …View on GitHub ↗ -
v5.0.0 v5.0.0 - OpenCode First-Class Support
Release notes excerpt
Highlights - OpenCode is now a first-class CLI for Shogun, Karo, Ashigaru 1-7, and Gunshi. - Generated .opencode/agents/*.md files define role-specific OpenCode agents from the shared instruction source. - config/opencode-permissions.yaml scopes OpenCode role permissions. - config/opencode-tui.json pins tmux-safe keybindings. - settings.yaml supports provider-qualified OpenCode model IDs such as opencode/qwen3.6-plus-free and openrouter/openai/gpt-4o-mini. Fixes - macOS CI now uses the project venv for scripts/slim_yaml.py, fixing PyYAML import failures. …View on GitHub ↗ -
Release notes excerpt
[4.6.0] - 2026-04-19 Added - shutsujin_departure.sh: --auto-mode-on flag (maps to --dangerously-skip-permissions) and --permission-mode <mode> for custom permission flags (Issue #124) - lib/cli_adapter.sh: accept PERMISSION_FLAG override from departure script, backward-compatible Fixed - Report flow unified to Ashigaru → Gunshi → Karo across all instruction files (instructions/ashigaru.md, karo.md, gunshi.md, CLAUDE.md, all generated CLI variants) (Issue #121) Changed …View on GitHub ↗