Why tmux Is the Foundation

AI coding agents run in terminals and often take a long time to complete tasks. If your terminal closes, the agent dies. tmux solves this by running sessions in the background -- they persist across disconnects, reboots, and SSH drops.

tmux also handles windowing, splitting, and session management natively. It is the standard tool for this kind of work, with decades of stability and a minimal resource footprint.

The Single-Window Workflow

Agent of Empires organizes your tmux sessions into two views:

Agent view: The TUI dashboard showing all sessions, their status, and metadata. Navigate with keyboard shortcuts, add or remove sessions, and jump into any agent.
Terminal view: The actual tmux pane where the AI agent is running. When you select a session in the dashboard and press enter, you drop into the agent's terminal.

Switching between views is a single keypress. You spend most of your time in the dashboard, dipping into individual agent sessions when they need attention.

Keyboard Shortcuts

aoe is keyboard-driven. The core shortcuts:

j / k or arrow keys to navigate sessions
Enter to attach to a session
a to add a new session
d to delete a session
g to manage groups
/ to search sessions
? to view all shortcuts

The interface follows vim-style conventions, so the keybindings feel natural to terminal users. All actions are available without reaching for the mouse.

Session Persistence

Sessions survive everything

Because aoe runs on tmux, your agent sessions persist across TUI closes, terminal closes, SSH disconnects, and system sleep/wake cycles. Reopen aoe and everything is right where you left it.

Because everything runs in tmux, your agents survive:

Closing the aoe TUI
Closing your terminal emulator
SSH disconnects
System sleep/wake cycles

Reopen aoe and your sessions are all there, with current status automatically detected. Long-running agent tasks complete in the background without you needing to keep anything open.

The TUI Layer on Top of tmux

Raw tmux is powerful but requires memorizing session names and switching commands. aoe adds a visual layer:

Dashboard view with real-time status for each session
Session groups for organization
Status detection that shows agent activity without entering each session
Integrated lifecycle for Docker containers and git worktrees

You get the reliability of tmux with the usability of a purpose-built interface.

Getting Started

You need tmux installed on your system. Most Linux distributions include it in their package managers, and on macOS you can install it via Homebrew:

brew install tmux    # macOS
apt install tmux     # Debian/Ubuntu

Then install and run aoe:

curl -fsSL https://raw.githubusercontent.com/njbrake/agent-of-empires/main/scripts/install.sh | bash
aoe

See the documentation for the full setup guide.