cmux

Manage cmux workspaces and Claude Code agents from one terminal.

This skill is bundled with forge as an opt-in addon. It requires the cmux terminal multiplexer to be installed and running as your active terminal. Without cmux, this skill is inert.

Quick Reference

# List workspaces
cmux list-workspaces

# Create named workspace with Claude + prompt (no focus steal)
CURRENT=$(cmux current-workspace 2>&1 | awk '{print $1}')
NEW_UUID=$(cmux new-workspace --command "claude 'Your prompt here'" 2>&1 | awk '{print $2}')
cmux rename-workspace --workspace "$NEW_UUID" "workspace-name" 2>&1
cmux select-workspace --workspace "$CURRENT" 2>&1

# Resume session in named workspace (no focus steal)
CURRENT=$(cmux current-workspace 2>&1 | awk '{print $1}')
NEW_UUID=$(cmux new-workspace --command "claude --resume <session-id>" 2>&1 | awk '{print $2}')
cmux rename-workspace --workspace "$NEW_UUID" "workspace-name" 2>&1
cmux select-workspace --workspace "$CURRENT" 2>&1

# Rename / Select / Close
cmux rename-workspace --workspace workspace:N "Name"
cmux select-workspace --workspace workspace:N
cmux close-workspace --workspace workspace:N

Key Patterns

• Send command to any workspace: cmux send --workspace workspace:N "text" && cmux send-key --workspace workspace:N Enter
• Read any agent's screen: cmux read-screen --workspace workspace:N
• Spawn named workspace: use spawn-workspace.sh script below

Surface (Tab) Management

# List panes and surfaces
cmux list-panes --workspace workspace:N
cmux list-pane-surfaces --workspace workspace:N

# Move / Reorder / Rename / Close
cmux move-surface --surface surface:S --workspace workspace:N
cmux reorder-surface --surface surface:S --index 0
cmux rename-tab --surface surface:S "New Name"
cmux close-surface --surface surface:S --workspace workspace:N

# Split pane
cmux drag-surface-to-split --surface surface:S left|right|up|down
cmux break-pane --workspace workspace:N --pane pane:M

Scripts

spawn-workspace.sh

Located at scripts/spawn-workspace.sh. Use to spawn a named cmux workspace with Claude Code without stealing focus.

Usage: spawn-workspace.sh <name> [--prompt "..."] [--cwd /path] [--auto] [--loop [pct]]

Flags:

• --prompt: prompt to send to the spawned Claude agent
• --cwd: set working directory for the agent
• --auto: run with --dangerously-skip-permissions (no confirmations)
• --loop: enable infinite loop (auto-handoff at 60% context, or pct if specified). Requires a separate loop handler hook to act on the registered config.

Socket API

Programmatic control via Unix socket at /tmp/cmux.sock. Request format: newline-terminated JSON.

Method	Purpose
workspace.list	List all workspaces
workspace.create	Create new workspace
workspace.select	Switch to workspace
surface.send_text	Send text to terminal
surface.send_key	Send keypress (enter, tab, escape)
set-status	Sidebar status pill (icon, color)
set-progress	Progress bar (0.0-1.0)
notification.create	Push notification

CLI flags: --json, --workspace ID, --surface ID, --id-format refs|uuids|both

Docs: https://www.cmux.dev/docs/api