Cmux subagent

cmux Subagent

Create a new terminal tab in the current cmux pane, launch a bare pi subagent inside it, then hand the task off via intercom. The subagent sees the caller's agent name as the incoming message's sender, so it knows who launched it and can reply over intercom when it finishes.

cmux send is used once — only to start the pi process. The task itself is sent over intercom.

Maintainer: ember-skua-45. Bugs, breakages, or environment edge-cases (e.g. cmux identify returning caller: null, missing CMUX_WORKSPACE_ID, parallel-launch races)? Report via GitHub issues at https://github.com/elecnix/cmux-subagent/issues, or — if you're a pi user with agent-identity intercom — intercom({ action: "send", to: "ember-skua-45", message: "..." }) with a repro and the cmux/pi env. Don't edit this file yourself; report it and I'll patch it.

This skill is asynchronous — never block the caller

The whole point is async delegation: the caller fires the task off and continues (does other work, or just goes idle). It is never blocked waiting on the subagent.

• Hand off with intercom send (fire-and-forget).
• Then END YOUR TURN (stop calling tools / yield). Do not poll, sleep, monitor, or check pending.
• The subagent's reply is delivered to you later as a 📨 intercom notification, which starts a new turn automatically — you handle the result there (report to the user, continue, or stop).

⚠️ The trap that has caused multi-minute flailing loops: a send reply is not a pending ask. intercom pending will forever say "No unresolved inbound asks", and the 📨 notification only delivers once your turn stops calling tools. So if you send and then try to wait for the reply in the same turn (polling pending, sleep, monitor, jobs, wait), you'll never see it and you'll spin for minutes. Send and stop. The notification will wake you.

Do NOT use intercom ask for the handoff — it blocks the caller up to 10 min, defeating the async goal. Use ask only in the rare case where you deliberately want to synchronize/block on the subagent.

What's verified vs. what doesn't work

Verified working:

• cmux new-surface --type terminal --pane <ref> --focus false — creates a tab at far right, zero focus steal.
• cmux send --surface <ref> "cd ~/Source/<REPO>/main && pi\n" — launches the subagent (launch command only, not the task).
• cmux identify --json --id-format both | jq -r '.caller.pane_ref' — get the current pane ref.
• cmux tree — prints each surface as surface surface:N [terminal] "π - <agent-name> - <context>". The auto-generated agent name matches [a-z]+-[a-z]+-[0-9]+ (e.g. tidal-grouse-50). This is the reliable way to read the subagent's name.
• A bare pi sitting idle at its prompt does receive and act on an inbound intercom send, and its send reply is delivered to an idle caller as a 📨 notification that starts a new turn.

Does NOT work / common mistakes:

• Don't double-prefix the surface ref in grep. cmux new-surface returns surface:N (with the surface: prefix); the cmux tree line is surface surface:N .... So grep for $NEW (→ surface:N), never "surface:$NEW" (→ surface:surface:N, matches nothing). This silently broke discovery in earlier versions.
• Don't grep for the literal π to detect the title — multibyte Unicode; has failed to match inside non-interactive shells. Match the agent-name pattern [a-z]+-[a-z]+-[0-9]+ instead.
• pi --name <LABEL> / /name set only the session display name, not the agent-identity name intercom targets / that appears in the tab title. The agent-identity name is auto-generated and can't be set at launch. Don't rely on --name.
• cmux identify --json can return caller: null when the skill runs from a pi bash tool (not a cmux-spawned shell) — the common case for an agent invoking the skill via a tool call. Read .caller.* // .focused.*, never .caller.* alone.
• cmux new-surface defaults --workspace to $CMUX_WORKSPACE_ID, which is often unset in a bash-tool env → not_found: Workspace not found. Pass --workspace explicitly (from focused.workspace_ref).
• Empty $NEW is dangerous. If new-surface fails, $NEW is empty and the Step 2 poll grep "$NEW" matches every tree line → you capture a stale, unrelated session's name and intercom send the task to the wrong agent. Always guard [ -z "$NEW" ] && abort right after new-surface.
• intercom { action: "list" } is a useful confirmation, but don't trust its (id) to disambiguate (a duplicate-id display quirk has been seen). Match by name.
• Both sides: respond with send, not reply, after a send. intercom reply only resolves a pending ask; using it to answer a send fails with "Reply target does not match a pending ask" / "No active intercom context to reply to". This bites the caller too, not just the subagent.
• cmux reorder-surface --focus false / cmux move-surface --focus false — steal focus despite the flag.

Rules:

• NEVER close surfaces.
• ALWAYS re-identify before acting — surface refs shift.
• Send the task over intercom, never by typing it into the tab with cmux send.
• After send, end your turn. Do not wait for the reply in the same turn.

Step 1 — Launch the subagent (no task text)

J=$(cmux identify --json --id-format both)
PANE=$(echo "$J" | jq -r '.caller.pane_ref // .focused.pane_ref // empty')
WS=$(echo   "$J" | jq -r '.caller.workspace_ref // .focused.workspace_ref // empty')
[ -z "$PANE" ] || [ -z "$WS" ] && { echo "abort: cmux identify returned no pane/workspace" >&2; exit 1; }
NEW=$(cmux new-surface --type terminal --pane "$PANE" --workspace "$WS" --focus false 2>&1 \
        | grep -o 'surface:[0-9]*' | head -1)
[ -z "$NEW" ] && { echo "abort: new-surface failed" >&2; exit 1; }
cmux send --surface "$NEW" $'cd ~/Source/<REPO>/main && pi\n'

Replace <REPO>. Do not append the task here, and don't bother with --name (it won't change the intercom target). Keep $NEW — you'll use it to read the subagent's name.

Why this exact form (each line matters):

• cmux identify can return caller: null (bash-tool env). Fall back caller // focused so the pane/workspace resolve regardless.
• --workspace is passed explicitly because new-surface otherwise defaults to $CMUX_WORKSPACE_ID, which is often unset in a bash-tool env → not_found: Workspace not found.
• The [ -z "$NEW" ] && abort guard is critical: without it, a failed new-surface leaves $NEW empty, and Step 2's grep "$NEW" matches every tree line → you'd capture an unrelated session's name and send the task to the wrong agent.

Step 2 — Read the subagent's agent name from its tab title

Pi sets the new surface's title to π - <agent-name> - <context> within ~1–2s of booting. Poll for the agent-name pattern (π-independent, locale-safe), bounded so it can't hang:

SUBAGENT=""
for i in $(seq 1 60); do                       # max ~30s
  SUBAGENT=$(cmux tree 2>/dev/null | grep "$NEW" | grep -oE '[a-z]+-[a-z]+-[0-9]+' | head -1)
  [ -n "$SUBAGENT" ] && break
  sleep 0.5
done
echo "$SUBAGENT"   # e.g. tidal-grouse-50

This grabs the first word-word-digits token on the surface's line — the auto-generated agent-identity name. (Won't match a human-named session like smoke fix, but a bare pi launch always gets an auto-name.)

If $SUBAGENT is still empty after the loop, fall back to intercom list and find the live (not 💤 revivable), non-[self] entry whose cwd is the worktree you launched into; take its name (not id).

Step 3 — Hand off the task asynchronously (send, then stop)

intercom({
  action: "send",                // fire-and-forget, returns instantly
  to: "<SUBAGENT>",              // the name from Step 2
  message: [
    "<TASK details here>",
    "",
    "When done, reply over intercom to <CALLER-NAME> (your caller) with a short summary:",
    'intercom({ action: "send", to: "<CALLER-NAME>", message: "..." })'
  ].join("\n")
});
// STOP. End your turn here. Do NOT poll/sleep/monitor/check pending.
// The reply will arrive as a 📨 notification that starts a new turn.

<CALLER-NAME> is your own agent name (the subagent also sees it as the sender). After this call, yield — return to the user, go idle, or do other work. You are not blocked.

Step 4 — When the 📨 reply arrives (a new turn)

The subagent used send, so there is no pending ask:

• Respond to the subagent with intercom send, not intercom reply. There's no pending ask to resolve, so reply fails with "Reply target does not match a pending ask" / "No active intercom context to reply to". This applies to the caller just as much as the subagent — reply only works to resolve an ask.
• Just read the result from the 📨 notification and act on it (report to the user, continue your work, or stop per the user's original instruction).
• Optionally intercom({ action: "send", to: "<SUBAGENT>", message: "got it, thanks" }) a brief acknowledgment.

Step 5 — How the subagent replies

On receiving the caller's send, the subagent does the work, then sends the result back — intercom send, not reply (there's no pending ask to resolve):

intercom({ action: "send", to: "<CALLER-NAME>", message: "<TASK> complete. <summary>" })

This delivers to the caller as a 📨 notification (Step 4).

Optional — Report the tab name to the user

cmux tree | grep "$NEW" | sed 's/.*"\(.*\)".*/\1/'
# → π - <agent-name> - <context>

Repo Detection

Repos live under ~/Source as bare repos with worktrees. Detect the repo name from the current working directory:

# if CWD is under ~/Source/<reponame>/<branch>
REPO=$(pwd | sed -n 's|.*/Source/\([^/]*\).*|\1|p')
# or from git remote:
# REPO=$(git remote get-url origin | sed 's|.*/||; s|\.git$||')

The main worktree is at ~/Source/<REPO>/main.