amux cheat sheet — NUILab Agentic AI

A quick lookup for the commands in the guides . For what they mean and how to install the pieces, follow the links.

Sessions (amux )

Command	Does
`amux register NAME --dir DIR [agent flags]`	Define a session (no start).
`amux start NAME`	Start it, or attach if already running.
`amux exec NAME --dir DIR [agent flags]`	Register and start in one step.
`amux attach NAME`	Attach. Detach with `Ctrl-b` then `d`.
`amux ls`	List sessions; `*` = running.
`amux ls -c`	Compact one-screen grid. (`amux ls \| less -R` pages the full list.)
`amux peek NAME [lines]`	Recent output, without attaching.
`amux send NAME "text"`	Send a line of input.
`amux stop NAME` / `amux rm NAME`	Stop / remove.
`amux-rename OLD NEW`	Rename a session everywhere — files, live tmux session, dashboard — keeping its history. `-n` = dry run.
`amux serve PORT --bind 127.0.0.1,IP`	Dashboard (private bind only).

Anything after the name on register / exec goes straight to the coding agent — use its full flag names, for example --model opus, --continue, --append-system-prompt "…".

Providers (amux )

A session runs one of four agents: claude, codex, gemini, or opencode (the local-model lane — amux refuses to point it at a hosted API).

Command	Does
`amux register NAME --dir DIR --provider P`	Persist the provider with the session (`exec` too).
`amux provider NAME`	Show a session’s provider.
`amux provider NAME P`	Change it (session must be stopped).
`amux start NAME --provider P`	One-shot override, not persisted.
`amux-remote BOX exec NAME --provider P`	Same, on another machine.
`amux-remote BOX provider NAME [P]`	Show / change on another machine.

Conversations (guide )

A session accumulates several past conversations. Pick the right one to resume instead of guessing with --continue (which grabs the newest).

Command	Does
`amux-convos NAME`	List the session’s past conversations, newest first, each with a snippet of the last thing you said.
`amux-convos NAME -n N`	Only the top N. `--less` pages; `--full` shows the whole snippet.
`amux-convos NAME --resume N`	Stop the session and restart it on the Nth listed conversation.
`amux-convos NAME --cmd N`	Just print the `amux start NAME --resume UUID` line (don’t run it).
`amux start NAME --resume UUID`	Start a session on a specific conversation by id.

Auth recovery (guide )

Command	Does
`check-claude-auth`	Read-only: is auth on this machine healthy, and if not, why?
`amux-reauth NAME`	Fix a session stuck at a real `401` — probes the token directly, clears a shadowing stored login, restarts. No browser.
`amux-reauth --all`	Same, for every session parked at a real `401`.
`claude auth logout`	Remove a stored browser-login that shadows the durable token.

amux-convos, amux-reauth, check-claude-auth and friends are in the amux-nui-public repo (opens in new tab) (./install.sh links them onto your PATH) — see amux-tools .

The two scripts (guide )

Command	Does
`amux-run NAME [agent flags]`	Start NAME in the current directory, detached. Re-run to restart with new flags.
`amux-attach NAME`	Attach to NAME.

cd ~/code/myapp
amux-run myapp --model opus --continue    # start (or restart), detached, resuming last conversation
amux-attach myapp                          # look in; Ctrl-b d to step out

tmux keys

amux sessions are tmux sessions, so the usual keys work after the Ctrl-b prefix:

Keys	Does
`Ctrl-b` `d`	Detach (leaves the session running).
`Ctrl-b` `[`	Scroll / copy mode (`q` to exit).
`Ctrl-b` `?`	List all key bindings.

Cross-machine bus (hcom )

Command	Does
`hcom relay new --broker mqtt://HOST:1883 --password '…'`	Create the group; prints a connect token.
`hcom relay connect TOKEN --password '…'`	Join the group on another machine.
`hcom relay on`	Turn syncing on.
`hcom relay daemon start`	Start the background daemon.
`hcom relay`	Show status and the group key.
`hcom relay token`	Reprint the connect command for adding machines.

Machines (amux-config )

One mode-600 config file per machine you drive; amux-config writes and maintains them.

Command	Does
`amux-config add BOX --host H`	Add a machine. Token arrives via `--from-ssh` (default, read over SSH) or `--token-stdin` — never on the command line.
`amux-config list` / `show BOX`	List boxes / show one box’s settings (the token is never printed).
`amux-config test BOX` / `--all`	Prove a box answers and the token works.
`amux-config edit BOX`	Open its config in `$EDITOR`.
`amux-config rename OLD NEW` / `remove BOX`	Rename / delete a box’s config.
`amux-config token BOX`	Re-fetch just the token, e.g. after a rotation.
`amux-doctor`	Is this machine set up correctly? Runs the real operations, not version checks.

Remote control (guide )

Command	Does
`amux-remote`	List the configured boxes (a box is always named first).
`amux-remote BOX ls`	List that box’s sessions, under a header naming it (host, URL, running counts).
`amux-remote BOX ls -c`	Compact grid, same shape as `amux ls -c`. (`--bare` drops the header, for embedding.)
`amux-remote BOX peek NAME`	Recent output from a session on BOX.
`amux-remote BOX start NAME [flags...]`	Start it on that box, forwarding one-shot launch flags (e.g. `--provider opencode`) — and, when run from a terminal, attach right away (`--no-attach` or piping skips that and prints the attach command instead). For claude, resume is automatic, so `--continue` is rarely needed.
`amux-remote BOX stop NAME`	Stop it. Takes no flags — extras error loudly.
`amux-remote BOX attach NAME`	Attach to a session on BOX over SSH.
`amux-up BOX NAME [flags]`	Start it on that box (flags forwarded) and attach — one command, same word order as `amux-remote`. `amux-up BOX:NAME` still works.
`amux-all`	Every machine at once — compact grid per box (local first), `-v` for verbose.
`ccjump`	Fuzzy picker → jump to any active session, local or remote.

Gotchas

You do	What happens
`amux-remote BOX start NAME` from a script and expect it to attach	Interactive runs attach; non-TTY runs (scripts, cron, pipes) start only and print the attach hint. Force the old behavior with `--no-attach`.
`amux start NAME --continue` on an already-running session	`start` short-circuits to attach and silently drops `--continue`.
See `Please run /login` · `401` after attaching/resuming	It may be replayed transcript history from an earlier auth outage, not a live failure. Send a message — if it replies, auth is fine. Details .
A new message 401s in every session at once	An expired stored browser-login is shadowing your durable token. `claude auth logout`, restart sessions (`amux-reauth --all`). Details .
Validate auth with `claude -p` and it says OK, but sessions still 401	`claude -p` silently falls back between credential stores. Use `check-claude-auth` (direct probe) or an end-to-end message instead.

Source: content/reference/amux-cheatsheet.md · maintained in the nuilab-agenticai repository.