cmux

Using cmux

cmux is a macOS terminal built for AI coding agents. The session runs inside cmux when CMUX_SOCKET_PATH is set.

Quick Orientation

cmux identify --json    # Current workspace, pane, surface
cmux tree --json        # Full hierarchy of windows/workspaces/panes/surfaces

Hierarchy: Window -> Workspace (sidebar tab) -> Pane (split region) -> Surface (terminal or browser tab)

Refs format: workspace:2, pane:1, surface:7 — always prefer short refs over UUIDs.

Environment Variables (Auto-Set)

Variable	Purpose
CMUX_SOCKET_PATH	Control socket (CLI uses automatically)
CMUX_WORKSPACE_ID	Current workspace UUID
CMUX_SURFACE_ID	Current surface UUID

Commands default to the current workspace/surface when flags are omitted.

Agent Orchestration

The core pattern for running multiple agents in parallel, each in its own pane.

Default: panes, not workspaces. Use cmux new-split to create splits within the current workspace. Only use cmux new-workspace when agents need completely separate project directories (e.g., monorepo subprojects with different --cwd).

Creating Balanced Pane Layouts

Each new-split returns the created surface ref — always capture it to target subsequent splits and commands:

S1=$(cmux new-split right | awk '{print $2}')   # Capture "surface:N" from "OK surface:N workspace:N"

Critical rule: always use --surface to target which pane to split. Without it, cmux splits whichever pane has focus — leading to recursive halving of one pane while others stay untouched.

Layout recipes by agent count

1 agent — single split:

S1=$(cmux new-split right | awk '{print $2}')
# Layout: [orchestrator 50% | agent-1 50%]

2 agents — split right, then subdivide:

S1=$(cmux new-split right | awk '{print $2}')
S2=$(cmux new-split down --surface $S1 | awk '{print $2}')
# Layout: [orchestrator 50% | agent-1 25%]
#                            | agent-2 25%]