A Claude Code plugin for cmux
One Orc session starts and closes its children as tabs. A status sidebar shows what each one is doing. A ⚠ marks every session that waits on you.
/plugin marketplace add yashMangal19/cmux-orc/plugin install cmux-orc@cmux-orc/cmux-orc:sessions-setupmacOS · cmux 0.64+ · python3 · MIT
A simulation of one cmux window. Nothing here runs Claude. Start a child, answer the ⚠, send a job.
Rows and colours follow orc-status.js. Tab titles and terminal output follow bin/orc.
An Orc is one Claude session that runs a team. Its workspace is one coloured, pinned tile in the left panel. Its children are tabs to the right of the Orc’s tab. The Orc starts, closes and reopens them, and its skill has it ask you before each new one.
A right-sidebar panel shows every child: status, how long it has been in that state, and its stage. Outside an Orc you see one row per Orc (“⚠ 1 need you · 4 working”) and every independent session.
When a session stops on a question or a permission prompt, its tab gets a ⚠ and the sidebar row turns red. The mark clears when you answer.
A job is a small Markdown file in an inbox. A hook shows each session its new jobs. A child works only through its Orc. Work between Orcs and independent sessions goes through one Sessions-Manager session.
| Piece | Where | What it does |
|---|---|---|
orc CLI | bin/orc | Drives cmux through its CLI (new-surface, rename-tab, workspace-action, …) and keeps the registry. |
| Hook | hooks/orc-hook.py | Inbox notices on SessionStart and UserPromptSubmit. ⚠ on AskUserQuestion and on permission or elicitation notifications; cleared on PostToolUse, UserPromptSubmit and Stop. |
| Sidebar | cmux/sidebars/orc-status.js | A cmux Custom Sidebar. Reads cmux’s live workspace and agent data. Stage and ⚠ reach it through tab titles, because a sidebar cannot read files. |
| Skills | skills/orc, skills/sessions-manager, skills/sessions-setup | The rules for each role, and the first-time setup command. |
Children talk to their Orc with Claude Code’s SendMessage. The spawn prompt tells each child its name, its Orc, and to report its stage.
/rename Shop-Orc
orc init Shop-Orcorc spawn QA --cwd ~/shop --brief "Run the checkout smoke cases"
orc list
orc close QA
orc resume QAorc stage "case 3/12"
orc job new --to Shop-QA --title "Smoke cases"
orc job set J-001 done "12/12 pass"python3 (standard library only)git, if you want orc close to check for uncommitted changesEach child is a full Claude Code session with its own context, so it uses tokens like any session you start yourself. That is why the orc skill tells the Orc to ask you before every orc spawn. Close children when their work is checked; orc resume brings one back if you need it again.
Yes. Tabs, workspace colours, pinning, the ⚠ mark and the sidebar all go through cmux. orc init, spawn, stage, close, resume and pane stop with not running inside a cmux terminal outside it. orc setup makes its links anywhere, but shows the panel only inside cmux. The job commands and orc list only read and write files.
“waiting” (orange) is cmux’s status for a session that finished its turn and is idle until you type. ⚠ (red) means the session stopped in the middle of its work on a question or a permission prompt, and nothing happens until you answer. Only ⚠ means a session is blocked on you.
No. cmux is a macOS app, and cmux-orc needs it. The CLI also uses fcntl file locks, which Windows does not have.
Yes. With the plugin installed, every session in cmux gets the ⚠ mark, and the sidebar’s Sessions overview lists independent sessions with their status. You can name one session Sessions-Manager and pass jobs between independent sessions. orc stage works only in an Orc tab or a child tab.
In ~/.agentic/sessions (set CLAUDE_ORC_HOME to move it): registry.json for Orcs and children, inbox/ for top-level jobs, orcs/<Name>/inbox/ for each team, state/ for the hook’s per-session notes. cmux-orc also reads cmux’s ~/.cmuxterm/claude-hook-sessions.json to map tabs to Claude sessions; it never writes it.
Yes. orc close saves the child’s Claude session id before it closes the tab, and orc resume <Role> opens a new tab with claude --resume <id>. orc close refuses while the child’s folder has uncommitted git changes or while the child waits on you.
Yes. Anything after -- goes to that child’s claude command: orc spawn Review -- --model opus. With no --, the child gets the Orc’s own flags, for example --permission-mode or --model and their values. Flags that belong to the Orc’s own session are left out: --name, --resume, --continue, --session-id, --worktree, --from-pr, --teleport, --cloud and --remote-control.
A cmux sidebar has no file access; it can read workspace and tab data only. orc stage "case 3/12" renames the tab to QA · case 3/12, and the sidebar splits the title back into name and stage. If you rename the tab by hand, the sidebar loses the stage until the next orc stage.
No. orc and the hook make no network calls. They run local cmux and git commands and read and write files under ~/.agentic/sessions. (Children are Claude sessions, so they talk to Claude as usual.)
cmux 0.64 has no button for Custom sidebars in the right sidebar’s mode bar. Run orc pane.
In Claude Code, /plugin uninstall cmux-orc@cmux-orc. Then remove the links that setup made, and the state if you no longer want it:
rm ~/.local/bin/orc ~/.config/cmux/sidebars/orc-status.js
rm -rf ~/.agentic/sessions # registry, inboxes and jobsWorkspace colours and pins are cmux settings; change them in cmux.