// This skill should be used when working with cmux, the terminal multiplexer application. Use when users mention cmux commands, workspace management, terminal pane operations, or cmux integration with erk. Essential for understanding cmux's workspace model, CLI commands, and scripting patterns.
This skill should be used when running CI checks iteratively and fixing failures. Use when executing make targets (fast-ci, all-ci, ci), iterating on lint/format/type/test errors, or needing the devrun agent pattern for pytest/ty/ruff/prettier/make/gt commands.
This skill should be used when creating a skill for a CLI tool. Use when users ask to document a command-line tool, create CLI guidance, or build a skill for terminal commands. Essential for systematically introspecting CLI tools through help text, man pages, GitHub repos, and online research, then organizing findings into effective skill documentation.
This skill should be used when creating a Claude Code slash command. Use when users ask to "create a command", "make a slash command", "add a command", or want to document a workflow as a reusable command. Essential for creating optimized, agent-executable slash commands with proper structure and best practices.
Simplifies and refines Python code for clarity, consistency, and maintainability while preserving all functionality. Applies dignified-python standards. Focuses on recently modified code unless instructed otherwise.
Internal skill for commit message generation. Only load when explicitly requested by name or invoked by commands.
Guide for erk exec subcommands. Use when running erk exec commands to understand syntax, find the right command for a task, or learn common workflows. Always check syntax with -h or load this skill before running erk exec commands.
| name | cmux |
| description | This skill should be used when working with cmux, the terminal multiplexer application. Use when users mention cmux commands, workspace management, terminal pane operations, or cmux integration with erk. Essential for understanding cmux's workspace model, CLI commands, and scripting patterns. |
| metadata | {"internal":true} |
cmux is a native macOS terminal application (Swift/AppKit) that provides terminal multiplexing with workspaces, panes, and splits. It uses Ghostty's rendering engine (libghostty) for GPU-accelerated terminal output. The CLI communicates with the running app via a Unix domain socket at /tmp/cmux.sock.
Think of cmux as "tmux reimagined as a native macOS app" -- it has workspaces (like tmux windows), panes (like tmux panes), and surfaces (individual terminal or browser instances within panes), all controllable via a rich CLI.
This skill covers the mental model, common commands, gotchas, and erk integration. Load references/cmux-reference.md when you need:
list-windows, new-window, focus-window, close-window, move-workspace-to-window)move-surface, reorder-surface, drag-surface-to-split, surface-health)list-panels, focus-panel, tab-action, rename-tab)clear-status, list-status, clear-progress, clear-log, list-log, sidebar-state)pipe-pane, wait-for, copy-mode, set-hook, bind-key, popup, etc.)ping, capabilities, claude-hook, set-app-focus)Window (top-level OS window)
+-- Workspace (vertical tab, like a tmux window)
+-- Pane (a split region)
+-- Surface (terminal or browser instance)
Objects are referenced by UUID (A1B2C3D4-...), short ref (workspace:1, pane:2, surface:3), or numeric index (0, 1). Use --id-format refs|uuids|both to control output format.
cmux sets these inside managed terminals: CMUX_WORKSPACE_ID (current workspace UUID, used as default for --workspace), CMUX_SURFACE_ID, CMUX_TAB_ID, CMUX_SOCKET_PATH (default: /tmp/cmux.sock).
Unix domain socket at /tmp/cmux.sock. V2 API uses newline-delimited JSON. CLI wraps socket calls into user-friendly commands.
--socket PATH Override socket path (default: /tmp/cmux.sock)
--window WINDOW Target specific window
--password PASSWORD Socket auth password
--json Output as JSON
--id-format refs|uuids|both Control ID format
--version, -v Show version
--help, -h Show help
| Command | Description |
|---|---|
new-workspace [--command <text>] | Create workspace (auto-appends \n). Returns OK <uuid> |
list-workspaces | List all workspaces |
select-workspace --workspace <ref> | Switch to workspace |
rename-workspace [--workspace <ref>] <title> | Rename workspace |
close-workspace --workspace <ref> | Close workspace |
current-workspace | Print current workspace ID |
| Command | Description |
|---|---|
new-split <left|right|up|down> [--workspace <ref>] | Split pane |
new-surface [--type <terminal|browser>] [--pane <ref>] | Add surface |
list-panes [--workspace <ref>] | List panes |
focus-pane --pane <ref> | Focus pane |
close-surface [--surface <ref>] | Close surface |
send [--workspace <ref>] [--surface <ref>] <text> | Send text (must include \n) |
send-key [--workspace <ref>] [--surface <ref>] <key> | Send keystroke |
read-screen [--workspace <ref>] [--surface <ref>] [--scrollback] [--lines <n>] | Read terminal content |
| Command | Description |
|---|---|
notify --title <text> [--subtitle <text>] [--body <text>] | Send notification |
set-status <key> <value> [--icon <name>] [--color <hex>] | Set sidebar status |
set-progress <0.0-1.0> [--label <text>] | Set progress bar |
log [--level <level>] [--source <name>] <message> | Add log entry |
The browser subsystem has 40+ commands for full web automation. Key categories:
browser open, browser navigate/goto, browser back/forward/reloadbrowser click, browser fill, browser type, browser select, browser pressbrowser snapshot [--interactive], browser eval <js>, browser get, browser isbrowser wait --selector|--text|--url-contains|--function [--timeout-ms]--snapshot-after flag: Most interaction commands accept this flag to automatically capture a snapshot after the actionLoad references/cmux-reference.md for full browser command syntax.
These are documented in the reference file:
wait-for <channel> -- Inter-process synchronization (tmux compat)claude-hook <event> -- Claude Code integration hookpipe-pane -- Pipe pane output to external commandpopup -- Show popup overlayset-hook / bind-key / unbind-key -- Hook and key binding management--command auto-appends newlinecmux new-workspace --command 'echo hello' automatically appends \n, so the command executes immediately. Do NOT add your own \n.
send requires explicit \nUnlike --command, cmux send does NOT auto-append a newline. You must include it:
# WRONG - text is typed but not executed
cmux send --workspace "$WS" "echo hello"
# CORRECT - command executes
cmux send --workspace "$WS" $'echo hello\n'
OK <uuid>cmux new-workspace returns OK <uuid>. Extract the workspace ID:
WS=$(cmux new-workspace | awk '{print $2}')
--commandUse single quotes to prevent outer shell expansion of $():
# CORRECT - subshell runs inside workspace
cmux new-workspace --command 'source <(erk slot teleport 456 --new-slot --script --sync)'
# WRONG - subshell expands in current shell
cmux new-workspace --command "source <(erk slot teleport 456 --new-slot --script --sync)"
--working-directory CLI flagThe CLI does not expose a working directory flag. Workaround:
cmux new-workspace --command 'cd /path/to/project'
There is a ~0.5s internal delay after workspace creation before commands are sent, to allow the shell to initialize. Keep this in mind when chaining commands.
cmux knows nothing about git branches. Branch names used as workspace titles via rename-workspace are purely cosmetic labels for human navigation.
cmux integration is gated on a global config flag:
# ~/.erk/config.toml
cmux_integration = true
Check/set via CLI:
erk config get cmux_integration
erk config set cmux_integration true
erk exec cmux-open-prCreates a cmux workspace that opens a PR with checkout or teleport mode:
erk exec cmux-open-pr --pr 8152
erk exec cmux-open-pr --pr 8152 --branch "my-branch"
erk exec cmux-open-pr --pr 8152 --mode teleport
What it does:
gh pr view --json headRefName (if --branch omitted)source <(erk pr checkout <pr> --script)source <(erk slot teleport <pr> --new-slot --script --sync){"success": true, "pr_number": N, "branch": "...", "workspace_name": "..."}When cmux_integration is enabled, the erk dash TUI command palette exposes:
Both require a plan with pr_number and pr_head_branch.
# Create workspace and run command
WS=$(cmux new-workspace --command 'cd ~/code/myproject && make build' | awk '{print $2}')
cmux rename-workspace --workspace "$WS" "build"
# Create workspace, then send commands separately
WS=$(cmux new-workspace | awk '{print $2}')
cmux send --workspace "$WS" $'cd ~/code/myproject\n'
cmux send --workspace "$WS" $'make test\n'
# Read terminal output
cmux read-screen --workspace "$WS" --lines 50
cmux read-screen --workspace "$WS" --scrollback
# Split workspace layout
WS=$(cmux new-workspace --command 'cd ~/code/project' | awk '{print $2}')
cmux new-split right --workspace "$WS"
# JSON output for scripting
cmux --json list-workspaces
cmux select-workspace --workspace workspace:0
| Issue | Cause | Fix |
|---|---|---|
Connection refused | cmux app not running | Launch cmux.app |
Socket not found | Wrong socket path | Check /tmp/cmux.sock exists |
| Command typed but not executed | Missing \n in send | Use $'command\n' |
| Wrong workspace targeted | No --workspace flag | Use $CMUX_WORKSPACE_ID or explicit ref |
--command text expanded too early | Double quotes around $() | Use single quotes |