Przejdź do treści
Biblioteka skilli
AI i agenci · Automatyzacja

cmux-dispatch

/cmux-dispatch

Deleguje zadania do równoległych sesji agentów przez cmux: tworzy powierzchnię, czeka na gotowość, dostarcza prompt i powiadamia o zakończeniu.

Repozytorium
konductor ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
2
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co sprawdzić przed instalacją
  • 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: cmux-completion-hook.sh, cmux-dispatch.sh

Co robi i kiedy

Deleguje zadania do równoległych sesji agentów przez cmux: tworzy powierzchnię, czeka na gotowość, dostarcza prompt i powiadamia o zakończeniu.

Oryginalny opis (EN)

Delegate tasks to parallel agent sessions via cmux. Use when the user asks to delegate, spawn, or run a task in a separate cmux surface with a specific agent. Handles surface creation, readiness polling, prompt delivery, and completion notification.

Jak działa

  1. Runtime Selection
  2. Overview
  3. Usage
  4. Locating cmux-dispatch.sh
  5. Deterministic Script
  6. Completion Detection
  7. Worktree Provisioning for Write Agents
  8. Best Practices
Sekcje z nagłówków SKILL.md, w oryginale · 236 linii, 1 912 słów
Podgląd SKILL.md
---
name: cmux-dispatch
description: Delegate tasks to parallel agent sessions via cmux. Use when the user asks to delegate, spawn, or run a task in a separate cmux surface with a specific agent. Handles surface creation, readiness polling, prompt delivery, and completion notification.
---

# cmux Dispatch

## Runtime Selection

The orchestrator always dispatches via panes. The dispatch script selects the CLI automatically:

- **Claude Code** (`$CLAUDECODE` is set): runs `claude --agent <PREFIX><agent-name> --dangerously-skip-permissions -p "<prompt>"` in the pane, where `<agent-name>` is the exact value passed via `--agent` (e.g. `k-developer`). The script never strips a prefix. `<PREFIX>` is the package-install prefix (e.g. `local-your-package-`), derived by searching `~/.claude/agents/` for any installed agent file ending in `-<agent-name>.md` (local- installs preferred over registry installs, checked as separate tiers). No package name is hardcoded, so this resolves correctly for any installed package. If `~/.claude/agents/` has no match and the skill ships inside a Claude Code plugin whose `agents/` has that agent, the bare name is launched and Claude resolves it to `<plugin>:<agent>`. A qualified `--agent` (`konductor:k-developer`) is launched only if the prefix is this plugin's name (from its `.claude-plugin/plugin.json`) and the plugin ships that agent; anything else is refused as not installed. **`--agent` must be a fully-qualified name.** If it matches 2+ installed agent files within the same tier (e.g. a partial name like `orchestrator` matching both `konductor-mux-orchestrator` and `konductor-cmux-orchestrator`), the script errors and lists the candidates rather than guessing. `--agent` values are also restricted to `[a-z0-9-]+`, optionally prefixed with `<plugin>:`, before any of this runs. A `<PREFIX>` derived from a file name must match `[A-Za-z0-9._-]*`, or the dispatch is refused. Completion is detected via process exit (claude -p exits on task completion); the script then writes the `.done` marker file.
- **kiro-cli** (default): runs `kiro-cli chat --agent <agent-name> ...` in the pane, using the exact `--agent` value passed in — no prefix is added or stripped. Completion is detected via the kiro-cli `stop` hook writing the `.done` file.

## Overview

Spawn agent sessions in cmux surfaces so delegated work is visible, interactive, and course-correctable in real time.

## Usage

Use this skill when:

- User asks you to do ANY implementation, design, QA, documentation, or operations work
- User says "delegate", "spawn", "run this in a new tab/pane", "have X agent investigate"
- User wants parallel work visible in cmux rather than hidden sub-agents
- **NEVER** use `use_subagent` when cmux is available — always use this skill instead

**You MUST immediately run the dispatch script without pre-checking the environment.** The script handles all validation (cmux availability, CMUX_WORKSPACE_ID) and exits with a clear error if anything is missing.

## Locating cmux-dispatch.sh

Run this once. It prints the skill's directory; use that absolute path for
`<CMUX_DISPATCH_DIR>` in every command below. A shell variable doesn't survive to the
next command.

```bash
ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
PROJECT="" CHECKOUT=""
[ -n "$ROOT" ] && [ -f "$ROOT/.konductor/manifest" ] && PROJECT="$ROOT/.konductor/skills/cmux-dispatch"
[ -n "$ROOT" ] && grep -qs '"name": *"konductor"' "$ROOT/.claude-plugin/marketplace.json" && CHECKOUT="$ROOT/skills/cmux-dispatch"
CMUX_DISPATCH_DIR=""
for d in "${CLAUDE_SKILL_DIR}" "${SKILLS_HOME:-$HOME/.konductor/skills}/cmux-dispatch" "$PROJECT" "$CHECKOUT"; do
  [ -n "$d" ] && [ -f "$d/cmux-dispatch.sh" ] && { CMUX_DISPATCH_DIR="$d"; break; }
done
[ -n "$CMUX_DISPATCH_DIR" ] || { echo "ERROR: cmux-dispatch.sh not found; not dispatching" >&2; exit 1; }
echo "CMUX_DISPATCH_DIR=$CMUX_DISPATCH_DIR"
```

If it exits 1, dispatch can't run: tell the user and fall back to the base
orchestrator.

## Deterministic Script

### cmux-dispatch.sh

Spawns a agent session in a cmux tab, split, or workspace.

**Parameters:**

| Flag                  | Required | Description                                                                                                              |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--agent`             | Yes      | Agent name (e.g. `k-developer`) or a plugin-qualified name (`konductor:k-developer`). On Claude Code the install prefix is resolved as described above |
| `--task`              | Yes      | Task prompt to send to the agent                                                                                         |
| `--cwd`               | Yes      | Absolute path to project root — agent starts here                                                                        |
| `--name`              | No       | Tab/workspace title (defaults to agent + task summary)                                                                   |
| `--split right\|down` | No       | Split direction (default: right)                                                                                         |
| `--tab`               | No       | Create a new tab instead of a split                                                                                      |
| `--workspace`         | No       | Create a full workspace instead of a tab                                                                                 |
| `--close`             | No       | Auto-close the tab when the agent finishes                                                                               |
| `--interactive`       | No       | Keep kiro-cli open for human interaction (default: non-interactive)                                                      |

**Examples:**

```bash
# Delegate implementation to developer (split right, default)
bash "<CMUX_DISPATCH_DIR>/cmux-dispatch.sh" \
  --agent k-developer \
  --cwd /path/to/project \
  --task "Implement the user authentication API endpoint"

# Side-by-side split for architecture review
bash "<CMUX_DISPATCH_DIR>/cmux-dispatch.sh" \
  --agent k-architect \
  --cwd /path/to/project \
  --split right \
  --task "Review the DynamoDB table design"

# Auto-close tab when done
bash "<CMUX_DISPATCH_DIR>/cmux-dispatch.sh" \
  --agent k-quality-assurance \
  --cwd /path/to/project \
  --task "Run the full test suite" --close
```

## Completion Detection

Each agent's kiro-cli `stop` hook writes a done file:

- Path: `/tmp/konductor-cmux/<done-key>.done` — `<done-key>` is the surface-derived dispatch key (`DONE_KEY`, from `SURFACE_ID`), not the workspace id. In split/tab mode there is no workspace id at all; in `--workspace` mode the workspace id is recorded inside the file's `workspace_id` field, but the filename itself always uses `DONE_KEY`.
- Format: `{"workspace_id": "...", "status": "done|error", "summary": "..."}`

Poll (glob-free — an unmatched `*.done` glob is a hard error under zsh, which
aborts the whole compound command before `2>/dev/null` can apply):
`find /tmp/konductor-cmux -maxdepth 1 -name '*.done' 2>/dev/null`

Running the dispatch script, polling, and reading result files are orchestrator direct work, as defined in the Orchestrator Direct Work table of `k-orchestrator-routing-rules.md`. Run them yourself; never dispatch them to another surface.

The `summary` field in the `.done` payload is a short status string (and is
literally `"shell fallback"` / `"claude exit"` when the completion hook didn't
run) — not a substitute for the deliverable. Dispatch prompts SHOULD instruct
the child agent to write its full deliverable to a file (e.g.
`/tmp/konductor-cmux/result-<slug>.md`) for the orchestrator to read; use
`cmux read-screen` only as a fallback.

## Worktree Provisioning for Write Agents

**The rule: every write-agent dispatch task must explicitly name the exact
target — never let the agent infer or default.** A silent default is the
actual collision mechanism: two write agents (any agent that edits, creates,
or deletes files) — from the same task or from different tasks — can each
independently default into the same working tree and step on each other:
half-applied edits, index contention, build contamination. This can happen
even when neither dispatch looks "concurrent" on its own. The named target
is one of three legitimate forms:

1. A new dedicated worktree — `wt-<id>` on branch `wt-<id>` (worktree and
   branch share one flat name), for the agent to create.
2. An existing worktree to reuse — `wt-<id>` at `<path>` on branch `wt-<id>`.
3. The shared primary tree, on a named feature branch `<branch>` — a
   deliberate, explicit choice, only for a single sequential write agent
   with no concurrent writer sharing that tree.

**Before dispatch (read-only):** check `.wt-ledger.json` and `git worktree
list` (ground truth over the ledger, which can go stale) and decide which of
the three forms applies for this task.

**`--cwd` points at the shared primary working tree** for every write-agent
dispatch, regardless of which of the three forms is named — a worktree named
under forms 1 or 2 may not exist yet at surface-launch time, and the primary
tree is guaranteed to already be a git repository, so `git worktree
list`/`git worktree add` work there with no extra `cd`. Pass the named
target in the dispatched task instead:

```bash
bash "<CMUX_DISPATCH_DIR>/cmux-dispatch.sh" \
  --agent k-developer \
  --cwd <primary-working-tree> \
  --task "Worktree wt-<id> already exists at <path> — cd in, do not create
          a new one. [OR: No worktree exists for this task — create wt-<id>
          before touching any file.]
          [OR: Work directly on branch <branch> in this shared working tree
          — no worktree for this task.]
          Implement the feature; commit and push the branch you're on; open
          a draft CR to mainline."
```

**Read-only agents** (research, investigation, review) need no worktree
decision at all — they share the primary working tree by default, and
`--cwd` points directly at the shared tree with no target to name.

**Write agent's first action, before touching any file:** if a worktree was
named (forms 1 or 2), independently re-run `git worktree list` (the
orchestrator's read could be stale by dispatch time), then either `cd` into
the existing worktree or provision it — running `$WORKTREE_PROVISION_CMD
wt-<id>` if that variable is set in its environment, otherwise `git worktree
add` (see Provisioning command below). If the shared tree was named (form
3), check out the named branch there.

### Provisioning command

The write agent provisions generically via `git worktree add`, but any
environment that has a more specific worktree tool can override this with
the `WORKTREE_PROVISION_CMD` environment variable. Set it in the
orchestrator's shell before dispatching — `cmux-dispatch.sh` forwards it
automatically into the dispatched surface's command, so no extra flag is
needed:

```bash
# Default (no WORKTREE_PROVISION_CMD set): plain git worktree, landed under
# a worktrees/ folder at the repo root.
# `git rev-parse --show-toplevel` returns the repo root
# (<workspace-root>/<repo>), 1 level below <workspace-root>, so `/..` reaches
# <workspace-root>.
git worktree add -b wt-<id> "$(git rev-parse --show-toplevel)/../worktrees/wt-<id>"

# Override point — set WORKTREE_PROVISION_CMD to substitute a
# project-specific provisioning command. It is invoked as:
#   $WORKTREE_PROVISION_CMD <wt-id>
# and must create (or otherwise make ready) a worktree whose directory
# name / return path corresponds to <wt-id>, landed at
# <workspace-root>/worktrees/wt-<id>.
export WORKTREE_PROVISION_CMD="<your-provisioning-command> --name"
```

This skill documents the hook generically; it does not prescribe what
`WORKTREE_PROVISION_CMD` should be set to in any specific environment —
environment-specific documentation (outside this package) covers that.

**Naming.** Worktree and branch share one flat name, `wt-<id>` (hyphens
only — no slashes). Slashes in a worktree identifier can cause
directory-nesting problems in some worktree tooling (a parent path segment
getting registered as a single entry, masking children).

`git worktree add` checks out at exactly the path given, creating any
missing intermediate directories.

**Sequential handoff** is the reuse case (form 2) above, or continuing on the
same named shared-tree branch (form 3) — a second write agent continuing the
same task gets the same named target in its task, and resumes there.
**Concurrent collaboration on one target is not supported, by design** —
whether that target is a worktree or the shared tree, a maker/checker pair
never shares it; a checker gets its own separate read-only checkout, never
the maker's tree.

This is a **best-effort guardrail, not a hard boundary** — the agent
dispatched into the surface could in principle ignore the named target. Two
things provide harder enforcement after the fact:

- The pre-commit hook (husky/lint-staged, or the equivalent for this
  project) runs inside the tree the agent actually committed from — edits
  made outside the named target simply will not surface in that commit.
- The CR diff at review time shows exactly which files changed; a human
  reviewer catches any file that should not have been touched before merge.

Cleanup (removing the worktree and branch) happens only after the agent's
draft CR has merged, and only with explicit user confirmation — this skill
does not perform cleanup itself.

## Best Practices

1. **`--cwd` is always the shared primary working tree for write-agent
   dispatch** — the dispatched agent acts on whichever target (new worktree,
   existing worktree, or the shared tree itself) is explicitly named in the
   task, as its first action from there; the surface launch never depends
   on a named worktree already existing. Read-only agents also use `--cwd`
   pointed at this same shared primary tree, with no target to name.
2. **Default to non-interactive** — agent processes task and exits
3. **Use --interactive** for tasks needing human review (specs, design review)
4. **Use --split right** for co-visible agents alongside the orchestrator
Pliki w paczce (3)
  • SKILL.md 14 KB
  • cmux-completion-hook.sh 1 KB
  • cmux-dispatch.sh 17 KB

Wersje

W bazie nie ma innych skilli o nazwie cmux-dispatch.

Migawka bazy z 13.11.2026 · wersja paczki e80a4d601296 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100using-cmux
    Steruje terminalem cmux: dzieli panele, uruchamia i zbiera wyniki subagentów, wysyła polecenia, czyta ekran i wysyła powiadomienia.
  • 100mux-dispatch
    Deleguje zadania do równoległych sesji agentów w panelach tmux lub zellij, automatycznie wykrywając używany multiplekser ze zmiennych środowiskowych.
  • 100cmux-team-guide
    Udziela pomocy i wyjaśnień o cmux-team w trybie tylko do odczytu: sposób użycia, pojęcia, referencja poleceń CLI i rozwiązywanie problemów.
  • 100cmux-workspace
    Pracuje wewnątrz bieżącego workspace'u i terminala cmux: panele, powierzchnie i adresowanie gniazda, z automatyzacją niezakłócającą innych sesji.
  • 100cmux-cua
    Steruje aplikacjami macOS przez agenta cmux, ale tylko po wyraźnym poleceniu użytkownika i według jego uprawnień.
  • 100cmux-cloud-vm
    Obsługuje maszyny cmux Cloud z poziomu aplikacji i steruje sesją cmux-tui wewnątrz maszyny.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.