Skill

using-cmux

Use when Claude Code is running inside a cmux session (CMUX_SOCKET_PATH is set) or the user asks to control cmux workspaces, panes, or surfaces — including sending text, reading screens, splitting and focusing panes, and the implementer-to-reviewer handoff where one pane writes code and another pane (Claude, Codex, Gemini CLI, etc.) reviews it. Trigger on mentions of cmux, "other pane", "review pane", "구현 pane", "리뷰 pane", "다른 pane", surface/workspace ids, or whenever the user starts composing `tmux` commands inside cmux so we can emit the cmux equivalent instead.

npx claudepluginhub giwonn/giwonn-plugins --plugin using-cmux

Tool Access

This skill uses the workspace's default tool permissions.

Preview

Control cmux (manaflow-ai/cmux) workspaces, panes, and surfaces from Claude Code, and coordinate multi-agent workflows across panes using message passing.

Supporting Assets

references/ai-orchestration.mdreferences/cli-cheatsheet.md

SKILL.md

Similar Skills

cache-components

139.2k

Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.

cache-components

mcp-builder

124.2k

Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).

9 files

anthropics-skills-13

canvas-design

124.2k

Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.

20 files

anthropics-skills-13

Stats

Stars0

Forks0

Last CommitApr 21, 2026

Actions

View Source View Plugin View on GitHub View README

using-cmux

Control cmux (manaflow-ai/cmux) workspaces, panes, and surfaces from Claude Code, and coordinate multi-agent workflows across panes using message passing.

cmux is a macOS-native Ghostty-based terminal. The cmux CLI (installed at /usr/local/bin/cmux) talks to the running app over a Unix socket.

1. Environment check (do this first)

Before any cmux command, confirm you are inside a cmux session:

echo "${CMUX_SOCKET_PATH:-NOT_IN_CMUX}"

Non-empty value: you are inside cmux. All commands below will work.
NOT_IN_CMUX or empty: you are outside cmux (plain terminal, SSH, CI). Every cmux command will fail. Tell the user explicitly and stop — do not silently fall back to tmux or guessing.

Other context variables cmux injects into each pane:

CMUX_WORKSPACE_ID — UUID of the current workspace
CMUX_SURFACE_ID — UUID of the current surface

When these are set, most cmux commands default to "me" if you omit --workspace / --surface.

2. Concept hierarchy

Window        (the macOS app window)
 └─ Workspace (sidebar tab; one project/context per workspace)
     └─ Pane  (split region within a workspace)
         └─ Surface (terminal or browser tab inside a pane)

Workspace: a vertical sidebar tab. Each has its own cwd, git branch, ports, etc.
Pane: a split region inside a workspace. ⌘D (split right) / ⌘⇧D (split down).
Surface: a tab within a pane; switch with ⌃1..⌃8.

Handle formats:

Refs (default): workspace:1, pane:2, surface:3, window:1
Index: zero-based integer
UUID: pass --id-format uuids (or both)

3. Core commands by category

3.1 Inspect — "where am I and what exists"

Purpose	Command
My context	`cmux identify`
Full tree	`cmux tree`
List workspaces	`cmux list-workspaces`
Current workspace	`cmux current-workspace`
List panes	`cmux list-panes`
List surfaces	`cmux list-panels`

Run cmux tree first whenever you need an id you don't already know. Do not hardcode ids — they change between sessions.

3.2 Create / move — "splits, tabs, focus"

Purpose	Command
New workspace	`cmux new-workspace --cwd ~/projects/x --command "npm run dev"`
Split right	`cmux new-split right`
Split down	`cmux new-split down --workspace workspace:1`
New surface (tab)	`cmux new-surface`
Focus a pane	`cmux focus-pane --pane pane:1`
Focus a surface	`cmux focus-panel --panel surface:2`
Resize pane	`cmux resize-pane --pane pane:1 -R 10`

3.3 Terminal I/O — "type into a pane, read its screen"

Purpose	Command
Send text	`cmux send --surface surface:2 "git status"`
Send a key	`cmux send-key --surface surface:2 enter`
Read screen	`cmux read-screen --surface surface:2 --lines 100`
Include scrollback	`cmux read-screen --surface surface:2 --scrollback`
Clear scrollback	`cmux clear-history --surface surface:2`

Newline caveat: cmux send "foo" only types foo into the input buffer — it does not press Enter. To execute, always call cmux send-key <surface> enter as a separate command. Treat the send + send-key pair as one unit.

3.4 Notify / status — "signal the user"

Purpose	Command
macOS notification	`cmux notify --title "Build done" --body "feature/x succeeded"`
Sidebar status	`cmux set-status build Running --icon clock`
Progress bar	`cmux set-progress 0.75 --label "Deploying"`
Log line	`cmux log "Server up" --level info --source api`

3.5 Browser automation — "drive the in-pane browser"

3.6 Miscellaneous

Purpose	Command
Check socket	`cmux ping`
Surface health	`cmux surface-health`
Refresh all surfaces	`cmux refresh-surfaces` — try this first if output looks frozen

4. tmux → cmux translations

Do not generate tmux commands inside cmux — they will not work.

tmux	cmux
`tmux split-window -h`	`cmux new-split right`
`tmux split-window -v`	`cmux new-split down`
`tmux send-keys -t 0 "cmd" Enter`	`cmux send --surface surface:0 "cmd"` then `cmux send-key --surface surface:0 enter`
`tmux capture-pane -p -t 0`	`cmux read-screen --surface surface:0`
`tmux select-pane -t 0`	`cmux focus-pane --pane pane:0`
`tmux new-session`	`cmux new-workspace`
`tmux list-panes`	`cmux list-panes`
`tmux kill-pane -t 0`	`cmux close-surface --surface surface:0`

5. Constraints and footguns

macOS GUI only. Over SSH, inside CI, or inside a tmux session on a remote box, CMUX_SOCKET_PATH is unset. Do not fall back — stop and tell the user.
send does not press Enter. Always pair with send-key ... enter.
Ids are session-scoped. Re-run cmux tree every time you need an id. Never hardcode.
Idle-state requirement. send only "executes" if the target pane is at a shell/agent prompt. If the pane is mid-task, the text sits in the buffer. Read the screen first; use send-key ... ctrl+c if you need to interrupt (only with user consent).
Omitting flags. Inside your own pane, CMUX_SURFACE_ID makes --surface optional. When targeting another pane, --surface is required.

6. Implementer ↔ Reviewer handoff (primary workflow)

Coordinate two panes running different AI agents via turn-based message passing. No polling. No automatic loops.

The five-step flow

Implementer pane: plan and write the code as usual.
Implementer → Reviewer: inject a review request with cmux send + cmux send-key enter, then end the turn.
Reviewer pane: after the review is done, inject a previously agreed completion signal back into the implementer pane (e.g., 리뷰했어. 확인해).
Implementer: on the next turn, recognize the signal, read the reviewer pane with read-screen, and present a feedback summary to the developer.
Developer: decides what to do next. Stop here. Do not auto-apply changes, do not auto-request another review.

Step 4 is a hard stop. The workflow resumes only when the developer explicitly says so ("apply it", "ask for another review", etc.).

For the full protocol — exact wording to put in the request, edge cases, signal conventions — read references/ai-orchestration.md.

7. Going deeper

If you need...	Read
Full CLI reference (every subcommand and flag)	`references/cli-cheatsheet.md`
Handoff protocol, signal conventions, failure modes	`references/ai-orchestration.md`

8. Slash commands this plugin ships

/cmux-here — summarize where you are (workspace / pane / surface) and list neighboring panes.
/cmux-ask <surface> <prompt> — inject a prompt into another pane and press Enter, in one step.