amux 0.1.3

tmux session manager for local code agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

# amux

[![CI](https://github.com/hewigovens/amux/actions/workflows/ci.yml/badge.svg)](https://github.com/hewigovens/amux/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/amux.svg)](https://crates.io/crates/amux)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

`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

```bash
cargo install amux
```

Or build from source:

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

## Usage

```bash
# 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`:

```bash
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) license.