zainfathoni/amux

amux

amux is the declarative machine-local configuration and activation layer for native Amp runners. Amp owns multi-directory serving, dynamic directory additions, remote work, and its native update behavior. Amux records how each runner should start and installs its systemd user service or launchd agent.

Prefer one native runner profile per machine. A profile can discover Git repositories beneath a code root while explicitly serving unrelated non-Git directories such as an Obsidian vault. Define a second profile only when you need a separately identified or isolated native runner.

Native runner profiles

Create ~/.config/amux/native-runners.json:

{
  "schema_version": 1,
  "runners": [
    {
      "name": "main",
      "runner_id": "laptop-main",
      "startup_directory": "/home/me/Code",
      "discover_dirs": true,
      "discover_depth": 3,
      "dirs": [
        "/home/me/Obsidian/Vault",
        "/home/me/.dotfiles"

"remotecontrolterminal": true } ] }

Preview, install, and inspect the services:

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

On Linux, Amux installs one `com.zainfathoni.amux.runner.<name>.service` systemd user unit per profile. On macOS, it installs the equivalent LaunchAgent. Each artifact executes the resolved Amp binary directly with `--no-tui`, the stable runner ID, discovery and explicit-directory flags, and optional remote terminal access. Amux records artifact digests and refuses to replace or remove unrecognized files. Installation also rejects a case-insensitive runner-ID collision with a retained `runners.tsv` row and rejects installed or activation-pending self-owned legacy maintenance; it does not rewrite either legacy record.

Dynamic `amp runner dirs add|list|remove` remains available. Amp persists those additions against the profile's stable startup directory; keep declarative machine-critical paths in `native-runners.json` and use dynamic additions for local, temporary choices.

When `discover_dirs` is true, Amp scans two levels beneath `startup_directory` by default. Set `discover_depth` from 1 through 10 when repositories are nested more or less deeply; for example, an owner/repository layout beneath a code root uses the default depth 2. Amux requires discovery to be explicitly enabled when a depth is configured. Use `dirs` for repositories or non-Git directories outside the discovery root.

During coexistence, use a dedicated persistent startup directory, for example `~/.local/share/amux/native-main` (create it first), set `discover_dirs` to `false`, and list the existing workdirs explicitly in `dirs`. Amp can reject a second headless instance starting in the same directory even with a different runner ID. Installation rejects startup directories matching retained legacy TSV workdirs, including parked rows; native profiles must also have distinct startup directories. Symlink aliases are resolved for these checks. Sharing explicit served directories is allowed; it does not migrate existing threads. A successful `service doctor` is a point-in-time check, not proof of sustained health.

The previous per-workdir registry, tmux lifecycle, and scheduled Amp updater remain available during migration, but they are no longer the destination architecture. Native Amp updates a running runner itself. Self-owned legacy maintenance cannot be installed or run while native runner services are installed or activation pending. External or package-manager update ownership remains an explicit compatibility-tail option.

### Primary-service rollout recovery companion

Operators who need a recovery channel while replacing the primary native runner service may retain one narrowly scoped legacy runner binding per host. Use <host-maintenance for both its workspace and runner ID, bind it to the canonical Amux checkout, and keep it parked when no rollout or recovery is in progress. Launch it on demand with the bare amp --no-tui --runner-id <host-maintenance shape produced by amux runner launch. Do not add discovery, explicit directory, or remote-terminal flags, do not declare this runner in native-runners.json or runner-services.json, and do not configure systemd, launchd, or login automation to launch it automatically.

Before a primary-service rollout, inspect the exact row, dry-run the launch, and verify that the detached tmux runner has the expected canonical workdir, argv, and a process group independent from the primary service. If an obsolete row owns that workdir and its runner is positively absent, migrate it only through supported dry-run-first runner unpin then runner pin operations; never edit runners.tsv, tmux, or PID markers manually. Keep the companion live through primary replacement, verify both runners with runner list and runner doctor, then dry-run and park the companion again. This is an on-demand replacement-survival channel, not a second native profile, an always-on service, a general delegated-work topology, or reboot persistence.

For cutover, first disable any login automation that invokes bare amux or amux launch --all. Give native and legacy runners distinct IDs, remove self-owned legacy maintenance (or explicitly retain external ownership), install and verify native service coverage, then park → soak → unpin each legacy runner. Include a login or reboot in the soak. Never use runner teardown for this migration: preserve the worktree, and roll back before unpin by removing the native services and relaunching the retained legacy row.

The former worker, spawn/adoption, shelf, group, report, callback, deadline, and finish-authorization commands have been removed. Their historical files are inert compatibility evidence: current commands neither migrate nor mutate them. The protected one-time #360 inventory remains read-only under its existing owner gate. /amux-tycho is a separate receipt bridge and is unaffected by removal of worker reports.

See ADR 0011, which supersedes the retained-host architecture in ADR 0008. ADR 0010, ADR 0009, and the disposition ledger remain migration context.

Website: amux.zainf.dev · Skill guide: amux.zainf.dev/skill/

Install

Requirements: Amp CLI. Legacy per-workdir lifecycle additionally requires tmux. Building from source requires the Go version in go.mod.