CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

cmux-connector

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).

Quality

95%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

cmux-connector

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).

Prerequisites

  • Everything cmux-fanout needs (PowerShell 7.1+, key-auth SSH, cmux socket gate open — see ../cmux-fanout/setup.md), plus a pane map written by a fanout build.
  • Shared transport: imports CmuxRpc.psm1 from the fanout skill via $env:CMUX_LIB_DIR (default: the sibling cmux-fanout\lib\).

How to run

$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'

Execution profiles (-Profile)

ProfileWhat 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 completionYes — full capture
CallerManagedPayload typed verbatim ({{OutDir}} substituted with the remote run dir); YOUR payload/agent must write <OutDir>/result.jsonYes — sentinel-driven
RawInteractivePayload typed verbatim, no run dir. -Wait rejected unless you pass -CompletionSentinel <remote path>No by default

Usage discipline

  1. Concurrent dispatch is the default. One call covers all targeted panes; each pane has its own runspace. Reserve serial calls for genuine dependencies.
  2. Submission is not completion. Fire-and-forget Status: done means SUBMITTED, nothing more. Completion evidence is the files your payload writes.
  3. Typed payloads are bounded (-MaxTypedChars, default 4096). For long prose, use ShellManaged, or stage the text to a Mac-side file yourself and type a short pointer.

Key parameters

  • -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).

Results

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.

Identity guarantee (what validation proves)

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.

Critical gotchas

  1. Every remote touch is a ~258 ms SSH round-trip; completion polling batches ALL pending panes into ONE ssh call per cycle.
  2. If the workspace disappears mid--Wait (torn down), pending panes resolve to failed/WORKSPACE_GONE — not a silent timeout.
  3. The connector holds the shared per-(host, workspace) lock across validate→stage→send, released before polling — fanout builds/teardowns cannot interleave with submission.
  4. 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.
  5. Error ids: 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.

Tests

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

Cleanup

& "<...>\cmux-connector\cleanup.ps1" -OlderThanHours 24   # local + remote run dirs

Does NOT touch workspaces — teardown is cmux-fanout's job.

Repository

KennethJefferson/cmux_test

Path

__solutions/cmux-connector/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.