tmux

AO uses tmux as the default runtime on macOS and Linux. Each session lives in its own tmux window under a single AO-managed session, and you can attach to any of them interactively.

Install

macOS:

brew install tmux

Debian/Ubuntu:

sudo apt install tmux

Arch:

sudo pacman -S tmux

AO needs tmux 3.2 or newer.

Use

runtime: tmux

No plugin-level config — this is the default on macOS/Linux so you can also omit the key entirely.

How it works

• Every AO-managed process lives in a tmux window inside a per-project tmux session.
• Agents start via tmux send-keys so their output is captured.
• For long commands (>200 characters), AO writes a temp bash script and sources it, because tmux send-keys truncates paste buffers.

Attaching

ao session attach <sessionId>

Or from inside tmux, switch windows manually. You can detach at any time (Ctrl-b d) and AO keeps running.

Troubleshooting

• tmux server not running. ao start launches the server for you; if you killed it, run ao start again.
• Window disappears after agent exits. Intentional — AO cleans up finished windows. The session metadata is archived under ~/.agent-orchestrator/.../archive/.