What does this skill do, and when should you use it?
cmux-workspace is one of 25 skills bundled in the manaflow-ai/cmux repository. It teaches an agent how to locate and operate the cmux workspace that invoked it — cmux being a Ghostty-based native macOS terminal for AI coding agents. It defines a concept model (window, workspace, pane, surface, panel) and a default scoping rule: act only in the caller's workspace. The skill stresses non-disruptive automation — never call focus-changing commands speculatively, build layouts additively in one shot, and message other agents through `cmux agent message` rather than typing into their terminals. It depends on the cmux CLI, socket access, and CMUX_* environment variables.
- Reads CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, and CMUX_SOCKET_PATH env vars, falling back to
cmux identify --when they are missing - Creates panes and surfaces with one-shot additive commands (
cmux new-pane,cmux new-surface) instead of create-then-move-then-focus chains - Sends commands and keystrokes to the caller terminal via
cmux send/cmux send-key - Passes messages between agents with
cmux agent message/cmux agent inbox, delivered through agent hooks that wake idle Claude Code sessions - Updates sidebar state with
cmux set-status,set-progress, andlog, and moves surfaces withcmux move-surface --focus falsewithout stealing attention - Connects via the cmux-provided socket path and troubleshoots with
cmux capabilitiesandcmux ping
- A developer running multiple AI coding agents in parallel who needs an agent to start a dev server or browser preview in its own workspace without disturbing other tabs
- One agent needs to notify another (e.g. a fix landed on main, rebase when free) without typing into the terminal the human there is using
- Automation that needs a reusable helper pane to the right of the caller terminal for logs, TUIs, or browser checks, reusing existing panes instead of splitting endlessly
- cmux contributors testing runtime changes with tagged isolated reloads from a source checkout
- Users not on the cmux terminal — every command depends on the cmux CLI and its socket API and will not work in plain terminals, tmux, or other macOS terminals
- Non-macOS environments — cmux is macOS-only for now, so this skill is unusable elsewhere
How do you install this skill?
- The skill only applies on macOS with cmux installed; it is unusable in any other environment.
- Socket access can be configured open to all local processes; verify the socket permission mode before allowing agent automation.
- No skill-level version/changelog; command semantics may drift with cmux releases (--focus false is still expanding across verbs).
- Known papercut (drag-surface-to-split workspace resolution) requires report-and-stop per the skill; do not work around it by focusing.
- Static source review only; nothing was executed, so confidence is low.
- Shell / CLI
cmux app with CLI and socket APIcmux environment variables (CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, CMUX_SOCKET_PATH)
The skill ships in the manaflow-ai/cmux repository at skills/cmux-workspace/. The README does not document per-skill install commands; it only describes skills as a reusable workflow collection (with a separate cmux-skills collection and docs at https://cmux.com/docs/skills). To install the cmux app itself:
macOS (Homebrew)
brew tap manaflow-ai/cmux
brew install --cask cmuxmacOS (DMG)
Download cmux-macos.dmg from GitHub Releases and drag cmux into Applications.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- Open a browser pane on the right of my current workspace pointing at http://127.0.0.1:8765 without stealing focus
- Message the cmux-remote-status agent: the fix is on main, rebase when free
- Run npm test in the caller terminal and set sidebar progress to 40%
- Check if there's a helper pane to the right of this workspace and add a tab running logs inside it
The skill triggers whenever an agent running inside a cmux workspace is asked about workspaces, panes, surfaces, socket targeting, or non-interfering automation. Core flow: confirm the caller context with cmux identify --; act only in the caller workspace by default, passing explicit --workspace / --surface flags on mutating actions; never call focus-pane, focus-panel, or select-workspace; prefer --command or --url on creation and pass --focus false wherever supported:
cmux new-pane --workspace "${CMUX_WORKSPACE_ID}" --type browser --direction right --url "http://127.0.0.1:8765"
cmux send --surface "${CMUX_SURFACE_ID:-}" "git status\n"
cmux agent message cmux-remote-status "The relay fix is on main; rebase when free."If a CLI command rejects a valid surface: or pane: ref, report the bug and stop rather than working around it by focusing.
What are this skill's strengths and limitations?
- Clear scoping rules: anchored to the caller workspace by default, with explicit flags for auditable automation
- Thoughtful user-experience guarantees: no speculative focus changes, `--focus false` preferred, one-shot additive layout
- Agent-to-agent messaging goes through hooks, avoiding the serious failure mode of typing into a human's half-written prompt
- Documents known defects with issue numbers (e.g. the drag-surface-to-split focus-resolution bug), which helps debugging
- Tightly bound to the cmux ecosystem — useless outside the cmux app
- Repo license is flagged NOASSERTION; it is actually a hybrid of GPL-3.0-or-later and BUSL-1.1 for server components, so commercial use needs care
- No automated tests ship with the skill, and some CLI behavior depends on unfixed issues (e.g. #1901)
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| cmux Workspace Skill this page | 64 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux Core Control | 47 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Diagnostics | 51 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Shared Behavior Rules | 48 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux-browser: Browser Automation Skill for cmux | 60 · Recommended | ★ 28k | 1d ago | NOASSERTION |
cmux positions itself against tmux: tmux is a multiplexer that runs inside any terminal, while cmux is a native macOS app with vertical tabs, split panes, an embedded browser, and a socket API built in — no config files or prefix keys. This skill codifies automation norms on top of those cmux primitives.
How did FollowSkills review this skill?
The skill executes nothing itself, exfiltrates nothing, and accesses no sensitive data; core rules enforce least impact (no speculative focus/close in other workspaces, --focus false, no keystrokes into other workspaces, agent message instead of typing into terminals) plus stop-and-report rules on failure. Deducted because socket access can be configured open to all local processes without confirmation guidance, and attribution rests on an unverified publisher.
SKILL.md and references/commands.md are self-consistent, with fallbacks when env vars are missing (cmux identify --), capability probing (capabilities -- / ping), and disclosed known bugs with issue links. Deducted for the static-only basis: command behavior is unverified and some semantics (--command typing at spawn) depend on implementation not read.
Trigger conditions are explicit (cmux workspace, panes, surfaces, socket), scenarios clear (AI coding agents inside cmux), with declared boundaries (macOS-only, requires the cmux app). Deducted for narrow fit: unusable outside cmux; skill text is English with Chinese support only via translated READMEs; no mainland-China reachability risk since it is a local socket.
Good layered architecture: main SKILL.md with progressive disclosure, a full command reference, and agents/openai.yaml interface metadata; known limitations and versioned issue references are present; repository license is explicit (GPL-3.0-or-later, server-side BUSL-1.1). Deducted for no skill-level version/changelog, NOASSERTION registry license metadata, and maintenance/update path inferable only from repo context.
Core tasks (scoping automation to the caller workspace, additive layout building, agent-to-agent messaging) are covered by concrete copyable commands, exceeding manual guesswork; rules like additive layout and helper-pane reuse add real marginal value. Deducted because static review cannot confirm output usability and value only exists with cmux installed.
Claims are indirectly auditable via the command reference, linked known-issue reports, and the repository's real CI/test infrastructure, but no committed tests cover this skill's own key paths. Deducted for lack of third-party execution evidence of the skill's behavior and limited cross-source corroboration.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →