# Cmux

> Control the cmux terminal multiplexer via its Unix socket CLI. Use when the agent needs to: manage terminal windows/workspaces/panes/splits, read terminal screen output, send commands or keystrokes to terminals, automate browser surfaces, set sidebar status/progress, handle notifications, or orchestrate multi-pane development workflows. Triggers on: cmux, terminal multiplexer, split pane, read screen, send keys, workspace layout, browser automation via cmux.

- Skill: `mikecfisher/cmux` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mikecfisher/cmux`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mikecfisher/cmux/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: mikecfisher (https://skillmd.com/u/mikecfisher)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mikecfisher/cmux

---


# 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
```bash
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
```bash
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
```bash
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
```bash
cmux list-workspaces
cmux select-workspace --workspace workspace:2
cmux rename-workspace "dev-server"
cmux close-workspace --workspace workspace:3
```

### Sidebar status and progress
```bash
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
```bash
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
```bash
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](references/cli-reference.md).