Agent Control

Agent Control with Pi + cmux

Use this skill when you need to run, delegate to, or monitor multiple Pi agent sessions in the cmux macOS terminal app.

This skill is intentionally generic. It does not prescribe project-specific branching, task trackers, model-routing policy, or repository workflow.

Prerequisites

• macOS with cmux installed.
• cmux CLI available in PATH.
• pi CLI available in PATH.
• Run automation from inside a cmux terminal whenever possible.
• jq is recommended for parsing --json output.

Quick checks:

which cmux
which pi
env | grep '^CMUX_' || true

cmux Environment

cmux injects useful environment variables into terminal panes:

| Variable | Purpose | | --- | --- | | CMUX_WORKSPACE_ID | Current workspace UUID. Prefer this for all automation. | | CMUX_SOCKET_PATH | cmux Unix socket path. Do not hardcode it. | | CMUX_SURFACE_ID | Current surface UUID. | | CMUX_PORT / CMUX_PORT_RANGE | Ports available to browser/app automation. |

Always anchor commands to CMUX_WORKSPACE_ID when available:

WS="${CMUX_WORKSPACE_ID:?Run this from inside cmux or set CMUX_WORKSPACE_ID}"

Non-Disruptive Rules

• Reuse existing agent panes when possible.
• Do not steal focus: pass --focus false when creating panes.
• Do not close, respawn, or replace panes unless the user explicitly asked.
• Read the layout before sending commands.
• Send long prompts through files, not as raw multiline terminal input.
• Keep worker agents interactive; do not use one-shot print mode for sessions you need to inspect later.

Inspect Current Layout

cmux tree --workspace "$CMUX_WORKSPACE_ID"
cmux list-panes --workspace "$CMUX_WORKSPACE_ID"

To inspect real screen geometry:

cmux list-panes --workspace "$CMUX_WORKSPACE_ID" --json | jq '.panes | map({
  ref: .ref,
  x: .pixel_frame.x,
  y: .pixel_frame.y,
  width: .pixel_frame.width,
  height: .pixel_frame.height,
  focused: .focused
})'

cmux tree shows refs, not visual position. Use JSON geometry to verify actual left/right/top/bottom layout.

Recommended Layout

A practical multi-agent layout is one large orchestrator pane plus several compact worker panes:

┌───────────────────────┬────────────────┐
│                       │ worker agent 1 │
│ primary/orchestrator  ├────────────────┤
│                       │ worker agent 2 │
│                       ├────────────────┤
│                       │ worker agent 3 │
└───────────────────────┴────────────────┘

Create panes only if reusable panes do not already exist:

cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type terminal --direction right --focus false
cmux new-split down --focus false

Exact layout commands may vary by cmux version. Prefer cmux help new-pane / cmux help new-split if unsure.

Start an Interactive Pi Worker

Create an empty terminal pane first, then send the Pi launch command into that pane.

SURFACE=$(cmux new-pane --workspace "$CMUX_WORKSPACE_ID" \
  --type terminal --direction right --focus false --json | jq -r '.result.surface_ref')

cmux send --surface "$SURFACE" "pi --mode text --no-extensions"
cmux send-key --surface "$SURFACE" enter

Optional model examples:

pi --model provider/model-name --mode text --no-extensions
pi --model magnit-ailab/MagnitCopilot --mode text --no-extensions
pi --model ollama/kimi-k2.6:cloud --mode text --no-extensions

These are examples only. Choose models according to your project, budget, and provider availability.

Reuse an Existing Pi Pane

When a pane already contains a Pi TUI session, start a fresh conversation with /new:

cmux send --surface surface:14 "/new"
cmux send-key --surface surface:14 enter

Then send a short pointer to a task file:

cmux send --surface surface:14 "Read /tmp/task-agent.md and execute it exactly."
cmux send-key --surface surface:14 enter

Send Long Prompts Safely

Do not send long multiline prompts directly with cmux send. Some TUIs treat each line as a separate input.

Preferred pattern:

cat > /tmp/task-agent.md  /tmp/task-agent-1.md <<'TASK'
Task: inspect the code and report likely causes of the failing test.
Do not modify files.
TASK

SURFACE=$(cmux new-pane --workspace "$WS" --type terminal \
  --direction right --focus false --json | jq -r '.result.surface_ref')

cmux send --surface "$SURFACE" "pi --mode text --no-extensions"
cmux send-key --surface "$SURFACE" enter
sleep 2

cmux send --surface "$SURFACE" "Read /tmp/task-agent-1.md and execute it exactly."
cmux send-key --surface "$SURFACE" enter

echo "Worker started on $SURFACE"

Quick Reference

# Layout
cmux tree --workspace "$CMUX_WORKSPACE_ID"
cmux list-panes --workspace "$CMUX_WORKSPACE_ID" --json

# Create pane
cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type terminal --direction right --focus false

# Send input
cmux send --surface surface:14 "message"
cmux send-key --surface surface:14 enter

# Read output
cmux read-screen --surface surface:14 --lines 40

# Fresh Pi conversation
cmux send --surface surface:14 "/new"
cmux send-key --surface surface:14 enter

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Timur00Kh
• Source: Timur00Kh/cmux-agent-control-skill
• License: MIT

Install and usage instructions live in the source repository linked above.