---
name: cmux-agent-manager
description: Manage, spawn, and control multiple Claude Code agent instances via cmux terminal. Create workspaces, split panes, dispatch tasks to other agents, fire notifications, color-code workspaces, reorganize layouts, check surface health, and orchestrate parallel agent workflows.
argument-hint: "[action: spawn|dispatch|list|tree|cleanup|notify|color|organize] [optional: task description or workspace name]"
---

# cmux Agent Manager

You are a terminal orchestration expert. Your job is to use the `cmux` CLI to create, manage, color, organize, and control Claude Code instances across workspaces and panes -- from inside the current running session.

cmux is a native macOS terminal (Ghostty-based) with a full CLI + socket API. Every cmux terminal has `CMUX_WORKSPACE_ID` and `CMUX_SURFACE_ID` auto-injected in its environment.

---

## Prerequisites

```bash
which cmux          # /Applications/cmux.app/Contents/Resources/bin/cmux
cmux ping           # OK (if fails: open cmux.app first)
cmux list-workspaces
cmux tree           # full hierarchy: windows > workspaces > panes > surfaces
```

---

## Topology Model

```
window       top-level OS window
  workspace  named tab in sidebar
    pane     split region
      surface  a terminal OR browser tab inside a pane
```

Sidebar per workspace shows: git branch, PR status, working dir, listening ports, notification text, color indicator.

---

## Core Commands

### Inspect
```bash
cmux list-workspaces              # * = selected
cmux list-panes [--workspace X]
cmux list-pane-surfaces [--workspace X] [--pane X]
cmux tree                         # full hierarchy dump
cmux surface-health [--workspace X]   # detect unhealthy surfaces
```

### Create
```bash
cmux new-workspace
cmux new-workspace --command "cd ~/project && claude"
cmux new-split right [--workspace X]
cmux new-split down  [--workspace X]
```

### Rename
```bash
cmux rename-workspace [--workspace X] "new name"
```

### Color Workspaces
```bash
cmux workspace-action --action color-green  [--workspace X]   # running
cmux workspace-action --action color-yellow [--workspace X]   # waiting
cmux workspace-action --action color-red    [--workspace X]   # error
cmux workspace-action --action color-blue   [--workspace X]   # research
cmux workspace-action --action color-purple [--workspace X]   # client
cmux workspace-action --action color-gray   [--workspace X]   # done
```

### Send Commands to Any Surface
```bash
cmux send --workspace X --surface Y "text here"
cmux send-key --workspace X --surface Y "enter"
cmux send-key --workspace X --surface Y "ctrl+c"    # interrupt
```

### Notifications
```bash
cmux notify --title "Agent done" --body "Review needed" [--workspace X]
cmux list-notifications
cmux trigger-flash --workspace X    # visual flash
```

### Reorder and Move
```bash
cmux reorder-workspace --workspace X --index 0
cmux move-workspace-to-window --workspace X --window Y
cmux move-surface --surface X --pane Y
```

### Close
```bash
cmux close-workspace --workspace X
cmux close-surface --surface X
cmux refresh-surfaces [--workspace X]   # fix ghost surfaces
```

---

## Patterns

### Spawn an Agent
```bash
spawn_agent() {
  local name="$1" path="$2" task="$3" color="${4:-color-green}"
  WS=$(cmux --json new-workspace | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
  cmux rename-workspace --workspace "$WS" "$name"
  cmux workspace-action --action "$color" --workspace "$WS"
  cmux send --workspace "$WS" "cd $path && claude"
  cmux send-key --workspace "$WS" "enter"
  sleep 4
  cmux send --workspace "$WS" "$task"
  cmux send-key --workspace "$WS" "enter"
  cmux trigger-flash --workspace "$WS"
  cmux notify --workspace "$WS" --title "Agent: $name" --body "Task dispatched"
}
```

### Dispatch Task to Running Agent
```bash
cmux send-key --workspace X --surface Y "ctrl+c"   # interrupt if busy
sleep 0.5
cmux send --workspace X --surface Y "your new task here"
cmux send-key --workspace X --surface Y "enter"
cmux trigger-flash --workspace X
```

### Hook: Auto-notify When Agent Finishes
Add to ~/.claude/settings.json:
```json
{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "cmux notify --title 'Claude done' --body 'Review needed'"
      }]
    }]
  }
}
```

---

## Quick Reference

```
inspect       cmux tree / list-workspaces / surface-health
new agent     new-workspace > rename > color > send claude > enter
split         new-split right|down [--workspace X]
send task     send "task" + send-key enter
interrupt     send-key ctrl+c
flash         trigger-flash --workspace X
color         workspace-action --action color-green|red|yellow|blue|purple|gray
notify        notify --title "done" --body "review"
close         close-workspace / close-surface
```