multi-agent-shogun: a tmux-based agent hierarchy for Claude Code and six other CLIs

The problem multi-agent-shogun solves: eight coding agents without eight sets of API bills

Running several AI coding agents at once is easy to start and hard to pay for. The README frames the cost directly: it claims that running eight Opus-grade agents through per-token API access costs roughly $100+ per hour, while flat-rate CLI subscriptions land near $200 per month. That comparison is the project's whole reason for existing. If you already hold a Claude Code, Codex, Copilot, Kimi, OpenCode, Cursor or Antigravity subscription, the marginal cost of a seventh worker is zero, so the constraint shifts from money to coordination.

Coordination is the second problem. The README's comparison table argues that most multi-agent frameworks spend API calls on orchestration itself, and that Claude Code's own Task tool runs subagents sequentially inside one process. multi-agent-shogun instead writes instructions and reports to YAML files on disk and lets tmux carry the process model. The intended user is a developer who lives in a terminal, wants to see every agent's pane, and is willing to read files rather than a web UI. It is not aimed at someone who wants a hosted dashboard or a Python library to import.

Shogun, karo, ashigaru: how the tmux hierarchy actually moves work

The architecture is a three-level chain. You type an order into the Shogun pane. Shogun delegates to Karo, the manager. Karo breaks the order into tasks and distributes them to seven Ashigaru workers, with one Gunshi acting as strategist. The README's diagram shows eight independent agents below the manager: seven workers plus the strategist.

The transport between levels is YAML plus tmux, which the README calls zero coordination overhead. Each agent gets dedicated files rather than a shared queue, and the README describes the communication as event-driven with no polling. That choice has a concrete consequence: because every instruction and report is a plain file, you can read, diff and version-control the coordination layer itself. The trade-off is that you are now responsible for a filesystem convention. There is no message broker to replay history, and no schema migration path if the file layout changes between versions.

Release v5.1.0 is titled "Karo as Traffic Controller," which suggests the manager role was strengthened in that release, though the README does not spell out what changed mechanically. Treat the release title as a signal, not documentation.

Installing multi-agent-shogun and launching your first agent army

The README's Quick Start lists the requirements plainly: tmux, bash 4 or later, and at least one of the supported CLIs. There is no package to install from a registry; the repository is shell scripts plus a small Python dependency.

Clone the repository and run the one-time setup script, which the README says handles config, dependencies and MCP:

# clone and run one-time setup
git clone https://github.com/yohey-w/multi-agent-shogun
cd multi-agent-shogun
bash first_setup.sh
source ~/.bashrc

After sourcing your shell profile to pick up PATH changes, the README instructs a first run of Claude Code with a specific flag, purely to complete OAuth and accept the Bypass Permissions prompt:

# first run only: OAuth + accept Bypass Permissions, then /exit
claude --dangerously-skip-permissions

Once that is done, launch the agents:

bash shutsujin_departure.sh

What you should see is a tmux session with the Shogun pane plus the Karo and Ashigaru panes. The README's example order is a natural-language request typed into the Shogun pane: "Build a REST API for user authentication." Shogun delegates, Karo breaks it down, and the seven Ashigaru execute in parallel while you watch the dashboard. The repository also ships install.bat for Windows, and the README points to a full install section that covers Windows separately.

If you want to develop against the project rather than just run it, the Makefile exposes test targets. They require bats, which the Makefile installs through its own target:

make install-deps   # installs bats and helpers
make test           # runs root-level and unit bats tests

The Makefile also documents make lint for shellcheck over lib/ and scripts/, and make check as the CI-equivalent build plus diff check.

Where multi-agent-shogun breaks down

The most important limitation is stated by the project itself, in a note at the top of the README: the author disbanded his own ten-agent army down to a single agent and moved to a successor project called kagemusha, which ships a judgment loop of corrections, principles and standing rules rather than agents. The README says multi-agent-shogun continues to work as-is. That is a candid disclosure, and it should shape how you read everything else. A project whose original author has publicly stepped back from the pattern it implements is not a project where you should expect the design to keep expanding in the same direction.

The second limitation is environmental. Everything runs through tmux, so there is no headless mode described in the README and no path to running this inside a CI job or a container without a terminal multiplexer. If your deployment target is a managed platform, this is the wrong tool.

The third is the permission model. The Quick Start tells you to launch Claude Code with --dangerously-skip-permissions to accept Bypass Permissions. That is a deliberate choice for a system that needs eight unattended agents to act without prompting, but it means the agents run without per-action confirmation. The README does not document a sandboxing layer around that flag, and it does not describe rollback behaviour for a bad batch of agent actions.

Finally, the coordination layer is files on disk. The README presents this as transparency, and it is, but it also means there is no transactional guarantee across agents. Nothing in the README describes conflict resolution when two Ashigaru touch the same file.

multi-agent-shogun compared with LangGraph and CrewAI

The README's own comparison table places multi-agent-shogun against Claude Code's Task tool, Claude Code Agent Teams, LangGraph and CrewAI. The differences it draws are architectural rather than feature-level.

LangGraph is a graph-based state machine that runs on any LLM API and, per the README, requires Postgres or Redis infrastructure for coordination and integrates with LangSmith for observability. CrewAI is role-based agents with a pip install and OpenTelemetry observability, and the README describes its parallelism as limited and its coordination cost as API plus the CrewAI platform. Both are libraries you embed in an application you write.

multi-agent-shogun is the opposite shape. It is not a library; it is a set of shell scripts that spawn CLI processes in tmux panes. You do not write orchestration code, you type an order. The README claims zero coordination cost because the only API calls are for actual work, and eight independent agents rather than parallel nodes in a graph. The honest framing is that this is a trade of programmability for immediacy. If you need to embed agent orchestration into a product, or to reproduce a run deterministically in a test suite, a graph library is the better fit. If you want eight CLI subscriptions working on your backlog while you watch, this is the tool.

Licence, maintenance and what an upgrade costs you

The project is MIT licensed, which the README states in a badge and the repository carries as a LICENSE file. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and permission notice are preserved. That is the general shape of the licence, not legal advice; read LICENSE and, for anything consequential, ask a lawyer.

The maintenance picture is mixed and that is worth stating plainly. The last push to the default branch was on 2026-08-06, roughly six weeks before this writing, so the repository is not dormant. But the README's own note says the author moved on to kagemusha, and the release cadence is uneven: v5.0.0 and v5.1.0 landed two days apart in May 2026, then v4.6.0 in April, and the most recent release listed is v5.1.0 from 2026-05-23. There is no release after that in the README's release list.

Upgrade cost is where the file-based design bites. Because coordination state lives in YAML files and per-agent directories, and because the repository ships a Makefile target that rebuilds instruction files, an upgrade can change the shape of the files your agents read. The Makefile documents make check as a build plus diff check, which is the repository's own way of catching instruction drift. A team running this in production should treat the instructions/ directory as generated output and re-run that check after pulling, rather than hand-editing instruction files and hoping a version bump leaves them alone.

Editorial conclusion

Adopt multi-agent-shogun if you already pay for flat-rate CLI subscriptions, work in tmux, and want to read every instruction and report as a YAML file rather than through a hosted dashboard. Do not adopt it if you need per-token API billing, a non-tmux environment, or a project whose upstream author is still expanding it: the README states the author disbanded his own ten-agent army and moved to a successor project called kagemusha, while this repository continues to work as-is. Before committing, verify that first_setup.sh completes on your machine, that your CLI of choice is one of the seven listed, and that the Bypass Permissions prompt described in the Quick Start is acceptable in your environment.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. yohey-w/multi-agent-shogun on GitHub