# Cmux

Control the cmux macOS terminal app: workspaces, panes, surfaces, browsers...

- Repository: https://github.com/davidondrej/skills (4238 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add davidondrej/skills --skill cmux -g -a claude-code -y`
Codex: `npx skills add davidondrej/skills --skill cmux -g -a codex -y`
Cursor: `npx skills add davidondrej/skills --skill cmux -g -a cursor -y`
Gemini CLI: `npx skills add davidondrej/skills --skill cmux -g -a gemini-cli -y`

## Description

Control the cmux macOS terminal app: workspaces, panes, surfaces, browsers, notifications, settings, and hooks. Use only when the user explicitly names cmux. Read before running any cmux command.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# cmux Control

macOS 14.0+. Prefer the CLI; if `cmux` is not on PATH, use `/Applications/cmux.app/Contents/Resources/bin/cmux`.

## Targeting and safety

**Window → workspace → pane → surface:** macOS window → sidebar project/branch tab → split region → terminal, browser, or Markdown tab.

- **Anchor to the caller's `CMUX_WORKSPACE_ID`.** Never assume the visually focused workspace is the target. Outside cmux, identify the intended workspace before acting.
- **Use prefixed refs or UUIDs.** `workspace:2`, `pane:1`, `surface:7`; bare numbers are indexes, not IDs. Output defaults to refs; `--id-format uuids|both` includes UUIDs.
- **Refresh targets.** Surface refs are global, not workspace-local. Re-list before reusing them; check `cmux surface-health` before sending input when state may be stale.
- **Preserve focus.** Pass `--focus false` wherever supported. Use `select-workspace`, `focus-pane`, `focus-panel`, or `focus-surface` only on explicit user request.
- **Respect ownership.** Never send input to surfaces you do not own. Stay in the caller's workspace unless the user explicitly requests cross-workspace routing.
- **Reuse one helper pane.** Use an existing non-caller helper pane or create one on the right. Create the intended layout directly with `new-pane --type … --focus false`.
- **Keep errors visible.** Never append `2>/dev/null`; stderr and exit status reveal invalid refs and flags.

## Inspect, read, and send

Check connectivity, identify the caller, and resolve the target pane to a surface. Replace example refs with those found in the current output.

```bash
cmux ping
cmux identify --json
cmux tree
cmux list-panes --workspace "$CMUX_WORKSPACE_ID"
cmux list-pane-surfaces --workspace "$CMUX_WORKSPACE_ID" --pane pane:1
cmux read-screen --surface surface:7 --lines 100
```

The rest: https://github.com/davidondrej/skills/blob/HEAD/skills/agent-orchestration/cmux/SKILL.md