amux-tools — NUILab Agentic AI

Setting up a new machine? Start from the repo

These commands live in a public git repository, amux-nui-public (opens in new tab) , which runs on Linux, macOS and Windows and adds a setup layer: setup/bootstrap installs what a machine is missing, amux-config manages the machines you drive, and amux-doctor tells you whether it all actually works.

Start from Set up amux on Linux . This page covers the download package and what is inside it.

amux gives you start / stop / attach / ls on one machine. amux-tools adds the things you reach for once you actually live in those sessions: driving another machine’s sessions, finding the right past conversation, recovering a session stuck at a login prompt, and jumping between sessions without typing names.

They are small bash scripts that shell out to amux (one also reads the agent’s transcript files). Nothing here replaces amux — install amux first.

Install

Download the package, check it, install it:

curl -fsSLO https://agenticai.nuilab.org/dl/amux-nui-public.tar.gz && tar xzf amux-nui-public.tar.gz && cd amux-nui-public-0.2.1 && ./install.sh

install.sh symlinks bin/* into ~/.local/bin (override with BINDIR=/usr/local/bin ./install.sh), so updating the files updates every command in place. Remove them again with ./install.sh --uninstall.

Verify the download first if you like — checksums are published next to it. --ignore-missing checks only the file you actually downloaded (the list covers both tarballs):

curl -fsSLO https://agenticai.nuilab.org/dl/SHA256SUMS && shasum -a 256 -c --ignore-missing SHA256SUMS

Download
`amux-nui-public.tar.gz`	Always the current release.
`amux-nui-public-0.2.1.tar.gz`	Pin an exact version.
`SHA256SUMS`	Checksums for both.

Prefer git? The repo is public, and a git pull updates every command through the symlinks:

git clone https://git.nuilab.org/f.ortega/amux-nui-public.git && cd amux-nui-public && ./install.sh

The repo deliberately ships only the companion commands — the amux session manager itself is a separate install (amux ). It also ships two checks you can run yourself: tools/audit-clean proves the tree contains nothing machine-specific or private (add --history to sweep past commits too), and tools/selftest exercises every command in a sandbox without touching your real ~/.amux.

Requirements

tmux, python3, git, amux on your PATH, and a coding agent that amux drives (for example Claude Code ). ccjump uses fzf when present and falls back to a plain menu without it. amux-tabs is macOS / iTerm2 only. Everything else works on macOS and Linux.

What’s in it

Command	What it’s for
`amux-remote BOX …`	Drive another machine’s amux over its REST API — `ls`, `attach`, `peek`, `send`, `start`, `stop`, `info`, `curl`.
`amux-config`	Add, inspect, test, and remove the machines you drive — writes the mode-600 configs below and fetches each token without ever printing it.
`amux-doctor`	Is this machine actually set up right? Runs the real operations amux depends on and reports what worked, with the fix for anything that didn’t.
`amux-ls`	This machine’s sessions in the compact one-line-per-box form (`-v` for detail).
`amux-all`	One session view across every configured machine, compact grid per box.
`amux-up [MACHINE] NAME`	Ensure a session is started and attach to it, in one command — one argument resolves locally, `amux-up MACHINE NAME [flags]` for a remote (flags are forwarded to the start).
`ccjump`	Fuzzy-pick any active session — local or remote — and jump straight to it.
`amux-convos NAME`	List a session’s past conversations with a snippet of each, and resume the right one.
`amux-rename OLD NEW`	Rename a session everywhere at once — files, live tmux session, dashboard — keeping its history.
`amux-reauth NAME`	Fix a session stuck at `401 / Please run /login` — no browser, works over SSH.
`check-claude-auth`	Read-only: will sessions on this machine authenticate, and if not, why?
`amux-tabs NAME…`	Open one terminal tab per session (macOS / iTerm2).

Every command answers -h, so amux-remote -h, ccjump -h, and the rest print their own usage.

Point it at a machine

The multi-machine commands (amux-remote, amux-all, amux-up, ccjump) read one small config file per machine, named after the box. amux-config creates and maintains those files, so you never hand-write one:

amux-config add <box> --host <address>    # add a machine (prompts for anything it still needs)
amux-config list                          # the boxes you have configured
amux-config show <box>                    # one box's settings — the token is never printed
amux-config test <box>                    # prove the box answers and the token works (--all: every box)
amux-config edit <box>                    # open its file in $EDITOR
amux-config rename <old> <new>            # rename a box
amux-config remove <box>                  # delete a box's config
amux-config token <box>                   # re-fetch just the token, e.g. after a rotation

There are two ways to hand it the token, and both keep it quiet: --from-ssh (the default) reads it over SSH from the box’s ~/.amux/auth_token and pipes it straight into the config file, and --token-stdin reads it from standard input for when SSH is not an option (amux-config add mybox --host h --token-stdin < token.txt). There is deliberately no --token flag — a token on the command line is visible to every user on the machine via ps and lands in your shell history.

What it writes — one mode-600 file per box:

# ~/.amux/remotes/<box>.env    (chmod 600 — it holds that machine's dashboard token)
AMUX_URL=https://<box>:8822                 # that machine's amux dashboard
AMUX_SSH_HOST=<box>                          # host to ride for `attach`
AMUX_TOKEN=<that machine's dashboard token>  # from its ~/.amux/ — never commit this

Then name the box first on every call. A bare amux-remote lists the boxes you have configured:

amux-remote                       # which boxes are configured?
amux-remote myhub ls -c           # that box's sessions, compact grid
amux-remote myhub peek webapp     # recent output, without attaching
amux-remote myhub attach webapp   # attach over SSH

The token is a password

A machine’s amux token is the password to its dashboard and its remote API. Keep each ~/.amux/remotes/*.env mode 600, never commit one, and never paste a token into a script or a chat.

Remote start attaches only when interactive

From a terminal, amux-remote BOX start NAME starts the session on that box and then attaches you over SSH. From a script, a pipe, or with --no-attach, it starts only and prints the attach command instead — so automation never grabs your terminal. amux-up BOX NAME is the same start-then-attach in one word-order-matching command, and extra flags are forwarded to the start, e.g. amux-up BOX NAME --provider opencode.

Where to go next

Set the machines up end to end: Connect machines .
Every command in one table: amux cheat sheet .
The session manager itself: amux .

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