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-zero

Run it inside Claude Code after adding the marketplace with /plugin marketplace add LeeJuOh/claude-code-zero.

Contents

Discovered from source

Skills 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 typeExampleStrategy
Batch (start→finish)npm run build, pytestwait-for signal
Long-running servicenpm run dev, docker compose upContent poll for "ready" text
Interactive programclaude, node, psqlContent poll for prompt marker
Instantecho, ls, catImmediate 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-split for panes, cmux send/cmux read-screen for terminal I/O, cmux notify for notifications.
  • Outside cmux: These features are unavailable. Use standard terminal workflows.
  • Browser automation in cmux: Use the cmux-browser skill 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 direct cmux topology commands with Teams orchestration.

Gotchas

  • cmux commands fail silently outside cmux — always check $CMUX_WORKSPACE_ID before using any cmux command.
  • Short refs (surface:7) are session-scoped and may change between sessions — always cmux identify --json at the start of automation to discover current topology.
  • send includes \n for Enter — cmux send "command\n" sends the command and presses Enter in one call. No need for a separate send-key enter unless you want explicit timing control.
  • send-keys does not exist — the command is send (text) and send-key (key event). This is different from tmux's send-keys.
  • press does not exist — to send Ctrl+C, use cmux send-key --surface surface:N ctrl+c.
  • read-screen returns the current screen state — if a command is still running, the output may be incomplete. Use --scrollback --lines N for history, or use a completion strategy (see Terminal I/O Patterns above).
  • In Claude Code, sleep over 2 seconds is blocked in foreground — use wait-for for batch commands, content polling for interactive programs. Both require run_in_background: true. Avoid sleep 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 --color requires hex values ("#34c759") — named colors like green are not supported.
  • set-status requires a key (e.g., build) as the first argument — the key allows multiple independent status pills per workspace.
  • If cmux claude-teams is 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 log for always-visible status updates.

Deep-Dive References

ReferenceWhen to Use
Terminal I/OSend commands, read output, server monitoring, E2E testing, build pipelines
Sync and Automationwait-for synchronization, buffers, cmux.json custom workspace commands
Handles and IdentifyHandle syntax, self-identify, caller targeting
Windows and WorkspacesWindow/workspace lifecycle and reorder/move
Panes and SurfacesSplits, surfaces, move/reorder, focus routing
Trigger Flash and HealthVisual flash confirmation and surface health checks
NotificationsNotification 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

  1. Open or target a browser surface.
  2. Verify navigation with get url before waiting or snapshotting.
  3. Snapshot (--interactive) to get fresh element refs.
  4. Act with refs (click, fill, type, select, press).
  5. Wait for state changes.
  6. 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:N per 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

ReferenceWhen to Use
CommandsFull browser command mapping and quick syntax
Snapshot and RefsRef lifecycle and stale-ref troubleshooting
AuthenticationLogin/OAuth/2FA patterns and state save/load
Session ManagementMulti-surface isolation and state persistence patterns
Video RecordingRecording limitations and screenshot/snapshot alternatives
Proxy SupportProxy behavior in WKWebView and workarounds

Ready-to-Use Templates

TemplateDescription
Form AutomationSnapshot/ref form fill loop
Authenticated SessionLogin once, save/load state
Capture WorkflowNavigate + 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-after on click/fill to combine action + snapshot.
  • snapshot --interactive can return js_error on complex pages — fall back to get text body or get html body for content extraction.
  • browser open targets the workspace of the calling terminal (via $CMUX_WORKSPACE_ID), even if a different workspace is currently focused. Use --workspace to override.
  • goto and navigate are aliases — both work for same-surface navigation.
  • Always use --json with browser 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 url first to confirm the page actually navigated.
  • Fall back to get text body or get html body when snapshot --interactive returns js_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

  1. Write your plan or notes to a .md file.
  2. Open it in a markdown panel.
  3. 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

ReferenceWhen to Use
CommandsFull command syntax and options
Live ReloadFile 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

More from LeeJuOh/claude-code-zero

All 12