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 <<'TASK'
Task: implement the requested change.

Context:
- ...

Instructions:
- Work in the specified directory.
- Report changed files and validation.
- Do not commit unless explicitly asked.
TASK

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

If literal paste is required:

cmux set-buffer --name agent-task "$(cat /tmp/task-agent.md)"
cmux paste-buffer --name agent-task --surface surface:14
cmux send-key --surface surface:14 enter

Read Worker Output

cmux read-screen --surface surface:14 --lines 40
cmux read-screen --surface surface:14 --lines 80 --scrollback

Use short reads repeatedly instead of dumping huge scrollback.

Send Follow-Up Instructions

cmux send --surface surface:14 "Please fix the failing test and rerun validation."
cmux send-key --surface surface:14 enter

For interactive prompts, send the option or short answer, then Enter:

cmux send --surface surface:14 "1"
cmux send-key --surface surface:14 enter

Monitor Multiple Agents

for S in surface:14 surface:15 surface:16; do
  echo "===== $S ====="
  cmux read-screen --surface "$S" --lines 20 || true
  echo
done

Optional cmux UI signals:

cmux notify --title "Agent finished" --body "Worker 1 is ready for review"
cmux trigger-flash --workspace "$CMUX_WORKSPACE_ID"
cmux set-progress 0.5 --label "Workers running"

Common Pitfalls

Do not use one-shot prompt mode for workers

Avoid this for inspectable worker sessions:

pi -p "do something"

It runs once and exits. For a worker you can monitor, use interactive mode:

pi --mode text --no-extensions

Do not send raw multiline prompts

Write long prompts to a file and send a one-line instruction to read it.

Do not respawn panes casually

Respawning can destroy the current surface, change refs, or disrupt the layout. Prefer /new inside an existing Pi TUI or send a launch command into an existing shell pane.

cmux send-surface is not a command

Use:

cmux send --surface surface:14 "text"
cmux send-key --surface surface:14 enter

Pane refs can change

After layout mutations, rerun:

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

Focus stealing is disruptive

Use --focus false when creating panes and avoid focus-changing commands unless explicitly requested.

Complete Example

#!/usr/bin/env bash
set -euo pipefail

WS="${CMUX_WORKSPACE_ID:?Run inside cmux}"

cat > /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