Agent of Empires (AoE)

A terminal session manager for AI coding agents on Linux and macOS. Built on tmux, written in Rust.

Run multiple AI agents in parallel across different branches of your codebase, each in its own isolated session with optional Docker sandboxing.

If you find this project useful, please consider giving it a star on GitHub: it helps others discover the project!

Features

Multi-agent support -- Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, Cursor CLI, Copilot CLI, Pi.dev, and Factory Droid
TUI dashboard -- visual interface to create, monitor, and manage sessions
Agent + terminal views -- toggle between your AI agents and paired shell terminals with t
Status detection -- see which agents are running, waiting for input, or idle
Git worktrees -- run parallel agents on different branches of the same repo
Docker sandboxing -- isolate agents in containers with shared auth volumes
Diff view -- review git changes and edit files without leaving the TUI
Per-repo config -- .aoe/config.toml for project-specific settings and hooks
Profiles -- separate workspaces for different projects or clients
CLI and TUI -- full functionality from both interfaces

How It Works

AoE wraps tmux. Each session is a tmux session, so agents keep running when you close the TUI. Reopen aoe and everything is still there.

The key tmux shortcut to know: Ctrl+b d detaches from a session and returns to the TUI.

Installation

Prerequisites: tmux (required), Docker (optional, for sandboxing)

# Quick install (Linux & macOS)
curl -fsSL \
  https://raw.githubusercontent.com/njbrake/agent-of-empires/main/scripts/install.sh \
  | bash

# Homebrew
brew install aoe

# Nix
nix run github:njbrake/agent-of-empires

# Build from source
git clone https://github.com/njbrake/agent-of-empires
cd agent-of-empires && cargo build --release

Quick Start

# Launch the TUI
aoe

# Add a session from CLI
aoe add /path/to/project

# Add a session on a new git branch
aoe add . -w feat/my-feature -b

# Add a sandboxed session
aoe add --sandbox .

In the TUI: n to create a session, Enter to attach, t to toggle terminal view, D for diff view, d to delete, ? for help.

Documentation

Installation -- prerequisites and install methods
Quick Start -- first steps and basic usage
Workflow Guide -- recommended setup with bare repos and worktrees
Git Worktrees -- parallel agents on different branches
Docker Sandbox -- container isolation for agents
Repo Config & Hooks -- per-project settings and automation
Diff View -- review and edit changes in the TUI
tmux Status Bar -- integrated session monitoring
Sound Effects -- audible agent status notifications
Configuration Reference -- all config options
CLI Reference -- complete command documentation
Development -- contributing and local setup

FAQ

What happens when I close aoe?

Nothing. Sessions are tmux sessions running in the background. Open and close aoe as often as you like. Sessions only get removed when you explicitly delete them.

Which AI tools are supported?

Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, Cursor CLI, Copilot CLI, Pi.dev, and Factory Droid. AoE auto-detects which are installed on your system.

Troubleshooting

Using aoe with mobile SSH clients (Termius, Blink, etc.)

Run aoe inside a tmux session when connecting from mobile:

tmux new-session -s main
aoe

Use Ctrl+b L to toggle back to aoe after attaching to an agent session.

Claude Code is flickering

This is a known Claude Code issue, not an aoe problem: https://github.com/anthropics/claude-code/issues/1913

Development

cargo check          # Type-check
cargo test           # Run tests
cargo fmt            # Format
cargo clippy         # Lint
cargo build --release  # Release build

# Debug logging (writes to debug.log in app data dir)
AGENT_OF_EMPIRES_DEBUG=1 cargo run

Star History

Acknowledgments

Inspired by agent-deck (Go + Bubble Tea).

Author

Created by Nate Brake (@natebrake)

License

MIT License -- see LICENSE for details.