amux

amux (short for agent multiplexer) is a tiny CLI that keeps your local AI/code agents organised inside tmux. Launch, attach, detach, and remove agent sessions with one consistent interface that works across shells.

Features

• Works with multiple sessions per agent (e.g. --name review-123)
• Understands built-in agent commands (codex, claude, gemini) out of the box
• Respects CA_AGENT_CMD_<NAME> environment overrides and --cmd/--params
• Provides status, attach, detach, start, and remove subcommands

Requirements

• tmux installed and available on PATH (v3.0+ recommended).
  • macOS: brew install tmux
  • Debian/Ubuntu: sudo apt-get update && sudo apt-get install tmux
  • Nix: nix-env -iA nixpkgs.tmux

Note on Ghostty over SSH:

• If your $TERM is xterm-ghostty and the remote host lacks Ghostty's terminfo, tmux may fail with "missing or unsuitable terminal: xterm-ghostty". To improve defaults, amux automatically runs tmux with TERM=xterm-256color in this case. If you prefer native Ghostty terminfo, install it on the remote (see https://ghostty.org/docs/help/terminfo) and keep $TERM=xterm-ghostty.

Installation

cargo install amux

Or build from source:

git clone https://github.com/hewigovens/amux
cd amux
cargo install --path .

Usage

# List running agent sessions
amux status

# Launch the default codex agent (short flag or positional shortcut)
amux start codex
amux start -a codex

# Launch a second codex session with extra params
amux start codex -n review-123 -p "--mode review"

# Attach to an existing session (start it automatically if absent)
amux attach codex -n review-123 -s

# Detach all clients from a session
amux detach codex -n review-123

# Remove the tmux session entirely
amux rm codex -n review-123

Custom agents

To register additional agents, set environment variables before running amux:

export CA_AGENT_CMD_myagent="my-agent-binary --flag foo"

You can also bypass configuration per command with --cmd and append extra arguments with --params.

License

Licensed under the MIT license.