# Agent Control

> Run and orchestrate multiple Pi AI agents inside cmux on macOS. Covers pane creation, non-disruptive layout management, interactive Pi sub-agent spawning, sending task prompts, reading screens, and monitoring worker sessions.

- **Type:** Skill
- **Install:** `agentstack add skill-timur00kh-cmux-agent-control-skill-agent-control`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Timur00Kh](https://agentstack.voostack.com/s/timur00kh)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Timur00Kh](https://github.com/Timur00Kh)
- **Source:** https://github.com/Timur00Kh/cmux-agent-control-skill/tree/main/skills/agent-control

## Install

```sh
agentstack add skill-timur00kh-cmux-agent-control-skill-agent-control
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
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:

```bash
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

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

To inspect real screen geometry:

```bash
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:

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

Create panes only if reusable panes do not already exist:

```bash
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.

```bash
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:

```bash
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`:

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

Then send a short pointer to a task file:

```bash
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:

```bash
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

```bash
# 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](https://github.com/Timur00Kh)
- **Source:** [Timur00Kh/cmux-agent-control-skill](https://github.com/Timur00Kh/cmux-agent-control-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-timur00kh-cmux-agent-control-skill-agent-control
- Seller: https://agentstack.voostack.com/s/timur00kh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.