Cmux
- 6.3k installs
- 25.5k repo stars
- Updated August 4, 2026
- manaflow-ai/cmux
cmux is a Build skill that controls non-browser cmux topology and routing on macOS via CLI handle refs for windows, workspaces, panes, and surfaces.
About
The cmux skill teaches agents end-user control of non-browser cmux topology and routing on macOS. It maps the handle model from windows through workspaces, panes, and surfaces so automation can target deterministic placement without guessing layout state. Fast Start commands cover caller context via cmux identify --json, topology listing with list-windows, list-workspaces, list-panes, and list-pane-surfaces, plus create and focus flows such as new-workspace, new-split, move-surface, split-off, and reorder-surface. Attention cues use trigger-flash on a targeted surface. Settings guidance defers to cmux docs settings, edits ~/.config/cmux/cmux.json with timestamped backups, and reloads cmux plus Ghostty config through cmux reload-config without restarting the app. Terminal rendering stays in Ghostty config while cmux.json owns sidebar, notifications, browser behavior, and shortcuts. Cross-links point to handles-and-identify, windows-workspaces, panes-surfaces, trigger-flash-and-health, and sibling cmux-workspace, cmux-settings, cmux-browser, and cmux-markdown skills. Use when automation must navigate or rearrange a multi-pane cmux layout with stable refs like window:N and surface:N.
- Maps window, workspace, pane, and surface handles for deterministic cmux topology targeting
- Fast Start covers identify --json, list-* commands, new-split, move-surface, split-off, and reorder-surface
- trigger-flash provides attention cues on a specific surface without disrupting layout
- Settings workflow backs up cmux.json, edits user config, and reloads Ghostty plus cmux in place
- Cross-links sibling skills for workspace rules, settings, browser automation, and markdown panels
Cmux by the numbers
- 6,291 all-time installs (skills.sh)
- +423 installs in the week ending Aug 2, 2026 (Skillselion tracking)
- Ranked #31 of 550 CLI & Terminal skills by installs in the Skillselion catalog
- Security screen: LOW risk (skills.sh audit)
- Data as of Aug 4, 2026 (Skillselion catalog sync)
cmux capabilities & compatibility
Free local cmux CLI; requires macOS cmux installation.
- Capabilities
- cmux topology listing · surface move and reorder · caller identify context · config reload without restart · trigger flash attention cue
- Works with
- chrome
- Use cases
- orchestration · debugging
- Platforms
- macOS
- Runs
- Runs locally
- Pricing
- Free
What cmux says it does
End-user control of cmux topology and routing (windows, workspaces, panes/surfaces, focus, moves, reorder, identify, trigger flash).
Use this skill to control non-browser cmux topology and routing.
Default output uses short refs: `window:N`, `workspace:N`, `pane:N`, `surface:N`.
npx skills add https://github.com/manaflow-ai/cmux --skill cmuxAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 6.3k |
|---|---|
| repo stars | ★ 25.5k |
| Security audit | 3 / 3 scanners passed |
| Last updated | August 4, 2026 |
| Repository | manaflow-ai/cmux ↗ |
How do agents deterministically place, focus, and navigate surfaces inside a multi-pane cmux layout without manual UI clicks?
End-user control of cmux topology and routing for windows, workspaces, panes, surfaces, focus, moves, reorder, identify, and trigger flash.
Who is it for?
macOS cmux users running agent automation that must list topology, split panes, move surfaces, and reload cmux.json safely.
Skip if: Browser automation on cmux webviews, Windows or Linux terminals, or layout changes without reading cmux-workspace non-disruptive rules.
When should I use this skill?
Automation needs deterministic placement and navigation in a multi-pane cmux layout using identify, list, move-surface, reorder-surface, or trigger-flash.
What you get
Stable window:N and surface:N refs, focused panes, reordered surfaces, and flash cues driven through cmux identify, list, move, and reorder commands.
- JSON topology identification
- focused pane or surface placement
By the numbers
- Models four hierarchy levels: Window, Workspace, Pane, and Surface
- Provides cmux identify --json plus list-windows, list-workspaces, and list-panes CLI commands
Files
cmux Core Control
Use this skill to control non-browser cmux topology and routing.
Core Concepts
- Window: top-level macOS cmux window.
- Workspace: tab-like group within a window.
- Pane: split container in a workspace.
- Surface: a tab within a pane (terminal or browser panel).
Fast Start
# identify current caller context
cmux identify --json
# list topology
cmux list-windows
cmux list-workspaces
cmux list-panes
cmux list-pane-surfaces --pane pane:1
# create/focus/move
cmux new-workspace
cmux new-split right --panel pane:1
cmux move-surface --surface surface:7 --pane pane:2 --focus true
cmux split-off --surface surface:7 right
cmux reorder-surface --surface surface:7 --before surface:3
# attention cue
cmux trigger-flash --surface surface:7Settings and Docs
Use cmux docs settings before changing cmux-owned settings. It prints the docs URL, schema URL, raw GitHub resources, cmux.json paths, and reload command.
cmux docs settings
cmux settings pathcmux-owned settings live in ~/.config/cmux/cmux.json. Legacy ~/.config/cmux/settings.json and ~/Library/Application Support/com.cmuxterm.app/settings.json files are read only as fallback for missing keys. Before editing, copy any existing cmux.json file to a timestamped .bak next to it so the user can revert. Edit the user file, then reload:
cmux reload-configcmux reload-config reloads BOTH cmux.json and Ghostty config (~/.config/ghostty/config) and refreshes terminals in place. No app restart needed.
Use cmux settings for app behavior, sidebar, notifications, browser behavior, automation, workspace colors, and cmux-owned shortcuts. Terminal rendering settings such as font, cursor style, theme, scrollback, background transparency (background-opacity), and blur (background-blur) belong in Ghostty config at ~/.config/ghostty/config.
Open the UI when useful:
cmux settings
cmux settings cmux-json
cmux settings shortcutsHandle Model
- Default output uses short refs:
window:N,workspace:N,pane:N,surface:N. - UUIDs are still accepted as inputs.
- Request UUID output only when needed:
--id-format uuids|both.
Deep-Dive References
| Reference | When to Use |
|---|---|
| references/handles-and-identify.md | Handle syntax, self-identify, caller targeting |
| references/windows-workspaces.md | Window/workspace lifecycle and reorder/move |
| references/panes-surfaces.md | Splits, surfaces, move/reorder, focus routing |
| references/trigger-flash-and-health.md | Flash cue and surface health checks |
| ../cmux-workspace/SKILL.md | Current caller workspace rules and non-disruptive automation |
| ../cmux-settings/SKILL.md | Safe cmux.json settings edits and validation |
| ../cmux-browser/SKILL.md | Browser automation on surface-backed webviews |
| ../cmux-markdown/SKILL.md | Markdown viewer panel with live file watching |
interface:
display_name: "cmux Core"
short_description: "Control windows/workspaces/panes/surfaces and routing with cmux CLI."
default_prompt: "Use this skill to inspect and manipulate cmux topology: identify context, target handles, create/focus/move/reorder windows/workspaces/panes/surfaces, and use trigger-flash for visual confirmation."
Handles and Identify
Use identify and short handles for deterministic automation targeting.
Handle Inputs
Most v2-backed commands accept:
- UUID
- short ref (
window:N,workspace:N,pane:N,surface:N) - index (where legacy/index-based commands still allow it)
Self Identify
cmux identify --jsonReturns current focused topology plus optional caller resolution.
Caller Override
cmux identify --workspace workspace:2
cmux identify --workspace workspace:2 --surface surface:8Useful for agents that need to route relative actions from a known caller anchor.
Output Shaping
cmux --json identify # refs-first output
cmux --json --id-format both identify
cmux --json --id-format uuids identifyPanes and Surfaces
Split layout, surface creation, focus, move, and reorder.
Inspect
cmux list-panes
cmux list-pane-surfaces --pane pane:1Create Splits/Surfaces
cmux new-split right --panel pane:1
cmux new-surface --type terminal --pane pane:1
cmux new-surface --type browser --pane pane:1 --url https://example.comFocus and Close
cmux focus-pane --pane pane:2
cmux focus-panel --panel surface:7
cmux close-surface --surface surface:7Move/Reorder Surfaces
cmux move-surface --surface surface:7 --pane pane:2 --focus true
cmux move-surface --surface surface:7 --workspace workspace:2 --window window:1 --after surface:4
cmux split-off --surface surface:7 right
cmux reorder-surface --surface surface:7 --before surface:3Surface identity is stable across move/reorder/split-off operations. Layout commands are focus-neutral by default; pass --focus true only when you want the moved or created surface selected.
Trigger Flash and Surface Health
Operational checks useful in automation loops.
Trigger Flash
Flash a surface or workspace to provide visual confirmation in UI:
cmux trigger-flash --surface surface:7
cmux trigger-flash --workspace workspace:2Surface Health
Use health output to detect hidden/detached/non-windowed surfaces:
cmux surface-health
cmux surface-health --workspace workspace:2Use this before routing focused input if UI state may be stale.
Windows and Workspaces
Window/workspace lifecycle and ordering operations.
Inspect
cmux list-windows
cmux current-window
cmux list-workspaces
cmux current-workspaceCreate/Focus/Close
cmux new-window
cmux focus-window --window window:2
cmux close-window --window window:2
cmux new-workspace
cmux select-workspace --workspace workspace:4
cmux close-workspace --workspace workspace:4Reorder and Move
cmux reorder-workspace --workspace workspace:4 --before workspace:2
cmux move-workspace-to-window --workspace workspace:4 --window window:1Related skills
Lark SharedWire Feishu/Lark Open Platform auth, tokens, and shared API helpers into agent-built bots and internal tools.514k
Runcomfy CliLet their coding agent call any RunComfy model from the terminal or scripts without managing separate SDKs.298k30
Skills CliDiscover, install, update, and manage reusable agent capabilities from the open Skillselion ecosystem directly inside their coding agent.270k71TzstCreate, extract, list, and script `.tzst` / `.tar.zst` archives from the terminal with the right compression, streaming, and conflict flags.267k71XdropPull files from an Xdrop share URL, decrypt them locally, and land outputs in a chosen directory with optional JSON for automation.266k71
WizardAuthor interactive bash setup wizards that open URLs, capture secrets, write .env upserts, and set GitHub Actions secrets step by step.104k202kHow it compares
Pick cmux over generic shell skills when automation must navigate cmux-specific topology rather than run commands in a single default terminal.
FAQ
What cmux hierarchy levels does this skill control?
Windows, workspaces, panes, and surfaces, using short refs like window:N and surface:N for deterministic targeting.
How should agents reload cmux settings safely?
Back up ~/.config/cmux/cmux.json, edit the user file, then run cmux reload-config to refresh cmux and Ghostty without restarting the app.
When should trigger-flash be used?
Use cmux trigger-flash --surface surface:N as an attention cue on a specific surface after moves or focus changes.