multi-agent-shogun: A tmux Feudal Hierarchy for Parallel Claude Code Agents

The coordination tax that multi-agent-shogun is built to avoid

Running several AI coding agents at once is easy. Getting them to agree on who does what is not. Most multi-agent frameworks pay for that agreement with API calls: a planner model decomposes the task, worker models report back, and the orchestrator spends tokens reading those reports. multi-agent-shogun takes a different position. The README states that agents talk through YAML files on disk, and that the only API calls are for actual work rather than orchestration. Coordination is a file write and a tmux send, not a model inference.

The intended user is someone who already runs Claude Code or a similar CLI in a terminal and wants more throughput without writing a framework. The README's stated entry point is a single command typed into the Shogun pane, such as building a REST API for user authentication, after which Shogun delegates, Karo breaks the work down, and seven Ashigaru execute in parallel. The author frames this as a way to use flat-rate CLI subscriptions at full tilt rather than metering API tokens.

How the Shogun, Karo and Ashigaru chain actually moves work

The hierarchy has three named layers. You sit above all of them. Shogun receives your command and delegates. Karo distributes tasks to workers. Below Karo sit seven Ashigaru plus one Gunshi, a strategist role that the README lists alongside the workers rather than above them. The README's own diagram shows the flow as YAML plus tmux, which is the whole transport in two words.

Each agent runs in its own tmux pane, and the README says each agent has dedicated files rather than a shared queue. Communication is described as event-driven with no polling, which matters because polling would burn model calls on empty checks. Because the instructions and reports are plain YAML, they can be read, diffed and version-controlled, which the README lists as a deliberate contrast to systems where the orchestration state lives inside a process you cannot inspect.

The release history shows this layer is still moving. v5.1.0 is titled Karo as Traffic Controller, which suggests the manager role was reworked to gate or sequence worker traffic rather than simply forward tasks. v5.0.0 added OpenCode as a first-class option. The README does not spell out the v5.1.0 routing rules in the material available, so treat the exact traffic-control behaviour as something to read from the repository before relying on it.

Getting eight panes running from a clean clone

The documented path is short and assumes a Unix shell. Requirements are tmux, bash 4 or later, and at least one supported CLI: Claude Code, Codex, Copilot, Kimi, OpenCode or Antigravity. The README's quick start clones the repository, changes into it, and runs three commands in sequence. First, bash first_setup.sh performs one-time setup covering configuration, dependencies and MCP. Then source ~/.bashrc reloads PATH. Then, for the first run only, claude --dangerously-skip-permissions is invoked so you can complete OAuth and accept Bypass Permissions before exiting. Finally, bash shutsujin_departure.sh launches all agents.

That --dangerously-skip-permissions flag is not incidental. The system depends on CLI sessions that will act without interactive confirmation, because a pane waiting on a permission prompt is a stalled worker. The README treats this as a first-run step rather than a permanent setting, but the implication is that the agents operate with broad file and command access inside whatever working directory you launch them in.

The README also mentions a dashboard for real-time progress and a Memory MCP component for preferences that persist across sessions, and says full install steps including Windows are covered further down in the document. The supplied excerpt does not include those Windows instructions, so I cannot describe them here.

Where the design breaks down

The most direct limitation is stated by the author, not by a critic. A note at the top of the README records that in August 2026 the author disbanded his own ten-agent army down to a single agent carrying his judgment, and that the successor project, kagemusha, ships the forms of a judgment loop rather than the agents. multi-agent-shogun continues to work as-is. That is an unusual thing to find in a project's own README, and it is more informative than any benchmark would be: the person who built the hierarchy concluded that the hierarchy itself was not where the value sat.

The second limitation is environmental. This is a shell and tmux system. There is no library to import, no Python package, no programmatic API. If your workflow lives in a notebook, a CI runner without a persistent terminal multiplexer, or an editor extension, the architecture does not meet you there. The README's comparison table lists setup as shell scripts, and that is accurate in both directions: no infrastructure to stand up, and no abstraction to build on.

The third is cost shape. The README argues that eight Opus-grade agents through per-token API pricing runs about $100 or more per hour, against roughly $200 per month on a flat-rate CLI subscription. Those figures come from the README and should be treated as the author's estimate, not a measured result. The point that survives regardless of the exact numbers is that the economics only work if you are on a subscription. On metered API access, running eight agents multiplies your bill by eight and the coordination savings do not offset it.

How it differs from a graph framework like LangGraph

LangGraph is the obvious comparison because it occupies the same conceptual slot: multiple agents, one task, some notion of control flow. The approach is opposite. LangGraph models the system as a state machine over a graph, with nodes and edges defined in Python code, and the README's comparison table lists its coordination cost as API plus infrastructure, naming Postgres and Redis. State lives in that infrastructure, and the framework gives you typed transitions and checkpointing in exchange.

multi-agent-shogun has no database and no graph definition. The control flow is a fixed three-level chain that you do not get to reshape per task, and the state is YAML on disk plus whatever is visible in the panes. You give up resumable checkpoints, conditional edges and programmatic introspection. You gain the ability to open a pane and watch an agent work, and to read the exact instruction it was given as a file.

The README also positions the project against Claude Code's built-in Task tool and Agent Teams, describing Task as sequential and Agent Teams as token-heavy because each teammate carries a separate context. Those are claims about other tools made in a comparison table; verify them against current Anthropic documentation rather than taking the table as settled. The multi-CLI row is the one claim that is easy to check yourself, since the repository's scripts either reference seven CLIs or they do not.

Maintenance, upgrades and the MIT licence

The project is Shell, MIT-licensed, not archived, and last pushed in August 2026. Releases arrive as tagged versions with descriptive names: v4.6.0 in April 2026, v5.0.0 in May 2026, v5.1.0 later the same month. The jump from 4.x to 5.x within roughly a month of each other, and the fact that v5.0.0's headline is a new CLI integration, tells you the surface area is still expanding rather than settling.

Upgrade cost is the practical question. Because the orchestration state is YAML on disk and the runtime is tmux, a version bump can change file formats or pane layout in ways that break a running session. There is no documented migration script in the material provided, and no compatibility statement about whether YAML written by v4.6.0 is read by v5.1.0. If you version-control your agent instruction files, as the README suggests is possible, you have a diff to inspect after each upgrade. If you do not, an upgrade is a leap.

The MIT licence permits commercial use, modification and redistribution with the licence and copyright notice retained. It provides no warranty, and the first-run step that accepts Bypass Permissions means the agents act without confirmation prompts. Whether that is acceptable in a given repository, and what the CLI vendors' own terms say about automated or parallel use of their subscriptions, is a question for you and possibly a lawyer. Nothing here is legal advice.

Who should run this, and what to check first

The fit is narrow and clear. You should consider multi-agent-shogun if you work in a terminal all day, already have tmux muscle memory, hold a flat-rate subscription to at least one supported CLI, and want parallel execution with visible panes rather than a framework to program against. The appeal is that the coordination layer is inspectable: you can cat the YAML an Ashigaru received and see exactly what it was told.

You should not adopt it if you need a library, if your environment is Windows without a Unix shell, if you are billed per token, or if you want a system whose architecture its own author still stands behind at full scale. That last point is not a criticism of the code. It is the most useful signal in the repository.

Before committing, do three things. Run bash first_setup.sh in a scratch clone and read what it installs and what MCP configuration it writes, rather than accepting the defaults blind. Confirm that shutsujin_departure.sh launches the CLI you actually intend to use, since v5.0.0's headline change was adding OpenCode and the launch path may assume a default. And read the linked kagemusha article before deciding how many agents you need, because the author's own answer to that question changed from ten to one.

Editorial conclusion

Adopt multi-agent-shogun if you already live in tmux, hold a flat-rate CLI subscription, and want eight visible agent panes with instructions and reports you can read and diff as YAML. Do not adopt it if you need a Python library, a Windows-native setup, or a guarantee that the author's own configuration still runs the way it did at v5.1.0. Before committing, verify the tool versions first_setup.sh checks for, confirm the MCP registration it writes, and read the kagemusha article to understand why the author cut his own ten-agent army down to one.

Official sources

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