Connect to already-running cmux panes on the remote Mac (built by cmux-fanout) and inject caller-supplied work into them from Windows — one runspace per pane, fire-and-forget or run-and-wait, broadcast or per-pane commands, ShellManaged/CallerManaged/RawInteractive profiles. Use AFTER cmux-fanout has built a grid, when you want to run/administer commands across those existing panes concurrently or steer agent REPLs in them. Requires PowerShell 7.1+, key-auth SSH to the Mac, and a pane map written by cmux-fanout. NOT for building panes (use cmux-fanout), local Windows grids (use psmux-connector), or in-process parallelism (use the Task tool).
95%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Drives already-running cmux panes on the remote Mac that cmux-fanout built. fanout
builds the grid and writes a pane-map JSON; this skill reads that map and injects work into
the panes — one Windows-side runspace per pane, every remote touch a ~258 ms SSH call.
Lifecycle: cmux-fanout (build grid + map) → cmux-connector (inject / administer) →
cmux-fanout teardown.ps1 (free resources).
../cmux-fanout/setup.md), plus a pane map written by a fanout build.CmuxRpc.psm1 from the fanout skill via $env:CMUX_LIB_DIR
(default: the sibling cmux-fanout\lib\).$connect = "<...>\__solutions\cmux-connector\connect.ps1"
# Broadcast one shell command to every pane, wait, capture stdout/stderr/exit:
& $connect -WorkspaceName fanout-... -Command 'git pull; npm test' -Wait
# Per-pane commands (aligned to targeted panes in ascending index order):
& $connect -MapFile <map.json> -Commands @('build A', 'build B') -Wait
# Steer claude REPL panes (verbatim prose, fire-and-forget):
& $connect -MapFile <map.json> -Profile RawInteractive -Command 'explain this error'
# Subset targeting: drive SOME panes, leave the rest alone:
& $connect -MapFile <map.json> -PaneIndex (0..3) -Profile RawInteractive -Command 'continue'
# Agent task with self-written completion sentinel:
& $connect -MapFile <map.json> -Profile CallerManaged -Wait -TimeoutSec 900 `
-Command 'Do X, then write your result JSON to {{OutDir}}/result.json'-Profile)| Profile | What the connector does | -Wait? |
|---|---|---|
| ShellManaged (default) | Stages your command as payload.sh + a capture wrapper cmd.sh on the Mac (one mkdir -p && cat ssh call each, bytes on stdin — nothing long is ever typed into a pane); the pane runs sh <dir>/cmd.sh; stdout/stderr/exit land in a remote GUID run dir and are fetched back on completion | Yes — full capture |
| CallerManaged | Payload typed verbatim ({{OutDir}} substituted with the remote run dir); YOUR payload/agent must write <OutDir>/result.json | Yes — sentinel-driven |
| RawInteractive | Payload typed verbatim, no run dir. -Wait rejected unless you pass -CompletionSentinel <remote path> | No by default |
Status: done means SUBMITTED, nothing
more. Completion evidence is the files your payload writes.-MaxTypedChars, default 4096). For long prose, use
ShellManaged, or stage the text to a Mac-side file yourself and type a short pointer.-MapFile <path> | -WorkspaceName <name> (+ -MapRoot) — locate the pane map.-Command <s> (broadcast) | -Commands <s[]> (per-pane) | -Map @{<index>='<cmd>'}.-PaneIndex <int[]> — subset selector; composes with all payload forms, which then only
cover the selected subset. Unknown indices fail before send.-Wait, -TimeoutSec (default 600), -PollSeconds (default 2), -CompletionSentinel.-SkipMissing — proceed with matched/alive panes when some are missing/dead/extra
(default = fail-before-send).-RecoverContextLimit — opt-in, RawInteractive/CallerManaged only: detect Claude's
Context limit reached · /compact or /clear banner (-ContextLimitPattern to override),
send /clear, wait for -ReadyPattern (default for shortcuts) within
-RecoverTimeoutSec (60), re-send ONCE. The one sanctioned exception to
"submitted work is never auto-retried".-SshConcurrency — gate width override (default: sshConcurrency from cmux-hosts.json,
10). Evidence-gated by smoke 08; the gate auto-degrades to serial on socket-refusal
patterns (future operations only — nothing is ever replayed).-ResultRoot — local mirror root for fetched results (default %TEMP%\cmux-connector).One object per targeted pane:
{ Index, SurfaceRef, Profile, Status, RunGuid, OutDir, RemoteOutDir, Started, Ended, ExitCode, Error },
Status ∈ done | failed | timedout-unknown | recovered-context-limit | context-limit-wedged.
OutDir = local fetched copies (stdout/stderr/exit/result.json); RemoteOutDir = the Mac-side
GUID run dir (~/.cmux-connector/<ws>/<pane>/<guid>). A connect-summary.json is written next
to the pane map. Timeout ⇒ timedout-unknown — the remote command may still be running; it is
NEVER auto-retried.
Before anything is sent: the manifest workspaceRef must exist live AND carry the manifest's
workspaceName; the live tree must contain every manifest surface with NO extras (structural
match); every targeted surface must answer a read-screen probe. fanout's default names carry
a random suffix, so a same-name collision requires deliberately reusing a custom
-WorkspaceName — which weakens identity to name+structure equality (documented residual).
CallerManaged recovery reuses its run dir only because the banner precedes any execution.
-Wait (torn down), pending panes resolve to
failed/WORKSPACE_GONE — not a silent timeout.(host, workspace) lock across validate→stage→send,
released before polling — fanout builds/teardowns cannot interleave with submission.CMUX_SHAPE from the tree parser means cmux's --json drifted: run fanout's
tests\smoke\03-discovery.ps1 and fix ONLY the key list in Get-CmuxTreeSurfaces.
Smoke 06 gates the parser against the real Mac before identity validation is trusted.CMUX_GATE/CMUX_TRANSPORT/CMUX_OP/CMUX_SHAPE (shared), SSH_OP
(remote shell exited nonzero), CONNECT_VALIDATION (manifest/targeting/profile rules).
Entry scripts emit {"error":"..."} JSON + exit 1.Import-Module Pester -MinimumVersion 5.5 -Force
Invoke-Pester __solutions\cmux-connector\tests\CmuxConnect.Tests.ps1 # no Mac needed
# Live battery (needs the Mac; run in order; 08 is the concurrency evidence gate):
& tests\smoke\06-connect-echo.ps1
& tests\smoke\07-connect-claude.ps1
& tests\smoke\08-concurrency.ps1
& tests\smoke\09-recovery.ps1& "<...>\cmux-connector\cleanup.ps1" -OlderThanHours 24 # local + remote run dirsDoes NOT touch workspaces — teardown is cmux-fanout's job.
KennethJefferson/cmux_test
a4e208e
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.