
claw-mux
cmux terminal integration: terminal I/O, topology control, browser automation, markdown viewer, notifications
- version
- 1.2.1
- GitHub stars
- 52
Install
/plugin install claw-mux@claude-code-zeroRun it inside Claude Code after adding the marketplace with /plugin marketplace add LeeJuOh/claude-code-zero.
Contents
Discovered from sourceSkills 3
cmux Core Control
Use this skill to control cmux topology, terminal I/O (send commands to other panes and read output), notifications, and sidebar metadata.
Environment Detection
cmux sets $CMUX_WORKSPACE_ID and $CMUX_SURFACE_ID in every terminal it spawns. Check before using cmux commands:
if [ -z "$CMUX_WORKSPACE_ID" ]; then
echo "Not running inside cmux — cmux commands unavailable"
fi
If not in cmux, fall back to standard tools (no pane splitting, no cmux notifications).
Core Concepts
- Window: Top-level macOS cmux window.
- Workspace: Tab-like group within a window (sidebar entry).
- Pane: Split container in a workspace.
- Surface: A tab within a pane (terminal or browser panel).
Hierarchy: Window > Workspace > Pane > Surface
Default output uses short refs: window:N, workspace:N, pane:N, surface:N. UUIDs are still accepted as inputs. Request UUID output only when needed: --id-format uuids|both.
Fast Start
Topology
# Always identify first — short refs (pane:1, surface:N) are session-scoped
cmux identify --json # current caller context
cmux list-workspaces # list workspaces
cmux list-panes # list panes in workspace
cmux list-pane-surfaces --pane pane:1 # list surfaces in pane
cmux new-workspace # create workspace
cmux new-split right # split current surface to the right
cmux move-surface --surface surface:7 --pane pane:2 # move surface between panes
cmux trigger-flash --surface surface:7 # visual flash
Terminal I/O (send commands to other panes, read output)
cmux send --surface surface:N "echo hello\n" # send text + Enter (\n = Enter)
cmux send --surface surface:N "npm start\n" # run a command in another pane
cmux send-key --surface surface:N enter # send Enter key separately
cmux send-key --surface surface:N ctrl+c # send Ctrl+C (stop a process)
cmux read-screen --surface surface:N # read visible terminal text
cmux read-screen --surface surface:N --scrollback # include scrollback history
cmux read-screen --surface surface:N --scrollback --lines 200 # last 200 lines only
Notifications & Sidebar
cmux notify --title "Build Complete" --body "All tests passed"
cmux set-status build "Ready" --icon checkmark --color "#34c759"
cmux set-progress 0.75 --label "Running tests"
cmux log --level info --source claude-code "Starting build..."
Terminal I/O Patterns
The core workflow: split a pane, send a command, detect completion, read the output.
Before sending any command, decide how you'll know when it finishes. Claude Code blocks foreground sleep over 2 seconds — pick a completion strategy based on what you're running:
| Command type | Example | Strategy |
|---|---|---|
| Batch (start→finish) | npm run build, pytest | wait-for signal |
| Long-running service | npm run dev, docker compose up | Content poll for "ready" text |
| Interactive program | claude, node, psql | Content poll for prompt marker |
| Instant | echo, ls, cat | Immediate read-screen |
Batch commands → wait-for
Chain cmux wait-for -S <signal> to the command. Run the wait with run_in_background: true.
cmux new-split right # → surface:9
cmux send --surface surface:9 "npm run build && cmux wait-for -S build-done\n"
# run_in_background: true — notified on completion
cmux wait-for build-done --timeout 120 && cmux read-screen --surface surface:9 --scrollback --lines 50
Services / interactive programs → content poll
Poll read-screen for expected text. Use the bundled helper ${CLAUDE_SKILL_DIR}/scripts/poll-screen.sh with run_in_background: true (references shorten it to poll-screen.sh):
# run_in_background: true
${CLAUDE_SKILL_DIR}/scripts/poll-screen.sh surface:9 "ready|listening|Claude Code" --timeout 60
Common match patterns:
- Server ready:
ready|listening on|started - Claude Code ready:
Claude Code|tips:|❯ - Task complete:
╭─|❯|\\$\\s*$ - Build result:
✓|passed|error|failed
Hybrid example
Server start → wait for ready → then batch work:
cmux send --surface surface:9 "npm run dev\n"
# run_in_background: true — poll for server ready
${CLAUDE_SKILL_DIR}/scripts/poll-screen.sh surface:9 "ready on" --timeout 30
# (after background notification confirms ready)
cmux send --surface surface:9 "curl localhost:3000/health && cmux wait-for -S health-ok\n"
cmux wait-for health-ok --timeout 10
For detailed patterns (server monitoring, E2E testing, build pipelines, remote Claude Code), read the terminal-io reference.
Sidebar Metadata
# status pill: set-status <key> <value> [--icon name] [--color #hex]
cmux set-status build "Ready" --icon checkmark --color "#34c759"
cmux set-status build "Failed" --icon xmark --color "#ff3b30"
cmux clear-status build
# progress bar (0.0 to 1.0, optional --label)
cmux set-progress 0.75 --label "Running tests"
cmux clear-progress
# log messages (leveled, optional --source)
cmux log --level info --source claude-code "Starting build..."
cmux log --level success "Build complete"
cmux log --level warning "3 deprecation warnings"
cmux log --level error "Test suite failed"
Coexistence
- In cmux: Use
cmux new-splitfor panes,cmux send/cmux read-screenfor terminal I/O,cmux notifyfor notifications. - Outside cmux: These features are unavailable. Use standard terminal workflows.
- Browser automation in cmux: Use the
cmux-browserskill for embedded webview automation. - Markdown viewing in cmux: Use
cmux markdown open <path>directly to open a live-reloading panel. - With
cmux claude-teams: Teams uses its own tmux-shim layer for topology — do not mix directcmuxtopology commands with Teams orchestration.
Gotchas
- cmux commands fail silently outside cmux — always check
$CMUX_WORKSPACE_IDbefore using anycmuxcommand. - Short refs (
surface:7) are session-scoped and may change between sessions — alwayscmux identify --jsonat the start of automation to discover current topology. sendincludes\nfor Enter —cmux send "command\n"sends the command and presses Enter in one call. No need for a separatesend-key enterunless you want explicit timing control.send-keysdoes not exist — the command issend(text) andsend-key(key event). This is different from tmux'ssend-keys.pressdoes not exist — to send Ctrl+C, usecmux send-key --surface surface:N ctrl+c.read-screenreturns the current screen state — if a command is still running, the output may be incomplete. Use--scrollback --lines Nfor history, or use a completion strategy (see Terminal I/O Patterns above).- In Claude Code,
sleepover 2 seconds is blocked in foreground — usewait-forfor batch commands, content polling for interactive programs. Both requirerun_in_background: true. Avoidsleep N && read-screen— it reads too early or too late. - Always plan completion detection before sending a command — decide upfront: is this batch (wait-for), service/interactive (content poll), or instant (immediate read)? Sending without a plan leads to blind retries.
set-status --colorrequires hex values ("#34c759") — named colors likegreenare not supported.set-statusrequires a key (e.g.,build) as the first argument — the key allows multiple independent status pills per workspace.- If
cmux claude-teamsis active, it manages topology through a tmux-compat shim. Direct topology commands (new-split,move-surface) may conflict with Teams orchestration. - Desktop alerts are suppressed when the cmux window is focused and the workspace is active — use
cmux logfor always-visible status updates.
Deep-Dive References
| Reference | When to Use |
|---|---|
| Terminal I/O | Send commands, read output, server monitoring, E2E testing, build pipelines |
| Sync and Automation | wait-for synchronization, buffers, cmux.json custom workspace commands |
| Handles and Identify | Handle syntax, self-identify, caller targeting |
| Windows and Workspaces | Window/workspace lifecycle and reorder/move |
| Panes and Surfaces | Splits, surfaces, move/reorder, focus routing |
| Trigger Flash and Health | Visual flash confirmation and surface health checks |
| Notifications | Notification CLI, sidebar metadata API, hook patterns |
Browser Automation with cmux
Use this skill for browser tasks inside cmux webviews. Requires cmux environment ($CMUX_WORKSPACE_ID). Outside cmux, this skill's features are unavailable.
Core Workflow
- Open or target a browser surface.
- Verify navigation with
get urlbefore waiting or snapshotting. - Snapshot (
--interactive) to get fresh element refs. - Act with refs (
click,fill,type,select,press). - Wait for state changes.
- Re-snapshot after DOM/navigation changes.
cmux --json browser open https://example.com
# use returned surface ref, for example: surface:7
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive
cmux browser surface:7 fill e1 "hello"
cmux --json browser surface:7 click e2 --snapshot-after
cmux browser surface:7 snapshot --interactive
Surface Targeting
# identify current context
cmux identify --json
# open routed to a specific topology target
cmux browser open https://example.com --workspace workspace:2 --window window:1 --json
Notes:
- CLI output defaults to short refs (
surface:N,pane:N,workspace:N,window:N). - UUIDs are still accepted on input; only request UUID output when needed (
--id-format uuids|both). - Keep using one
surface:Nper task unless you intentionally switch.
Wait Support
cmux browser <surface> wait --selector "#ready" --timeout-ms 10000
cmux browser <surface> wait --text "Success" --timeout-ms 10000
cmux browser <surface> wait --url-contains "/dashboard" --timeout-ms 10000
cmux browser <surface> wait --load-state complete --timeout-ms 15000
cmux browser <surface> wait --function "document.readyState === 'complete'" --timeout-ms 10000
Common Flows
Form Submit
cmux --json browser open https://example.com/signup
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive
cmux browser surface:7 fill e1 "Jane Doe"
cmux browser surface:7 fill e2 "jane@example.com"
cmux --json browser surface:7 click e3 --snapshot-after
cmux browser surface:7 wait --url-contains "/welcome" --timeout-ms 15000
cmux browser surface:7 snapshot --interactive
Clear an Input
cmux browser surface:7 fill e11 "" --snapshot-after --json
cmux browser surface:7 get value e11 --json
Stable Agent Loop (Recommended)
# navigate -> verify -> wait -> snapshot -> action -> snapshot
cmux browser surface:7 get url
cmux browser surface:7 wait --load-state complete --timeout-ms 15000
cmux browser surface:7 snapshot --interactive
cmux --json browser surface:7 click e5 --snapshot-after
cmux browser surface:7 snapshot --interactive
If get url is empty or about:blank, navigate first instead of waiting on load state.
Deep-Dive References
| Reference | When to Use |
|---|---|
| Commands | Full browser command mapping and quick syntax |
| Snapshot and Refs | Ref lifecycle and stale-ref troubleshooting |
| Authentication | Login/OAuth/2FA patterns and state save/load |
| Session Management | Multi-surface isolation and state persistence patterns |
| Video Recording | Recording limitations and screenshot/snapshot alternatives |
| Proxy Support | Proxy behavior in WKWebView and workarounds |
Ready-to-Use Templates
| Template | Description |
|---|---|
| Form Automation | Snapshot/ref form fill loop |
| Authenticated Session | Login once, save/load state |
| Capture Workflow | Navigate + capture snapshots/screenshots |
Limits (WKWebView)
These are not supported in cmux's embedded browser (WKWebView-based):
- Viewport emulation
- Offline emulation
- Trace/screencast recording
- Network route interception/mocking
- Low-level raw input injection
Use supported high-level commands (click, fill, press, scroll, wait, snapshot) instead.
Gotchas
- WKWebView-based, not Chromium — viewport emulation, network interception, and trace/screencast recording are not supported. Don't attempt CDP-style commands.
- Element refs (
e1,e2, ...) are invalidated on any DOM change — always re-snapshot after navigation, modal open/close, or mutating actions. Use--snapshot-afteron click/fill to combine action + snapshot. snapshot --interactivecan returnjs_erroron complex pages — fall back toget text bodyorget html bodyfor content extraction.browser opentargets the workspace of the calling terminal (via$CMUX_WORKSPACE_ID), even if a different workspace is currently focused. Use--workspaceto override.gotoandnavigateare aliases — both work for same-surface navigation.- Always use
--jsonwithbrowser open— without it, the output is plain text and the returned surface ref is harder to parse reliably.cmux --json browser open <url>returns structured JSON with the surface ref.
Troubleshooting
js_error on snapshot --interactive or eval
Some complex pages can reject the JavaScript used for rich snapshots.
Recovery:
cmux browser surface:7 get url
cmux browser surface:7 get text body
cmux browser surface:7 get html body
- Use
get urlfirst to confirm the page actually navigated. - Fall back to
get text bodyorget html bodywhensnapshot --interactivereturnsjs_error. - If the page is still failing, navigate to a simpler intermediate page, then retry.
Markdown Viewer with cmux
Use this skill to display markdown files in a dedicated panel with rich formatting and live file watching. Requires cmux environment ($CMUX_WORKSPACE_ID). Outside cmux, this skill's features are unavailable.
Core Workflow
- Write your plan or notes to a
.mdfile. - Open it in a markdown panel.
- The panel auto-updates when the file changes on disk.
# Open a markdown file as a split panel next to the current terminal
cmux markdown open plan.md
# Absolute path
cmux markdown open /path/to/PLAN.md
# Target a specific workspace
cmux markdown open design.md --workspace workspace:2
When to Use
- Displaying an agent plan or task list alongside the terminal
- Showing documentation, changelogs, or READMEs while working
- Reviewing notes that update in real-time (e.g., a plan file being written by another process)
Live File Watching
The panel automatically re-renders when the file changes on disk. This works with:
- Direct writes (
echo "..." >> plan.md) - Editor saves (vim, nano, VS Code)
- Atomic file replacement (write to temp, rename over original)
- Agent-generated plan files that are updated progressively
If the file is deleted, the panel shows a "file unavailable" state. During atomic replace, the panel retries within a short window. If the file returns later, close and reopen the panel.
Agent Integration
Opening a plan file
Write your plan to a file, then open it:
cat > plan.md << 'EOF'
# Task Plan
## Steps
1. Analyze the codebase
2. Implement the feature
3. Write tests
4. Verify the build
EOF
cmux markdown open plan.md
Updating a plan in real-time
The panel live-reloads, so simply overwrite the file as work progresses:
# The markdown panel updates automatically when the file changes
echo "## Step 1: Complete" >> plan.md
Routing
# Open in the caller's workspace (default — uses CMUX_WORKSPACE_ID)
cmux markdown open plan.md
# Open in a specific workspace
cmux markdown open plan.md --workspace workspace:2
# Open splitting from a specific surface
cmux markdown open plan.md --surface surface:5
# Open in a specific window
cmux markdown open plan.md --window window:1
Deep-Dive References
| Reference | When to Use |
|---|---|
| Commands | Full command syntax and options |
| Live Reload | File watching behavior, atomic writes, edge cases |
Rendering Support
The markdown panel renders:
- Headings (h1-h6) with dividers on h1/h2
- Fenced code blocks with monospaced font
- Inline code with highlighted background
- Tables with alternating row colors
- Ordered and unordered lists (nested)
- Blockquotes with left border
- Bold, italic, strikethrough
- Links (clickable)
- Horizontal rules
- Images (inline)
Supports both light and dark mode.
Gotchas
- File watcher does NOT auto-reconnect after a file is deleted and recreated — close and reopen the panel to pick up the new file.
- Large files (100KB+) may cause brief UI hitches during re-render. Keep plan files concise.
- Write the full plan file first, then open it — opening while still writing exposes a partially rendered state.
- Don't delete and recreate files rapidly — prefer overwriting in place or using atomic replacement (write to temp + rename).
Sponsors
Details
- Marketplace
- LeeJuOh/claude-code-zero
- Source
- plugins/claw-mux
- Category
- Community