amux-nuilab

Companion tooling for amux — the session manager that runs each coding agent in its own tmux session.

amux gives you start / stop / attach / ls on the machine you are sitting at. This adds the things you need once you are actually living in those sessions day to day, and especially once there is more than one computer: configuring machines, seeing every session everywhere, recovering a session over SSH, and finding the right past conversation.

Works on macOS, Linux, and Windows (WSL, MSYS2, or Git Bash — see docs/windows.md).

Quick start

git clone https://git.nuilab.org/f.ortega/amux-nui-public.git
cd amux-nui-public
./install.sh          # symlinks bin/* into ~/.local/bin
amux-doctor           # tells you what this machine can and cannot do
setup/bootstrap       # installs whatever amux-doctor says is missing

amux-doctor is the one to run first and whenever something is odd. It does not guess: it runs the actual calls amux depends on and reports what worked.

Using one computer

That is all you need. amux works locally, and amux-ls, amux-convos and check-claude-auth work right away. Skip the rest until you get a second machine.

Adding a second computer

On the machine you want to reach:

setup/serve-install

On the machine you want to drive from:

amux-config add desktop --host <address>
amux-config test --all

Details, including how to get a network path between them: docs/remote.md.

Commands

Command	What it does
amux-doctor	Honest report of what this machine can do — tmux calls, auth mode, every configured machine
amux-config	Add, test, edit, rotate and remove the machines you drive. Tokens never touch argv or your history
amux-ls	This machine's sessions, compact grid or verbose
amux-remote	Drive another machine over its REST API — including secure attach, exec, and provider selection
amux-all	Every machine's sessions in one view. Unreachable ones are marked, not hung on
ccjump	Fuzzy-pick any session anywhere and jump straight to it
amux-up	Ensure a session is started and attach to it, local or remote
amux-convos	List a session's past conversations with a snippet of each, and resume the right one
amux-reauth	Fix a session stuck at 401 / Please run /login, with no browser. Works over SSH
check-claude-auth	Whether sessions on this machine will actually authenticate, and why not
amux-rename	Rename a session everywhere at once without losing its context
amux-tabs	One terminal tab per session (macOS / iTerm2)

Every command's -h is its own header comment, so the help cannot drift from the code.

Docs

• auth.md — /login vs long-lived tokens, why browser control only works with one of them, and the both-at-once trap that produces mysterious recurring 401s
• remote.md — connecting machines: VPN, LAN, or SSH tunnel; tokens and rotation
• windows.md — WSL vs MSYS2 vs Git Bash vs Scoop, and what each can actually do
• troubleshooting.md — symptoms, causes, fixes

Patches

Two bugs in upstream amux that have not been fixed there, shipped as anchored edits to the copy on your machine. Nothing upstream is redistributed here.

patches/apply --check     # am I affected?
patches/apply             # fix it
patches/apply --revert    # undo

• running-flag — a gracefully stopped session reports running forever, because the list only checks whether a tmux session exists.
• auto-resume — when the server cannot resolve which conversation to resume it starts a blank one, wiping the session's context. The watchdog restarts sessions on its own, so this destroys work with no obvious cause, and compounds each time.

The patches are idempotent, refuse to apply if upstream has drifted, validate that the result still compiles before installing it, and back up first.

Security

The design rule throughout: a secret never reaches argv, stdout, or your shell history.

• Tokens move over stdin or a mode-600 file. amux-config has no --token flag on purpose — a token on a command line is visible to every user on the machine via ps, and is saved to your history permanently.
• Where a token must be shown, only a four-character prefix and a length are printed. Enough to tell two tokens apart; useless to anyone reading over your shoulder.
• An amux server's token grants full control of every session on that machine. setup/serve-install binds to loopback plus one address you choose, never 0.0.0.0. Expose it on a private network or through an SSH tunnel — never straight onto the internet.

Requirements

• amux (github.com/mixpeek/amux) — setup/bootstrap installs it for you: the Homebrew tap on macOS, otherwise a shallow clone into ~/.local/bin (no sudo). Note that amux is not on PyPI, so pip install amux does not work.
• tmux, python3, and curl or wget
• A coding agent for amux to drive, normally Claude Code

setup/bootstrap detects your platform and package manager — brew, port, apt, dnf, pacman, zypper, apk, winget, scoop, choco, or MSYS2's pacman — and uses whichever is present rather than assuming one.

License

MIT — see LICENSE.

amux itself is a separate project, licensed MIT + Commons Clause. This repository contains only original work and does not bundle any part of it.