Cmux

cmux

cmux is a command-line client for the cmux.app on this machine. Each command opens the app's Unix socket and changes the live window. There is no dry-run mode. Written against cmux 0.64.22; run cmux version to compare.

The four nouns

The surface is where text goes in and out. Almost every command needs one, and takes it from a flag or from the environment.

You are the caller

You run inside a cmux surface. Your environment has CMUX_WORKSPACE_ID and CMUX_SURFACE_ID, and every targeting flag defaults to them. So cmux send "ls" with no --surface types into your own terminal.

Start with:

cmux identify --json

caller.surface_ref in the output is you. focused.surface_ref is what the user looks at. Send text to your own surface only when the user asks for that.

Handles

A window, workspace, pane, or surface flag accepts three forms:

• ref — workspace:30, surface:217. Printed by every list command.
• uuid — A1B2C3D4-E5F6-4789-ABCD-0123456789AB. Stable and global.
• index — 0, 1, 2. The position in the list.

A ref and an index both look like a number, and they point at different things: the first workspace can print as workspace:1 at index 0. Use refs, and copy them from a listing you just ran. Add --id-format uuids or --id-format both when you need UUIDs.

Orient first

cmux tree            # this window: workspaces, panes, surfaces, titles, ttys
cmux tree --all      # every window
cmux identify --json # who you are

cmux tree shows the whole app in one screen. Read it before you target anything.

Two ways in

CLI verbs — cmux new-workspace, cmux send, cmux browser click. Use these to create things. A CLI verb is the only path that honours creation options.

cmux rpc <method> '<json>' — the raw socket. Use it to read and change things that already exist. It returns JSON on stdout, so it parses cleanly.

cmux rpc workspace.list
cmux rpc surface.list '{"workspace_id":"<uuid>"}'
cmux rpc surface.read_text '{"surface_id":"<uuid>"}'
cmux rpc workspace.rename '{"workspace_id":"<uuid>","title":"Done"}'

Creation is the split that matters. surface.create over rpc takes no url, and workspace creation over rpc drops the title, cwd, description, and group. So:

cmux new-workspace --name "Tests" --cwd . --description "owner/repo#1" --focus false
cmux new-surface --type browser --url "file:///tmp/board.html" --workspace <uuid> --focus false

Errors arrive on stderr with a non-zero exit, not as a JSON error object:

Error: invalid_params: Surface is not a terminal
method_not_found: Unknown method

Look it up

The binary is the source of truth, and it ships its own docs.

cmux --help              # every command
cmux <command> --help    # exact flags and examples for one command
cmux docs                # doc topics
cmux docs api            # CLI contract and socket API URLs
cmux capabilities        # every v2 socket method, as JSON

cmux --help lists more than 200 commands. Do not guess a flag. Read cmux <command> --help first. To find an rpc method:

cmux capabilities | jq -r '.methods[]' | grep workspace

Most commands take --json for machine-readable output.

Stay out of the user's way

The user is sitting in this app while you work. Pass --focus false on creation so their selection stays put. Focus something only when the user asks to see it.

Recipes

Run a command in a new workspace

cmux new-workspace --name "Tests" --cwd . --command "npm test" --focus false

--command sends the text and Enter.

Send input to another surface

cmux send --surface surface:78 "npm run build\n"
cmux send-key --surface surface:78 ctrl+c

send types the text and stops. End the string with \n to submit it.

Read what a surface shows

cmux read-screen --surface surface:78
cmux read-screen --surface surface:78 --scrollback --lines 200

read-screen returns a snapshot of this moment. It does not wait. It fails on a browser surface with invalid_params: Surface is not a terminal.

Boot an agent in another surface

An agent TUI batches an incoming paste. An Enter that races the paste gets swallowed, and the prompt sits typed but unsent. So type, confirm on screen, then press Enter as a separate call.

S=surface:78
cmux send --surface $S "claude\n"

# 1. Wait for the TUI. Poll for its prompt marker: ⏵⏵ ❯ "for shortcuts"
until cmux read-screen --surface $S | grep -qE '⏵⏵|❯|for shortcuts'; do sleep 0.2; done

# 2. Type the prompt with no Enter.
cmux send --surface $S "Fix the failing test in src/auth.ts"

# 3. Confirm it landed. Match a short head slice — the input box wraps the rest.
until cmux read-screen --surface $S | grep -qF "Fix the failing test"; do sleep 0.1; done

# 4. Now submit.
cmux send-key --surface $S enter

Budgets that hold in practice: the TUI is ready in about 2 seconds, so time out at 20. The typed text appears in well under a second, so time out at 5. Submit anyway on timeout, and tell the user it was not confirmed.

A dedicated agent surface is the other option, with its own UI instead of a TUI:

cmux new-surface --type agent-session --provider claude --working-directory . --focus false

--provider accepts codex, claude, or opencode, and defaults to codex.