cmux

Use this skill when managing cmux terminal panes, surfaces, and workspaces from Claude Code or any AI agent. Triggers on spawning split panes for sub-agents, sending commands to terminal surfaces, reading screen output, creating/closing workspaces, browser automation via cmux, and any task requiring multi-pane terminal orchestration. Also triggers on "cmux", "split pane", "new-pane", "read-screen", "send command to pane", or subagent-driven development requiring isolated terminal surfaces.

What is cmux?

Overview Files

cmux

cmux is a production-ready AI agent skill for claude-code. Managing cmux terminal panes, surfaces, and workspaces from Claude Code or any AI agent.

Quick Facts

Field	Value
Category	developer-tools
Version	0.1.0
Platforms	claude-code
License	MIT

How to Install

Make sure you have Node.js installed on your machine.
Run the following command in your terminal:

npx skills add AbsolutelySkilled/AbsolutelySkilled --skill cmux

The cmux skill is now available in your AI coding agent (Claude Code, Gemini CLI, OpenAI Codex, etc.).

Overview

cmux is a terminal multiplexer controlled via a Unix socket CLI. It manages windows, workspaces, panes, and surfaces. AI agents use it to spawn isolated terminal panes for parallel tasks, send commands, read output, and clean up when done.

All commands use cmux [--json] <command> [options]. Always pass --json when parsing output programmatically. References use short refs like pane:5, surface:12, workspace:3 - or UUIDs.

Platforms

claude-code

Related Skills

Pair cmux with these complementary skills:

Frequently Asked Questions

What is cmux?

How do I install cmux?

Run npx skills add AbsolutelySkilled/AbsolutelySkilled --skill cmux in your terminal. The skill will be immediately available in your AI coding agent.

What AI agents support cmux?

This skill works with claude-code. Install it once and use it across any supported AI coding agent.

Maintainers

@maddhruv

Generated from AbsolutelySkilled

SKILL.md

cmux

All commands use cmux [--json] <command> [options]. Always pass --json when parsing output programmatically. References use short refs like pane:5, surface:12, workspace:3 - or UUIDs.

When to use this skill

Trigger this skill when the user or agent needs to:

Spawn split panes for sub-agent tasks or parallel work
Send commands or keystrokes to a specific terminal surface
Read screen content from a pane/surface
Create, list, close, or manage workspaces
Open browser surfaces alongside terminal panes
Orchestrate multi-pane layouts for subagent-driven development
Rename, reorder, or move surfaces/panes between workspaces

Do NOT trigger this skill for:

General shell scripting unrelated to cmux
tmux or screen commands (cmux has its own protocol)

Environment variables

cmux auto-sets these in every terminal it creates:

Variable	Purpose
`CMUX_WORKSPACE_ID`	Default `--workspace` for all commands
`CMUX_SURFACE_ID`	Default `--surface` for commands
`CMUX_TAB_ID`	Default `--tab` for tab-action/rename-tab
`CMUX_SOCKET_PATH`	Override socket path (default: `/tmp/cmux.sock`)

These mean most commands work without explicit IDs when run inside cmux.

Core concepts

Window - a top-level OS window. Most users have one. List with cmux list-windows.

Workspace - a tab within a window. Each workspace has its own pane layout. Create with cmux new-workspace, select with cmux select-workspace.

Pane - a rectangular split region within a workspace. A pane contains one or more surfaces (tabs). Create with cmux new-pane --direction <dir>.

Surface - the actual terminal (or browser) instance inside a pane. Each surface has a ref like surface:42. This is what you send commands to and read output from.

Ref format - short refs like pane:5, surface:12, workspace:3. Pass --id-format uuids for UUID output, --id-format both for both.

Common tasks

Identify current context

cmux --json identify

Returns caller's surface_ref, pane_ref, workspace_ref, window_ref. Use this to know where you are before creating splits.

Create a split pane (most common for subagents)

# Split right (vertical split, new pane on right)
cmux --json new-pane --direction right

# Split down (horizontal split, new pane below)
cmux --json new-pane --direction down

# Split in a specific workspace
cmux --json new-pane --direction right --workspace workspace:3

Returns the new pane's ref and its surface ref. Save the surface ref to send commands to it later.

Send a command to a surface

# Send text (does NOT press Enter)
cmux send --surface surface:42 "npm test"

# Send text + Enter (press Enter after)
cmux send --surface surface:42 "npm test"
cmux send-key --surface surface:42 Enter

# Or combine in one shell call
cmux send --surface surface:42 "npm test" && cmux send-key --surface surface:42 Enter

Read screen output from a surface

# Current visible screen
cmux read-screen --surface surface:42

# Include scrollback buffer
cmux read-screen --surface surface:42 --scrollback

# Last N lines
cmux read-screen --surface surface:42 --lines 50

Close a surface (clean up after subagent)

cmux close-surface --surface surface:42

List panes in current workspace

cmux --json list-panes

List surfaces in a pane

cmux --json list-pane-surfaces --pane pane:5

Focus a specific pane

cmux focus-pane --pane pane:5

Subagent workflow pattern

The primary use case for AI agents. Spawn panes, run tasks, read results, clean up.

# 1. Identify where we are
CALLER=$(cmux --json identify)

# 2. Create a split pane for the subagent task
RESULT=$(cmux --json new-pane --direction right)
# Parse the surface ref from RESULT

# 3. Send command to the new surface
cmux send --surface <new-surface-ref> "cd /path/to/project && npm test"
cmux send-key --surface <new-surface-ref> Enter

# 4. Wait, then read the output
cmux read-screen --surface <new-surface-ref> --scrollback --lines 100

# 5. Clean up when done
cmux close-surface --surface <new-surface-ref>

For parallel subagents, repeat steps 2-5 for each task, using different directions (right, down) to create a grid layout.

Workspace management

# List all workspaces
cmux --json list-workspaces

# Create a new workspace
cmux --json new-workspace

# Create workspace with a startup command
cmux new-workspace --command "cd ~/project && code ."

# Select/switch to a workspace
cmux select-workspace --workspace workspace:3

# Rename a workspace
cmux rename-workspace --workspace workspace:3 "My Task"

# Close a workspace
cmux close-workspace --workspace workspace:3

# Get current workspace
cmux --json current-workspace

Sending keystrokes

# Common keys
cmux send-key --surface surface:42 Enter
cmux send-key --surface surface:42 Escape
cmux send-key --surface surface:42 Tab
cmux send-key --surface surface:42 "ctrl+c"
cmux send-key --surface surface:42 "ctrl+d"
cmux send-key --surface surface:42 Up
cmux send-key --surface surface:42 Down

Notifications

cmux notify --title "Task Complete" --body "All tests passed"
cmux notify --title "Error" --subtitle "Build failed" --body "See surface:42"

Error handling

Error	Cause	Resolution
Socket not found	cmux app not running or socket path wrong	Start cmux app or check `CMUX_SOCKET_PATH`
Surface not found	Surface was closed or ref is stale	Re-list surfaces with `cmux --json list-panes`
Workspace not found	Workspace was closed	Re-list with `cmux --json list-workspaces`
Auth failed	Socket password mismatch	Set `CMUX_SOCKET_PASSWORD` or use `--password`

Gotchas

Stale surface refs after workspace close - If a workspace is closed (by the user or another agent), all surface refs from that workspace become invalid. Subsequent commands using those refs return "Surface not found". Always re-list with cmux --json list-panes before sending commands to a surface that was created more than a few minutes ago.
send does not press Enter - cmux send --surface <ref> "command" types the text but does not execute it. You must follow with cmux send-key --surface <ref> Enter. Missing this step leaves commands typed but not run, causing read-screen to show input but no output.
read-screen without --scrollback misses completed output - Once a long-running command finishes and its output scrolls off the visible terminal area, read-screen without --scrollback returns only what's currently visible - potentially just a shell prompt. Always use --scrollback when reading the result of a command that may have produced more output than one screen.
Socket path mismatch in nested environments - When running cmux commands from inside a cmux-spawned terminal, the CMUX_SOCKET_PATH env var is set automatically. But if you spawn a subshell or use sudo, the variable may not propagate. Always pass --socket-path explicitly or verify the env var is inherited when running cmux from non-standard shell contexts.
Closing the wrong surface - cmux close-surface closes the surface (terminal tab), not the pane. To remove a pane from the layout entirely, close all surfaces in it first, then the pane collapses. Calling close-surface on the wrong ref silently removes a still-needed terminal - always verify the ref with cmux --json list-pane-surfaces before closing.

References

For detailed content on specific cmux sub-domains, read the relevant file from the references/ folder:

references/pane-management.md - advanced pane operations: resize, swap, break, join, drag-to-split, panels
references/browser-automation.md - opening browser surfaces, navigating, snapshots, clicking, filling forms, evaluating JS
references/subagent-workflows.md - complete patterns for multi-agent orchestration, parallel task execution, output polling, cleanup strategies

Only load a references file if the current task requires it - they are long and will consume context.

References

browser-automation.md

Browser Automation

cmux can open browser surfaces alongside terminals and control them via CLI.

Open a browser surface

# Open browser split in caller's workspace
cmux browser open "https://example.com"

# Open as a split (explicit)
cmux browser open-split "https://example.com"

# Open browser in a specific pane
cmux --json new-surface --type browser --pane pane:5 --url "https://example.com"

# Open browser in a new pane (split)
cmux --json new-pane --type browser --direction right --url "https://example.com"

Navigation

# Navigate to URL
cmux browser navigate "https://example.com" --snapshot-after

# Back, forward, reload
cmux browser back --snapshot-after
cmux browser forward --snapshot-after
cmux browser reload --snapshot-after

# Get current URL
cmux browser url
# or
cmux browser get url

Use --snapshot-after to get an accessibility snapshot of the page after the action.

Page snapshots (accessibility tree)

# Default snapshot
cmux browser snapshot

# Interactive snapshot (includes clickable refs)
cmux browser snapshot --interactive

# Compact output
cmux browser snapshot --compact

# Snapshot a specific CSS selector
cmux browser snapshot --selector "#main-content"

# Limit depth
cmux browser snapshot --max-depth 3

The snapshot returns an accessibility tree representation - ideal for AI agents to understand page structure without screenshots.

Interactions

Click, hover, focus

cmux browser click "button.submit" --snapshot-after
cmux browser dblclick "#item" --snapshot-after
cmux browser hover ".menu-trigger" --snapshot-after
cmux browser focus "#search-input" --snapshot-after

Type and fill

# Type into a focused element (simulates keystrokes)
cmux browser type "#search" "hello world" --snapshot-after

# Fill a field (sets value directly, faster)
cmux browser fill "#email" "user@example.com" --snapshot-after

# Clear a field
cmux browser fill "#email" "" --snapshot-after

Keyboard

cmux browser press Enter --snapshot-after
cmux browser press "Control+a" --snapshot-after
cmux browser keydown Shift
cmux browser keyup Shift

Select dropdowns

cmux browser select "#country" "US" --snapshot-after

Checkboxes

cmux browser check "#agree-terms" --snapshot-after
cmux browser uncheck "#newsletter" --snapshot-after

Scroll

# Scroll page down by 500px
cmux browser scroll --dy 500 --snapshot-after

# Scroll a specific element
cmux browser scroll --selector ".content" --dy 300 --snapshot-after

Wait for conditions

# Wait for element to appear
cmux browser wait --selector "#loaded"

# Wait for text on page
cmux browser wait --text "Success"

# Wait for URL change
cmux browser wait --url-contains "/dashboard"

# Wait for page load
cmux browser wait --load-state complete

# Custom JS condition
cmux browser wait --function "() => document.querySelectorAll('.item').length > 5"

# With timeout
cmux browser wait --selector "#loaded" --timeout-ms 10000

Get page data

cmux browser get title
cmux browser get text                    # full page text
cmux browser get html                    # full page HTML
cmux browser get value "#input-field"    # input value
cmux browser get attr "#link" href       # element attribute
cmux browser get count ".items"          # count matching elements
cmux browser get box "#element"          # bounding box
cmux browser get styles "#element"       # computed styles

Evaluate JavaScript

cmux browser eval "document.title"
cmux browser eval "document.querySelectorAll('.item').length"
cmux browser eval "window.scrollTo(0, document.body.scrollHeight)"

Find elements (Playwright-style locators)

cmux browser find role button
cmux browser find text "Submit"
cmux browser find label "Email"
cmux browser find placeholder "Search..."
cmux browser find testid "submit-btn"
cmux browser find first ".item"
cmux browser find last ".item"
cmux browser find nth ".item" 3

Element state checks

cmux browser is visible "#modal"
cmux browser is enabled "#submit-btn"
cmux browser is checked "#checkbox"

Tabs

cmux browser tab list
cmux browser tab new "https://example.com"
cmux browser tab switch 1
cmux browser tab close 2

Console and errors

cmux browser console list
cmux browser console clear
cmux browser errors list
cmux browser errors clear

Cookies and storage

cmux browser cookies get
cmux browser cookies set '{"name":"token","value":"abc123"}'
cmux browser cookies clear

cmux browser storage local get "myKey"
cmux browser storage local set "myKey" "myValue"
cmux browser storage session clear

Advanced

# Set viewport size
cmux browser viewport 1280 720

# Handle dialogs (alert, confirm, prompt)
cmux browser dialog accept
cmux browser dialog dismiss "cancel text"

# Highlight an element (visual debugging)
cmux browser highlight ".target-element"

# Save/load browser state
cmux browser state save /tmp/browser-state.json
cmux browser state load /tmp/browser-state.json

# Add custom script or styles
cmux browser addscript "console.log('injected')"
cmux browser addstyle "body { background: red; }"

# Identify which surface the browser is in
cmux browser identify --surface surface:42

pane-management.md

Pane Management

Advanced pane operations beyond basic create/close.

Resize panes

# Resize pane left by 10 cells
cmux resize-pane --pane pane:5 -L --amount 10

# Resize pane right, up, down
cmux resize-pane --pane pane:5 -R --amount 5
cmux resize-pane --pane pane:5 -U --amount 3
cmux resize-pane --pane pane:5 -D --amount 3

Direction flags: -L (left), -R (right), -U (up), -D (down). --amount defaults to 1 if omitted.

Swap panes

cmux swap-pane --pane pane:5 --target-pane pane:8

Swaps the positions of two panes within the same workspace.

Break pane (promote to workspace)

# Break surface out of current pane into a new workspace
cmux break-pane --surface surface:42

# Break without focusing the new workspace
cmux break-pane --surface surface:42 --no-focus

Join pane (merge into another)

# Move current surface into target pane
cmux join-pane --target-pane pane:8

# Join specific surface into target, without focusing
cmux join-pane --target-pane pane:8 --surface surface:42 --no-focus

Drag surface to split

# Drag a surface to create a new split in a direction
cmux drag-surface-to-split --surface surface:42 right
cmux drag-surface-to-split --surface surface:42 down

Move surface between panes

# Move surface to a different pane
cmux move-surface --surface surface:42 --pane pane:8

# Move to specific index within the pane
cmux move-surface --surface surface:42 --pane pane:8 --index 0

# Move before/after another surface
cmux move-surface --surface surface:42 --before surface:50
cmux move-surface --surface surface:42 --after surface:50

# Move and focus
cmux move-surface --surface surface:42 --pane pane:8 --focus true

Reorder surfaces within a pane

cmux reorder-surface --surface surface:42 --index 0
cmux reorder-surface --surface surface:42 --before surface:50
cmux reorder-surface --surface surface:42 --after surface:50

Multiple surfaces per pane (tabs)

A pane can hold multiple surfaces as tabs. Create additional surfaces in an existing pane:

# Add a new terminal tab to an existing pane
cmux --json new-surface --type terminal --pane pane:5

# Add a browser tab to an existing pane
cmux --json new-surface --type browser --pane pane:5 --url "https://example.com"

List panels

Panels are a separate concept from panes - they are sidebar/auxiliary views.

cmux --json list-panels
cmux focus-panel --panel panel:1
cmux send-panel --panel panel:1 "some text"
cmux send-key-panel --panel panel:1 Enter

Respawn a surface

Kill and restart the process in a surface:

cmux respawn-pane --surface surface:42
cmux respawn-pane --surface surface:42 --command "zsh"

Pipe pane output

Pipe all output from a surface to a shell command:

cmux pipe-pane --command "tee /tmp/surface-log.txt" --surface surface:42

Clear history

cmux clear-history --surface surface:42

Wait for signal

Synchronization primitive between surfaces:

# In surface A: wait for a signal
cmux wait-for my-signal --timeout 30

# In surface B: send the signal
cmux wait-for --signal my-signal

Surface health check

cmux --json surface-health

Returns health status for all surfaces in the current workspace.

Trigger flash (visual identification)

# Flash current surface
cmux trigger-flash

# Flash specific surface
cmux trigger-flash --surface surface:42

Useful for visually identifying which surface a ref points to.

subagent-workflows.md

Subagent Workflows

Patterns for using cmux to orchestrate multiple parallel tasks from an AI agent.

Single subagent pattern

The simplest case: spawn one pane, run a task, read output, clean up.

# 1. Create a split pane to the right
PANE_RESULT=$(cmux --json new-pane --direction right)
# Parse: extract surface_ref from JSON (e.g., "surface:50")
SURFACE_REF="surface:50"  # extracted from PANE_RESULT

# 2. Send command
cmux send --surface $SURFACE_REF "cd /path/to/project && npm test"
cmux send-key --surface $SURFACE_REF Enter

# 3. Wait for completion, then read output
cmux read-screen --surface $SURFACE_REF --scrollback --lines 200

# 4. Clean up
cmux close-surface --surface $SURFACE_REF

Parallel subagents pattern

Run multiple independent tasks simultaneously in separate panes.

# Create panes in a grid layout
# First split right
PANE1=$(cmux --json new-pane --direction right)
SURFACE1="surface:50"  # from PANE1

# Split the new pane down to create a 2x1 grid on the right
PANE2=$(cmux --json new-pane --direction down --pane pane:50)
SURFACE2="surface:51"  # from PANE2

# Send commands to each
cmux send --surface $SURFACE1 "npm run test:unit" && cmux send-key --surface $SURFACE1 Enter
cmux send --surface $SURFACE2 "npm run test:e2e" && cmux send-key --surface $SURFACE2 Enter

# Read results from each when done
OUTPUT1=$(cmux read-screen --surface $SURFACE1 --scrollback --lines 100)
OUTPUT2=$(cmux read-screen --surface $SURFACE2 --scrollback --lines 100)

# Clean up all
cmux close-surface --surface $SURFACE1
cmux close-surface --surface $SURFACE2

Workspace isolation pattern

For heavier tasks, create a dedicated workspace to avoid cluttering the main one.

# Create a new workspace
WS=$(cmux --json new-workspace)
WS_REF="workspace:20"  # from WS

# Create panes in the new workspace
PANE=$(cmux --json new-pane --direction right --workspace $WS_REF)
SURFACE="surface:60"

# Run task
cmux send --surface $SURFACE "make build" && cmux send-key --surface $SURFACE Enter

# When done, close entire workspace
cmux close-workspace --workspace $WS_REF

Output polling pattern

When you need to wait for a command to finish before reading output.

# Option 1: Use wait-for signals
# In the surface, append a signal after the command
cmux send --surface $SURFACE "npm test && cmux wait-for --signal task-done"
cmux send-key --surface $SURFACE Enter

# In the main agent, wait for the signal
cmux wait-for task-done --timeout 120

# Option 2: Poll read-screen for a completion marker
# Send command that echoes a marker when done
cmux send --surface $SURFACE "npm test; echo '===DONE==='"
cmux send-key --surface $SURFACE Enter

# Then poll read-screen and check for ===DONE===

Naming panes for tracking

Use rename-tab to label surfaces for easier identification:

cmux rename-tab --surface $SURFACE "Unit Tests"
cmux rename-tab --surface $SURFACE2 "E2E Tests"

Browser + terminal side-by-side

Common for web development - terminal on left, browser on right:

# Create browser pane to the right
cmux --json new-pane --type browser --direction right --url "http://localhost:3000"

# The terminal pane (left) runs the dev server
cmux send --surface $TERMINAL_SURFACE "npm run dev"
cmux send-key --surface $TERMINAL_SURFACE Enter

Cleanup strategies

Close individual surfaces

cmux close-surface --surface surface:50
cmux close-surface --surface surface:51

Close by sending exit

cmux send-key --surface surface:50 "ctrl+c"
cmux send --surface surface:50 "exit"
cmux send-key --surface surface:50 Enter

Close entire workspace

cmux close-workspace --workspace workspace:20

Kill and respawn

cmux respawn-pane --surface surface:50

Notification on completion

cmux send --surface $SURFACE "npm test && cmux notify --title 'Tests' --body 'Passed' || cmux notify --title 'Tests' --body 'Failed'"
cmux send-key --surface $SURFACE Enter

Best practices

Always save surface refs - Store the surface ref from new-pane output. Stale refs after closing will error.
Use --json for parsing - Always pass --json when you need to extract refs from command output.
Clean up after yourself - Close surfaces/workspaces when tasks complete. Orphaned panes waste screen space and confuse users.
Use directions wisely - right for side-by-side comparison, down for log tailing. Avoid more than 3-4 splits as they become too small.
Prefer read-screen over pipe-pane - read-screen is a one-shot read. pipe-pane streams continuously and needs cleanup.
Signal for synchronization - Use cmux wait-for when you need to block until a task completes rather than polling.
Rename for clarity - Use rename-tab so the user can identify what each pane is doing at a glance.

Frequently Asked Questions

What is cmux?

How do I install cmux?

Run npx skills add AbsolutelySkilled/AbsolutelySkilled --skill cmux in your terminal. The skill will be immediately available in your AI coding agent.

What AI agents support cmux?

cmux works with claude-code. Install it once and use it across any supported AI coding agent.