cmux Cheatsheet
Workspaces and Agents
Use this cmux reference while you build software engineering projects, review code, or refresh the syntax you reach for most.
Creating workspaces
A workspace is one sidebar row: a working directory, a layout of panes, and its own
metadata. ⌘N makes an empty one, and the CLI gives you every knob.
cmux ~/code/api # directory as a new workspace cmux new-workspace --name "Build" cmux new-workspace --cwd . --command "npm test" cmux new-workspace --cwd ~/code/api --focus true cmux new-workspace --name Agent --description "Fix flaky specs"
| Flag | Effect |
|---|---|
--name <title> | custom sidebar title |
--description <text> | second line in the sidebar |
--cwd <path> | working directory |
--command <text> | text plus one Enter sent to the first shell |
--env KEY=VALUE | workspace environment variable, repeatable |
--env-file <path> | load KEY=VALUE lines from a file |
--layout <json> | create with a split layout already built |
--focus <true|false> | focus it, default false |
--group <id|ref> | put it in a workspace group |
--command runs in a normal interactive shell and the shell stays alive after it
exits, so no follow-up send is needed. It is terminal only and is rejected for
browser or simulator surfaces.
Layouts in one call
--layout takes JSON, which is the fastest way to reproduce a standard agent setup.
cmux new-workspace --name Dev --layout '{
"direction": "horizontal",
"split": 0.5,
"children": [
{"pane": {"surfaces": [{"type": "terminal", "command": "vim"}]}},
{"pane": {"surfaces": [{"type": "terminal",
"command": "npm run start"}]}}
]
}'Layout surfaces define their own commands, so a top-level --command is ignored
when --layout is present.
Workspace environment
Variables set on a workspace are inherited by every pane, surface, and split created in it later, and they are re-applied on session restore.
cmux new-workspace --cwd . --env AWS_PROFILE=prod --env-file .env.local
cmux workspace env --mask--env overrides a value from --env-file. The set is deliberately left out of
workspace list so a plain listing cannot leak secrets, and --mask redacts values.
CMUX_* variables plus TERM, COLORTERM, and TERM_PROGRAM are protected and
always win. Values live in the session manifest in plaintext on disk.
Lifecycle and status
cmux workspace list cmux workspace select workspace:3 cmux workspace rename workspace:3 --title "Reviewing PR 412" cmux workspace close workspace:3 cmux workspace status # effective, inferred, override cmux workspace status set review cmux workspace status set auto # clear a pinned lane
workspace-action runs the sidebar context-menu items from a script.
--action | Effect |
|---|---|
pin · unpin | keep the row in the pinned group |
rename · clear-name | with --title |
set-description · clear-description | with --description |
set-color · clear-color | with --color <name|#hex> |
move-up · move-down · move-top | reorder |
close-others · close-above · close-below | bulk close |
mark-read · mark-unread | notification state |
Agents and notifications
Notifications are how you keep dozens of agents straight. A pane gets a blue ring, its sidebar row badges, and macOS shows a banner. They fire from OSC 9, 99, and 777 sequences automatically, or from the CLI.
cmux notify --title "Build done" --body "All tests passed" cmux notify --title Error --subtitle test.swift --body "Line 42" cmux list-notifications cmux jump-to-unread cmux mark-notification-read --all cmux clear-notifications --workspace workspace:2
cmux hooks setup wires the same thing into agent lifecycle events, so turn ends and
permission prompts notify without any per-project glue. Policy lives under
notifications in cmux.json:
| Key | Default | Meaning |
|---|---|---|
agentTurnComplete | whenIdle | whenIdle, always, or never |
agentPermissionPrompt | true | ping when an agent waits for permission |
agentIdleReminder | true | ping about 60s after a turn if still idle |
unreadPaneRing | true | blue ring on panes with unread |
dockBadge | true | unread count on the Dock tile |
paneFlashColor | null | override the ring and flash color |