Shogun Multi-Agent Command
A tmux-based command hierarchy for running multiple coding CLIs on parallel development tasks.
Per-dimension scores and reasoning
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.
- 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.
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.
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 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.
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.