The /amux skill

The bundled skill gives agents a precise vocabulary for local Amp lifecycle. It separates configuration, local execution, and remote thread state—and reserves higher-level health, sprawl, and finish behavior for safe skill orchestration.

Install globally

npx skills add zainfathoni/amux --skill amux --global
# optional experiments only:
npx skills add zainfathoni/amux --skill amux-claude --global
npx skills add zainfathoni/amux --skill amux-pi --global
npx skills add zainfathoni/amux --skill amux-tycho --global

skills.sh is the primary installation path. A machine with a clean local main checkout may opt into installer-managed links for all four skills:

AMUX_REPO="$HOME/Code/GitHub/zainfathoni/amux"
git -C "$AMUX_REPO" pull --ff-only origin main
curl -fsSL https://amux.zainf.dev/install.sh | AMUX_SKILLS_SOURCE="$AMUX_REPO" sh

The installer does not update the checkout. It preserves replaced installations as timestamped backups and creates absolute links under ~/.agents/skills. Pull again and reload Amp (or start a new thread) after main changes. Core /amux stays thin: only an already-bound pre-cutover Amux worker whose persisted provenance proves it drain-eligible reads reference/contract-v1.md; only an existing pre-cutover deadline uses reference/deadline-v1.md. Native-created work receives neither. Experimental Tycho/Claude/Pi routes are separate skills.

Terminology

• Worker: interactive TUI client identified by canonical Amp thread ID.
• Runner: non-interactive amp --no-tui client identified by canonical workdir. It enables remote work but does not own remote agent threads.
• Workspace: worker/runner lifecycle group represented by one same-named tmux session.

Top-level list, launch, park, restart, remove, doctor, and reconcile aggregate both modes. The worker and runner namespaces narrow scope. Pin/unpin always require a mode namespace.

Amux work groups, reports, callback leases, deadlines, and finish authorization are pre-cutover compatibility/drain state only. Native child threads use native parent/reply routing and acquire none of that lifecycle.

Trigger routing

Skill-only health

/amux health aggregates workers and runners by default, with optional workspace and mode filters. It is not a CLI command.

• Workers: match configuration, tmux placement, workdir, thread, and an idle interactive Amp pane; send one tokenized read-only prompt only when safe.
• Runners: never send input; verify canonical workdir, ownership, generated window, and the exact amp --no-tui process.

A worker timeout means candidate stale, not safe to replace. Health never mutates, launches, restarts, removes, reconciles, or spawns.

Skill-only sprawl

/amux sprawl uses authenticated native Amp creation. Before side effects, the agent reads every issue and native dependency relationship, checks likely file/API overlap, and sequences anything dependent or conflicting.

Task: <bounded issue task and why it matters>
Acceptance criteria: <observable outcome and scope boundary>
Relevant context and constraints: <files, repository, safety limits, settled decisions>
Validation: <checks to run>
Expected result: complete the task and reply to the parent with changed files, checks, and blockers.

Every accepted issue gets one narrow assignment and dedicated branch/worktree. Physical worktrees require the exact live runner rooted at that canonical workdir; there is no Orb/runner fallback. Native-created children remain unmanaged by Amux: no worker, group, report, callback, shelf, or pane state. With known linked ChatGPT routing and target-mode availability, use Low for small mechanical work, Medium for ordinary implementation, or High for difficult architecture, debugging, or review; otherwise use Medium. Ultra and special modes remain owner-explicit.

Native child-thread coordination

New coordination uses Amp's authenticated create_thread, parent/child identity, reply routing, messaging, and waiting. Each child is created directly on its exact executor/workdir and receives only a lean task prompt. No contract path, receipt, report, callback, adoption, group, deadline, finish authorization, or other Amux lifecycle state is created for it.

Task: <bounded coordination task and why it matters>
Acceptance criteria: <observable outcome and scope boundary>
Relevant context and constraints: <files, repository, safety limits, settled decisions>
Validation: <checks to run>
Expected result: complete the task and reply to the parent with changed files, checks, and blockers.

Existing pre-cutover durable groups, reports, callback leases, deadlines, and finish authorization remain compatibility/drain-only only when exact persisted provenance proves their already-bound identity and exact allowed next transition. Contract and lifecycle instructions stay inside that boundary. Do not add a replacement member or new task merely to finish old state.

Exit 2 lock contention writes nothing: wait, then retry the identical operation and report ID. Missing, stale, recycled, duplicate, reordered, and restarted callbacks fail closed or recover from durable state. Never retry into a suspected busy composer; inspect pending/history directly. Never guess a pane, force-delete, auto-release, or infer finish from a wake-up.

Existing pre-cutover report deadlines retain their exact size and generation: Small 30m, Medium 1h, or Large 2h; XL should already have been split. Stale is 15m, review warns after 10m, demonstrated external CI alerts after 20m, and authorized finish alerts after 10m. Only demonstrated external waits pause active time. One existing extension may add at most half the original budget under a new generation; expiry is diagnostic only. Native-created work gets no new Amux deadline state. The coordinator owns one nearest-deadline queue, not a timer process per child; never edit reports.json directly.

Skill-only finish

/amux finish is a drain workflow for an existing Amux worker, not a lifecycle automatically attached to native-created work. It verifies merge and a clean worker worktree, then fails closed if runner configuration or diagnostics show that the worktree has acquired runner ownership. It never removes or unpins that runner implicitly.

After updating main, finish removes the clean worktree without force and preserves squash-merge branch safety: git branch -d first; no automatic -D. Worker teardown runs last. A ready callback never authorizes cleanup; finish requires independently verified merge and explicit authorization.

Agent contracts

• Use long canonical selectors and current contextual help.
• Use --dry-run before mutation and --json for parsing.
• JSON v1 separates planned, successful, skipped, and failed.
• Exit 2 rejects before mutation; exit 1 may represent partial runtime success.
• Ordinary new threads are created with native create_thread, lean task prompts, and native parent/reply routing only.
• Contract and lifecycle instructions apply only to proven pre-cutover Amux-managed drains.
• The projectless physical-host exception requires exact owner authorization and fails closed without retry or fallback.
• Health, coordinator orchestration, sprawl, and finish are not amux subcommands.