cmux

cmux is a terminal multiplexer controlled via a Unix socket CLI. All commands follow the pattern:

cmux [--json] <command> [options]

Key Concepts

• Window — top-level container (like a tmux window)
• Workspace — a tab-like grouping within a window
• Pane — a visible rectangle in a workspace (can contain multiple surfaces)
• Surface — a single terminal or browser tab within a pane
• Panel — an overlay panel (e.g., sidebar)

IDs can be UUIDs, short refs (workspace:1/pane:2/surface:3), or numeric indexes.

Environment Variables

When running inside a cmux terminal, these are auto-set:

• CMUX_WORKSPACE_ID — default --workspace for all commands
• CMUX_SURFACE_ID — default --surface

This means most commands work without explicit IDs when run from within cmux.

Common Workflows

Read what's on screen

cmux read-screen                          # current surface
cmux read-screen --lines 50               # last 50 lines
cmux read-screen --scrollback             # include scrollback
cmux read-screen --surface surface:2      # specific surface

Send commands to a terminal

cmux send "ls -la\n"                      # send text + enter
cmux send-key Enter                       # send a keypress
cmux send --surface surface:2 "cd /tmp\n" # target specific surface

Create layouts

cmux new-workspace --command "vim"         # new workspace running vim
cmux new-split right                       # split current pane right
cmux new-split down                        # split current pane down
cmux new-pane --type browser --url "http://localhost:3000"

Manage workspaces

cmux list-workspaces
cmux select-workspace --workspace workspace:2
cmux rename-workspace "dev-server"
cmux close-workspace --workspace workspace:3

Sidebar status and progress

cmux set-status build "passing" --icon checkmark --color "#00ff00"
cmux set-progress 0.75 --label "Deploying..."
cmux log --level info --source agent "Task completed"

Browser automation

cmux browser open "https://example.com"
cmux browser snapshot --interactive
cmux browser click "#submit-button"
cmux browser fill "#search" "query text"
cmux browser eval "document.title"
cmux browser wait --selector ".loaded"

Notifications

cmux notify --title "Build Complete" --body "All tests passed"

Tips

• Always use --json when parsing output programmatically.
• Use cmux identify to discover the current workspace/surface context.
• read-screen + send is the primary pattern for interacting with running processes.
• capture-pane is an alias for read-screen (tmux compatibility).
• Browser commands require a browser-type surface; create one with cmux new-pane --type browser.

Full CLI Reference

For the complete list of commands, flags, and subcommands, see cli-reference.md.