Shogun Multi-Agent Command
A tmux-based command hierarchy for running multiple coding CLIs on parallel development tasks.
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.sh
Reload 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.