multi-agent-shogun workflow
Ten AI agents in tmux panes: a manager hands tasks to seven workers, progress shows on a dashboard, with Claude Code, Codex, Cursor and OpenCode supported
- 1,424 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Ten agents work autonomously: Claude Code starts with the `--dangerously-skip-permissions` flag, meaning no permission prompts
- The `first_setup.sh` script installs system packages through `sudo apt-get`, edits `~/.bashrc` and connects Memory MCP
- The ntfy topic name acts as a password: anyone who knows it can read notifications and send messages to the shogun
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add workflows/multi-agent-shogunDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Ten agents work autonomously: Claude Code starts with the `--dangerously-skip-permissions` flag, meaning no permission prompts
- The `first_setup.sh` script installs system packages through `sudo apt-get`, edits `~/.bashrc` and connects Memory MCP
- The ntfy topic name acts as a password: anyone who knows it can read notifications and send messages to the shogun
This is third-party code. Review the repository files before installing.
What it does
multi-agent-shogun is a set of shell scripts, YAML templates and instructions that starts ten AI agents in tmux panes and splits work among them. The `shutsujin_departure.sh` script creates two sessions: in `shogun` you type a task in plain words, and in `multiagent` the manager karo, seven workers ashigaru and the strategist gunshi do the work. Each agent is a separate instance of a console client: Claude Code, Codex, GitHub Copilot, Kimi Code, OpenCode, Cursor or Antigravity. The client type for each agent is set in `config/settings.yaml`. The chain works like this: the shogun takes your command and writes it to `queue/shogun_to_karo.yaml`, karo splits the task and hands pieces to workers, they run in parallel and return YAML reports, and karo gathers the result in `dashboard.md`. Agents exchange files on disk and tmux signals, so no model calls are spent on coordination. Instructions for each client are built from shared templates in the `instructions` folder by `scripts/build_instructions.sh` and turn into `CLAUDE.md`, `AGENTS.md`, Cursor rules and OpenCode agent definitions. There is also memory between sessions through Memory MCP in the `memory/shogun_memory.jsonl` file, phone notifications through ntfy, an Android app with an SSH terminal and an agent grid, and skill suggestions: workers flag recurring techniques and you decide which ones deserve a command of their own.
Who it is for. For developers on Linux, macOS or Windows with WSL2 who already use console AI clients and want to run several tasks in parallel from one window.
Good fit when
- A large task splits into independent parts and you want seven workers to take them at once
- You want to watch each agent in its own tmux pane and read their assignments and reports as plain YAML files
- You mix Claude Code, Codex, Cursor and OpenCode in one project and want their instructions kept in one source
- You need to give tasks from a phone: ntfy notifications and the Android app cover that
- You want agents to remember your preferences between sessions and propose recurring techniques as new commands
Not a fit when
- The task is small and sequential: ten sessions burn limits faster than a single agent finishes the job
- You work on Windows without WSL2: the system relies on tmux and bash, and the author offers only WSL2 with Ubuntu for Windows
- You need to confirm every agent action: the system is built for autonomous work without permission prompts
- You want a loosely coupled library for building your own agents: this is a ready hierarchy of roles configured through files
Example request
Split the task of building a REST API with authentication into independent parts and hand them to the seven workers, gather the result in dashboard.mdLimitations
- Windows needs WSL2 and Ubuntu, and `install.bat` sets them up. Linux and macOS require tmux and bash 4 or newer, and the `first_setup.sh` script offers to install a recent bash, coreutils and flock through brew. Node.js 20 or newer is needed for MCP servers.
- Each agent needs its own installed and authenticated console client. The author estimates eight Opus-grade agents on pay-per-token billing at over 100 dollars an hour and counts on subscriptions. The OpenAI and Anthropic APIs are unavailable from Russia.
- The phone app exists only for Android, there is no iOS version. Its voice input is tuned to recognize Japanese speech.
- The latest release, 5.1.0, came out in May 2026. In August the author wrote that he cut his own army of ten agents down to one and carried the ideas on in the kagemusha project.
- MIT license. The repository has a `tests` folder, and CI checks are declared for Ubuntu and macOS.
How to disable. Close the tmux sessions with `tmux kill-session -t shogun` and `tmux kill-session -t multiagent`. To remove the system, delete the cloned folder and the lines `first_setup.sh` added to `~/.bashrc`, and cancel the ntfy topic subscription in the app.
FAQ
How do I run several Claude Code sessions in parallel through tmux?
After `first_setup.sh`, run `bash shutsujin_departure.sh`. The script creates a `shogun` session for your commands and a `multiagent` session with karo, seven ashigaru and gunshi. Attach to `shogun`, type the task and read the result in `dashboard.md`.
How do I plug in Codex, Cursor or OpenCode instead of Claude Code?
Each agent's client is set in `config/settings.yaml` through `type`: claude, codex, copilot, kimi, opencode, cursor or antigravity. `scripts/build_instructions.sh` builds the instructions for them. OpenCode loads definitions from `.opencode/agents` with the `--agent` flag.
How do I get progress notifications on a phone?
Set `ntfy_topic` in `config/settings.yaml`, install the ntfy app and subscribe to the same topic. `shutsujin_departure.sh` starts the listener itself. When karo updates `dashboard.md`, the push goes out directly, and the shogun handles replies from the phone.
How do agents remember my preferences between sessions?
Memory MCP does that: `first_setup.sh` configures it and entries live in `memory/shogun_memory.jsonl`. According to the author, after `/clear` the agent loads your preferences from memory in about 700 tokens.
How do agents' work turn into new skills?
A worker that notices a recurring technique adds a `skill_candidate` field with a name and reason to its report. Karo collects such proposals in `dashboard.md`. If you approve, the command is created in `.claude/commands` and any agent can call it.
Discussion
No questions or reviews yet.
Related
Workflowsbotmux connects Lark and Feishu to Claude Code, Codex, Gemini CLI and OpenCode: each message starts its own agent session with live cards
A skill for messaging between Claude Code, Codex, Gemini CLI and other CLI agents through a shared local SQLite database, written in bash
A local dashboard for running many agents across machines: memory, code graph and agent-to-agent messaging
A Rust terminal task board: every task runs in its own git worktree and tmux window while Claude Code, Codex, Gemini CLI and other agents work in parallel
A portable .agent folder with memory, skills and protocols that plugs into many coding agents and keeps its knowledge when you switch tools
A Go terminal multiplexer with tiled panes that shows the state of Claude Code, Codex and other agents and gathers their requests in one list
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| multi-agent-shogun (this entry) | no | 1,424 | |
| CLI Agent Orchestrator | no | 1,465 | a supervisor hands tasks to specialists in tmux sessions, while this one has its own Japanese role hierarchy, dashboard and memory |
| Claude Squad | no | 8,656 | a terminal app for parallel sessions in tmux and git worktrees, with no manager and worker roles |
| Agent of Empires | no | 3,377 | a session manager with a web interface, with no role hierarchy and no task exchange through YAML |
README in short
The docs open with a six-command quick start and a hierarchy diagram, then compare the approach with other systems and explain why the author chose console clients over the API. Next come a table of supported clients, a section on skill suggestions, installation for Windows, Linux and macOS, the Android app and a walk through features: memory, notifications, task names on pane borders and a battle cry mode. The end holds the version history and settings. There is a Japanese version and the `docs`, `tests`, `templates` and `scripts` folders.