The /amux skill

The Amp skill for declaring native multi-directory runners and installing their systemd or launchd services. Amp owns runner execution, updates, and task coordination; Amux keeps reproducible machine configuration.

Install globally

npx skills add zainfathoni/amux --skill amux --global

Experimental provider skills are separate, explicit-only installs:

npx skills add zainfathoni/amux --skill amux-tycho --global
npx skills add zainfathoni/amux --skill amux-claude --global
npx skills add zainfathoni/amux --skill amux-pi --global

Installing a provider skill does not select or authorize it. Core /amux defaults to native Amp. To opt into links from a clean local checkout without having the installer update that checkout:

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

Core concepts

• Runner profile: named configuration for one native amp --no-tui process.
• Startup directory: the stable directory from which Amp starts and remembers dynamic directory additions.
• Served directory: any existing Git or non-Git directory made available by the runner.
• Runner service: a generated systemd user service or launchd agent that executes Amp directly.

Common requests

Example profile

{
  "schema_version": 1,
  "runners": [{
    "name": "main",
    "runner_id": "laptop-main",
    "startup_directory": "/home/me/Code",
    "discover_dirs": true,
    "dirs": ["/home/me/Obsidian/Vault"]
  }]
}

amux --dry-run runner service install
amux runner service install
amux runner service doctor

Current directory and runner IDs

cd ~/Code/project-runner
amux runner pin -w project -c -i laptop-project
amux runner launch -c

# Preview and apply a live native-ID change
amux --dry-run runner pin -w project -c \
  -i laptop-project-new --restart
amux runner pin -w project -c \
  -i laptop-project-new --restart

After a command, -c means --current-dir, exactly equivalent to --workdir .. It does not inspect the tmux pane; the older --current selector does. Before a command name, contextual -c <path> still means global --config-dir <path>, so reusable instructions should spell out --config-dir.

A stopped runner remains stopped when its ID changes. Repeating the same ID is a no-op. A live change without --restart rejects unchanged. With --restart, Amux requires exact local ownership and executor evidence before replacement; it does not guarantee uninterrupted active thread execution.

Safety boundaries

• Prefer --dry-run before mutation and --json when parsing output.
• runner park stops an exact owned process but keeps its row.
• runner unpin removes one exact binding only after proving its runner absent; it never stops a process.
• runner remove is unavailable and fails closed. Missing-workdir runner reconcile also retains the row and rejects.
• runner teardown requires a fresh digest, preserves the branch, and rejects primary, dirty, detached, locked, prunable, ambiguous, or otherwise unsafe worktrees.
• Runner operations never own or archive remote Amp threads.

Runner-ID replacement verifies the exact owned tmux pane, Amp process, executable, arguments, and canonical workdir before mutation. If proof is incomplete, Amux rejects rather than guessing.

Activation and maintenance

amux runner service install generates one service per profile. systemd or launchd executes Amp directly and keeps it running; Amux is not a resident supervisor. launchd starts at GUI login. Starting a systemd user service without login requires lingering configured outside Amux. Amp owns update and idle-restart behavior, subject to its installation and settings.

The old per-workdir registry, tmux lifecycle, and scheduled Amux maintenance remain available only during migration. Do not use them for new profiles.

Skill-only workflows

/amux health performs read-only runner diagnostics. /amux sprawl fans independent work out through native Amp child threads only. /amux sweep is a protected, one-time, read-only historical inventory and requires separate exact owner authorization; loading the skill does not authorize it.

Legacy status and replacements

Removed, not merely deprecated: worker, generalized spawn/adoption, shelf, top-level worker teardown, group, worker-report, callback, deadline, and finish commands are no longer supported. Do not run old syntax or mutate historical stores.

• Use native Amp child creation and parent/reply routing instead of spawn, groups, reports, callbacks, and deadlines.
• Use native Amp archive state instead of shelves.
• Use native thread lifecycle separately from machine-local runner teardown.
• Treat old worker and coordination files as inert evidence: do not migrate, rewrite, drain, or delete them.
• Use /amux-tycho only when explicitly requested; its separate receipt bridge is not the removed report mechanism.