cmux

Files (3)

• SKILL.md
• openai.yaml · agents/
• automation-patterns.md · references/

SKILL.md (first lines)

# 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

| Noun | What it is |
|---|---|
| window | A macOS window. Holds workspaces. |
| workspace | A tab-like group in a window. Holds panes. |
| pane | A split area in a workspace. Holds surfaces. |
| surface | One tab in a pane. A terminal, a browser, a simulator, or an agent session. |

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:

```bash
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

```bash
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.

```bash
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:

```bash
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.

```bash
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:

```bash
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

```bash

From will-ness-ai/skills, MIT.

More from will-ness-ai/skills