cmux Cheatsheet
What cmux Is
Use this cmux reference while you build software engineering projects, review code, or refresh the syntax you reach for most.
What it is
cmux is a native macOS terminal app with vertical tabs and a notification system built for AI coding agents. It is written in Swift and AppKit and uses libghostty for terminal rendering, so it reads your existing Ghostty config for themes, fonts, and colors. The repo is manaflow-ai/cmux, the license is GPL, and the app auto-updates through Sparkle.
The parts that make it different from a plain terminal:
- A sidebar of vertical tabs, one row per workspace, showing git branch, linked
PR status and number, working directory, listening ports, and the latest
notification text.
- Notification rings. A pane gets a blue ring and its sidebar row lights up
when a process wants attention, driven by OSC 9, 99, and 777 escape sequences or
by the cmux notify CLI.
- An embedded browser pane with a scriptable API, so an agent can drive your
dev server and read the page back.
- A Unix socket plus CLI that can create workspaces, split panes, send
keystrokes, read screens, and automate the browser.
What it is not
| Not | Reality |
|---|---|
| A fork of Ghostty | it links libghostty as a library, the way an app uses WebKit |
| Cross-platform | macOS only, native Swift and AppKit |
| An Electron or Tauri app | no web runtime for the shell of the app |
| A terminal multiplexer | no prefix key, no server you attach to by default |
| An agent orchestrator with its own model | it launches whatever agent CLI you already have |
| A git client | it can show diffs, but it has no commit, push, or merge command |
| A container or worktree manager | workspaces are app-level groupings, not sandboxes |
There is also no built-in agent. cmux is a terminal, so Claude Code, Codex, OpenCode, Gemini CLI, Aider, Amp, Cursor CLI, and anything else that runs in a shell works because it runs in a shell.
The handle model
Four nested objects, and every CLI command targets one of them.
| Handle | Meaning | Short ref |
|---|---|---|
| Window | a top-level macOS window | window:1 |
| Workspace | a sidebar row, the tab-like group inside a window | workspace:2 |
| Pane | a split container inside a workspace | pane:3 |
| Surface | one tab inside a pane, a terminal or browser or preview | surface:4 |
cmux tree --all # the whole hierarchy cmux identify --json # which window/workspace/surface am I in
Commands accept a UUID, a short ref, or a plain index. Output prints refs by
default, and --id-format uuids or --id-format both adds UUIDs.
Where it sits next to Ghostty and tmux
Ghostty owns the terminal layer inside cmux, so anything Ghostty already does stays in Ghostty's config file.
| Concern | Configure in |
|---|---|
| Font, theme, colors, cursor, opacity, blur, scrollback | ~/.config/ghostty/config |
| Terminal keybindings | Ghostty config |
| Sidebar, tabs, notifications, browser, app behavior | ~/.config/cmux/cmux.json |
| cmux-owned shortcuts (workspaces, splits, browser) | cmux Settings or cmux.json |
Versus tmux: tmux is a multiplexer that runs inside any terminal and survives
disconnects, cmux is a GUI app whose layout is app state. cmux restores windows,
workspaces, panes, working directories, and best-effort scrollback on relaunch, but
it does not keep arbitrary live processes running across a quit. People commonly
run both, with tmux on the remote end of cmux ssh.
Quick orientation
cmux ~/code/myproject # open a directory as a new workspace cmux welcome # the welcome screen cmux --help # full command list, works with no socket cmux docs api # doc URLs and raw resources for a topic cmux version
cmux <path> is special: it goes through the app's file-open path and does not need
control-socket access, so it works before you enable socket control. Everything else
talks to the socket.
Docs live at cmux.com/docs, and the CLI
carries its own pointers. cmux docs accepts settings, shortcuts, api,
browser, agents, dock, and sidebars, and each one prints the canonical URL
plus a curl line for the raw schema or markdown.