pi-agents-config: Skill for Claude Code

cmux Terminal & Browser Management

Use this skill when you need to run processes in separate terminals you can observe and control — dev servers, test watchers, build processes, or any long-running task. Also use it to open browser surfaces for testing web pages, taking screenshots, clicking elements, and reading page content.

Prerequisite: You must be running inside cmux (check for CMUX_SOCKET_PATH in the environment). If it's not set, these commands won't work.

Default approach: Prefer creating surfaces (tabs) in the current workspace over spawning new workspaces. Tabs keep everything grouped together and are less disruptive. Only use new-workspace when you need full isolation (e.g., a completely separate project).

---

Environment Variables

cmux auto-sets these in every shell it spawns:

Variable	Purpose
CMUX_WORKSPACE_ID	UUID of the current workspace
CMUX_SURFACE_ID	UUID of the current surface/panel
CMUX_SOCKET_PATH	Unix socket path (usually /tmp/cmux.sock)

Commands run inside a cmux shell automatically target the right workspace without needing --workspace.

---

Core Commands

Create a new tab (surface) in the current workspace

cmux new-surface --type terminal
# Returns: OK surface:<n> pane:<n> workspace:<n>

This is the preferred way to spawn a new shell. It creates a tab next to the current terminal in the same workspace.

Create a new split pane

cmux new-split <left|right|up|down>
cmux new-pane --direction <left|right|up|down> [--type terminal]

Spawn a new workspace (for full isolation)

cmux new-workspace [--cwd <path>] [--command "<text>"]
# Returns: OK workspace:<n>

Send commands

cmux send --surface <ref> '<command>\n'

The \n sends Enter. Without it, text is typed but not executed.

Read terminal output

cmux read-screen --surface <ref> [--lines <n>] [--scrollback]

• Default: visible screen only
• --scrollback: include scrollback buffer
• --lines <n>: limit to last N lines (implies scrollback)