CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

cmux-fanout

Fan out agent workspaces on a remote Mac's cmux from Windows — create a cmux workspace with N split panes by running one `ssh <host> cmux <verb>` per operation, launch agent REPLs (claude, codex, any CLI) in each pane, wait for readiness, and return a pane map for downstream skills. Use when the user wants to build an agent grid on the Mac's cmux, "fan out N agents on the mac", spin up remote cmux workspaces/panes, or inspect (status) and tear down grids built this way. Requires PowerShell 7.1+, key-auth SSH to the Mac, cmux running there, and the one-time socket-gate step (see setup.md). NOT for injecting into or reading existing panes conversationally (future cmux-connector), local Windows pane grids (use psmux-fanout), or driving cmux's embedded browser.

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

cmux-fanout

Builds an agent grid on a remote Mac's cmux from this Windows host: one workspace, N split panes, each running an agent CLI, plus a pane-map JSON handoff artifact.

Transport: one ssh <host> cmux <verb> <args> per operation — a plain, stateless CLI-over-SSH call each time, no persistent connection or session. Each verb (new-workspace, new-split, send, send-key, read-screen, refresh-surfaces, list-workspaces, close-workspace, tree, ping, version, capabilities) is its own ssh -T <host> <cmuxPath> <verb> ... invocation. Dependent operations (splits building on earlier splits) run sequentially; nothing is batched or pipelined the way a persistent RPC channel would be.

Requires

  • PowerShell 7.1+, ssh.exe on PATH, key-auth SSH to the Mac (no password prompts).
  • Mac side: cmux running, reachable via its CLI at the configured cmuxPath.
  • The one-time socket gate: by default cmux's automation socket only accepts processes started inside cmux (automation.socketControlMode: "cmuxOnly"). An SSH session is not a cmux child, so every socket-backed command is refused until the Mac is switched to allowAll and cmux is reloaded from inside the app — full steps in setup.md. Until then, only cmux version works over SSH.
  • First run: doctor.ps1, then tests\smoke\03-discovery.ps1 to validate the ref-key shapes (lib\CmuxRpc.psm1) against your cmux version.

Quickstart

$fan = "$env:USERPROFILE\...\cmux-fanout"   # wherever this skill lives

& "$fan\doctor.ps1"                          # preflight — run this first
& "$fan\fanout.ps1" -Panes 4 -Command claude
& "$fan\status.ps1"
& "$fan\teardown.ps1" -MapFile "<project>\__files.ccg\__temp\cmux-fanout-<name>.json"

Per-pane commands: -Commands @('claude','codex','claude','opencode'). Non-claude ready detection: -ReadyPattern '<regex matching the CLI's boot banner>'.

Pane map contract (consumed by cmux-connector)

{
  "host": "macmini", "sshHost": "macmini", "socketPath": "",
  "workspaceName": "fanout-...", "workspaceRef": "workspace:1", "created": "<ISO8601>",
  "panes": [ { "index": 0, "surfaceRef": "surface:1", "command": "claude", "ready": true } ]
}

Troubleshooting

Anything wrong → doctor.ps1 first. It runs cmux version (works even while gated — proves ssh + binary reachability) and then a socket op like ping (fails while gated) so you can tell the two failure modes apart.

  1. CMUX_GATE — socket refused a non-child process. The Mac is still on cmuxOnly. Fix: enable allowAll and reload cmux from inside the app (setup.md, section 2). Editing the config file alone does not fix this; cmux must be reloaded or restarted.
  2. CMUX_TRANSPORT — the ssh/host call itself failed (network, host down, auth). State on the Mac is unknown; check status.ps1 before retrying.
  3. CMUX_OP — cmux itself exited nonzero for a reason other than the gate. Read the actual cmux stderr/error text in the exception; it usually names the bad ref or argument.
  4. CMUX_SHAPE — a --json response didn't contain the expected ref key. Run tests\smoke\03-discovery.ps1 to see the real shape for your cmux version, then reconcile the ref-key lists in lib\CmuxRpc.psm1.
  5. Panes never ready → wrong -ReadyPattern for that CLI; check with -Verbose.
Repository

KennethJefferson/cmux_test

Path

__solutions/cmux-fanout/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.