Agent of Empires

A terminal session manager for Linux and macOS using tmux to aid in management and monitoring of AI coding agents, written in Rust.

Features

• TUI Dashboard - Visual interface to manage all your AI coding sessions
• Session Management - Create, attach, detach, and delete sessions
• Group Organization - Organize sessions into hierarchical folders
• Status Detection - Automatic status detection for Claude Code and OpenCode
• tmux Integration - Sessions persist in tmux for reliability
• Multi-profile Support - Separate workspaces for different projects
• Git Worktrees - Run parallel agents on different branches of the same repo

How It Works

Agent of Empires (aoe) is a wrapper around tmux, the terminal multiplexer. Each AI coding session you create is actually a tmux session under the hood.

Once you attach to a session, you’re working directly in tmux. Basic tmux knowledge helps:

If you’re new to tmux, the key thing to remember is Ctrl+b d to detach and return to the TUI.

Quick Links

• Installation - Get started with Agent of Empires
• Quick Start - Basic usage tutorial
• CLI Reference - Complete command documentation
• Git Worktrees Guide - Parallel development with worktrees

Installation

Prerequisites

Agent of Empires requires tmux to be installed on your system.

macOS:

brew install tmux

Ubuntu/Debian:

sudo apt install tmux

Fedora:

sudo dnf install tmux

Install Agent of Empires

Quick Install (Recommended)

Run the install script:

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

Homebrew

brew install njbrake/aoe/aoe

Update via brew update && brew upgrade aoe.

Build from Source

git clone https://github.com/njbrake/agent-of-empires
cd agent-of-empires
cargo build --release

The binary will be at target/release/aoe.

Verify Installation

aoe --version

Uninstall

To remove Agent of Empires:

aoe uninstall

This will guide you through removing the binary, configuration, and tmux settings.

Quick Start

Launch the TUI

The simplest way to use Agent of Empires is through the TUI dashboard:

aoe

This opens an interactive interface where you can:

• View all your coding sessions
• Create new sessions with n
• Attach to sessions with Enter
• Delete sessions with d
• Quit with q

CLI Quick Reference

Add a Session

# Add session in current directory
aoe add

# Add session with custom title
aoe add -t "my-feature"

# Add and launch immediately
aoe add -l

# Add session for specific project
aoe add /path/to/project

List Sessions

# Table format
aoe list

# JSON format
aoe list --json

Manage Sessions

# Attach to a session
aoe session attach my-session

# Start a stopped session
aoe session start my-session

# Stop a running session
aoe session stop my-session

# Show session details
aoe session show my-session

Check Status

# Summary of all sessions
aoe status

# Detailed status
aoe status -v

# JSON format (for scripts)
aoe status --json

Profiles

Profiles let you maintain separate workspaces:

# Use default profile
aoe

# Use a specific profile
aoe -p work

# Create a new profile
aoe profile create client-xyz

# List all profiles
aoe profile list

Configuration

Configuration is stored in ~/.agent-of-empires/:

~/.agent-of-empires/
├── config.toml           # Global configuration
├── profiles/
│   └── default/
│       ├── sessions.json # Session data
│       └── groups.json   # Group structure
└── logs/                 # Session logs

Environment Variables

Next Steps

• See the CLI Reference for complete command documentation
• Learn about Git Worktrees for parallel development

Command-Line Help for aoe

This document contains the help content for the aoe command-line program.

Command Overview:

• aoe↴
• aoe add↴
• aoe list↴
• aoe remove↴
• aoe status↴
• aoe session↴
• aoe session start↴
• aoe session stop↴
• aoe session restart↴
• aoe session fork↴
• aoe session attach↴
• aoe session show↴
• aoe session current↴
• aoe group↴
• aoe group list↴
• aoe group create↴
• aoe group delete↴
• aoe group move↴
• aoe profile↴
• aoe profile list↴
• aoe profile create↴
• aoe profile delete↴
• aoe profile default↴
• aoe worktree↴
• aoe worktree list↴
• aoe worktree info↴
• aoe worktree cleanup↴
• aoe uninstall↴

aoe

Agent of Empires (aoe) is a terminal session manager that uses tmux to help you manage and monitor AI coding agents like Claude Code and OpenCode.

Run without arguments to launch the TUI dashboard.

Usage: aoe [OPTIONS] [COMMAND]

Subcommands:

• add — Add a new session
• list — List all sessions
• remove — Remove a session
• status — Show session status summary
• session — Manage session lifecycle (start, stop, attach, etc.)
• group — Manage groups for organizing sessions
• profile — Manage profiles (separate workspaces)
• worktree — Manage git worktrees for parallel development
• uninstall — Uninstall Agent of Empires

Options:

• -p, --profile <PROFILE> — Profile to use (separate workspace with its own sessions)

aoe add

Add a new session

Usage: aoe add [OPTIONS] [PATH]

Arguments:

• <PATH> — Project directory (defaults to current directory)

  Default value: .

Options:

• -t, --title <TITLE> — Session title (defaults to folder name)
• -g, --group <GROUP> — Group path (defaults to parent folder)
• -c, --cmd <COMMAND> — Command to run (e.g., ‘claude’, ‘opencode’)
• -P, --parent <PARENT> — Parent session (creates sub-session, inherits group)
• -l, --launch — Launch the session immediately after creating
• -w, --worktree <WORKTREE_BRANCH> — Create session in a git worktree for the specified branch
• -b, --new-branch — Create a new branch (use with –worktree)
• -s, --sandbox — Run session in Docker sandbox
• --sandbox-image <SANDBOX_IMAGE> — Custom Docker image for sandbox (implies –sandbox)

aoe list

List all sessions

Usage: aoe list [OPTIONS]

Options:

• --json — Output as JSON
• --all — List sessions from all profiles

aoe remove

Remove a session

Usage: aoe remove [OPTIONS] <IDENTIFIER>

Arguments:

• <IDENTIFIER> — Session ID or title to remove

Options:

• --delete-worktree — Delete worktree directory (default: keep worktree)
• --keep-container — Keep container instead of deleting it (default: delete per config)

aoe status

Show session status summary

Usage: aoe status [OPTIONS]

Options:

• -v, --verbose — Show detailed session list
• -q, --quiet — Only output waiting count (for scripts)
• --json — Output as JSON

aoe session

Manage session lifecycle (start, stop, attach, etc.)

Usage: aoe session <COMMAND>

Subcommands:

• start — Start a session’s tmux process
• stop — Stop session process
• restart — Restart session
• fork — Fork Claude session with context
• attach — Attach to session interactively
• show — Show session details
• current — Auto-detect current session

aoe session start

Start a session’s tmux process

Usage: aoe session start <IDENTIFIER>

Arguments:

• <IDENTIFIER> — Session ID or title

aoe session stop

Stop session process

Usage: aoe session stop <IDENTIFIER>

Arguments:

• <IDENTIFIER> — Session ID or title

aoe session restart

Restart session

Usage: aoe session restart <IDENTIFIER>

Arguments:

• <IDENTIFIER> — Session ID or title

aoe session fork

Fork Claude session with context

Usage: aoe session fork [OPTIONS] <IDENTIFIER>

Arguments:

• <IDENTIFIER> — Session ID or title to fork

Options:

• -t, --title <TITLE> — Custom title for forked session
• -g, --group <GROUP> — Target group for forked session

aoe session attach

Attach to session interactively

Usage: aoe session attach <IDENTIFIER>

Arguments:

• <IDENTIFIER> — Session ID or title

aoe session show

Show session details

Usage: aoe session show [OPTIONS] [IDENTIFIER]

Arguments:

• <IDENTIFIER> — Session ID or title (optional, auto-detects in tmux)

Options:

• --json — Output as JSON

aoe session current

Auto-detect current session

Usage: aoe session current [OPTIONS]

Options:

• -q, --quiet — Just session name (for scripting)
• --json — Output as JSON

aoe group

Manage groups for organizing sessions

Usage: aoe group <COMMAND>

Subcommands:

• list — List all groups
• create — Create a new group
• delete — Delete a group
• move — Move session to group

aoe group list

List all groups

Usage: aoe group list [OPTIONS]

Options:

• --json — Output as JSON

aoe group create

Create a new group

Usage: aoe group create [OPTIONS] <NAME>

Arguments:

• <NAME> — Group name

Options:

• --parent <PARENT> — Parent group for creating subgroups

aoe group delete

Delete a group

Usage: aoe group delete [OPTIONS] <NAME>

Arguments:

• <NAME> — Group name

Options:

• --force — Force delete by moving sessions to default group

aoe group move

Move session to group

Usage: aoe group move <IDENTIFIER> <GROUP>

Arguments:

• <IDENTIFIER> — Session ID or title
• <GROUP> — Target group

aoe profile

Manage profiles (separate workspaces)

Usage: aoe profile [COMMAND]

Subcommands:

• list — List all profiles
• create — Create a new profile
• delete — Delete a profile
• default — Show or set default profile

aoe profile list

List all profiles

Usage: aoe profile list

aoe profile create

Create a new profile

Usage: aoe profile create <NAME>

Arguments:

• <NAME> — Profile name

aoe profile delete

Delete a profile

Usage: aoe profile delete <NAME>

Arguments:

• <NAME> — Profile name

aoe profile default

Show or set default profile

Usage: aoe profile default [NAME]

Arguments:

• <NAME> — Profile name (optional, shows current if not provided)

aoe worktree

Manage git worktrees for parallel development

Usage: aoe worktree <COMMAND>

Subcommands:

• list — List all worktrees in current repository
• info — Show worktree information for a session
• cleanup — Cleanup orphaned worktrees

aoe worktree list

List all worktrees in current repository

Usage: aoe worktree list

aoe worktree info

Show worktree information for a session

Usage: aoe worktree info <IDENTIFIER>

Arguments:

• <IDENTIFIER> — Session ID or title

aoe worktree cleanup

Cleanup orphaned worktrees

Usage: aoe worktree cleanup [OPTIONS]

Options:

• -f, --force — Actually remove worktrees (default is dry-run)

aoe uninstall

Uninstall Agent of Empires

Usage: aoe uninstall [OPTIONS]

Options:

• --keep-data — Keep ~/.agent-of-empires/ (sessions, config, logs)
• --keep-tmux-config — Keep tmux configuration
• --dry-run — Show what would be removed without removing
• -y — Skip confirmation prompts

This document was generated automatically by clap-markdown.

Git Worktree - Quick Reference

CLI vs TUI Behavior

One-Liner Commands

# Create worktree session (new branch)
aoe add . -w feat/my-feature -b

# Create worktree session (existing branch)
aoe add . -w feat/my-feature

# List all worktrees
aoe worktree list

# Show session info
aoe worktree info <session>

# Find orphans
aoe worktree cleanup

# Remove session (prompts for worktree cleanup)
aoe remove <session>

# Remove session (keep worktree)
aoe remove <session> --keep-worktree

TUI Keyboard Shortcuts

Note: When creating a session with a worktree branch name in the TUI, it will automatically create a new branch and worktree.

Default Configuration

[worktree]
enabled = false
path_template = "../{repo-name}-worktrees/{branch}"
auto_cleanup = true
show_branch_in_tui = true

Template Variables

• {repo-name} - Repository folder name
• {branch} - Branch name (slashes → hyphens)
• {session-id} - First 8 chars of UUID

Common Path Templates

# Default (sibling directory)
path_template = "../{repo-name}-worktrees/{branch}"

# Nested in repo
path_template = "./worktrees/{branch}"

# Absolute path
path_template = "/absolute/path/to/worktrees/{repo-name}/{branch}"

# With session ID
path_template = "../wt/{branch}-{session-id}"

Quick Start

# 1. Enable worktrees (first time only)
cd ~/scm/my-project
aoe add . -w feat/test -b

# 2. Create parallel sessions in TUI
aoe
# Press 'n' and fill in the "Worktree (optional)" field:
#   - Title: UI Changes, Worktree: feat/ui-changes
#   - Title: API Changes, Worktree: feat/api-changes
#   - Title: Urgent Fix, Worktree: fix/urgent-bug
# Each session will create a new branch and worktree automatically

# 3. View all worktrees
aoe worktree list

# 4. Work and cleanup
aoe remove <session>  # Answer Y to delete worktree

Cleanup Behavior

Workflow Examples

CLI Workflow

# Create 3 parallel feature sessions
cd ~/scm/my-app
aoe add . -w feat/ui -b
aoe add . -w feat/api -b
aoe add . -w feat/db -b

# View all
aoe worktree list

# Work in TUI
aoe  # See all 3 with branch names

# When done
aoe remove <id>  # Cleans up worktree

TUI Workflow

# Launch TUI
cd ~/scm/my-app
aoe

# Press 'n' to open new session dialog
# Fill in fields:
#   Title: Feature UI (or leave empty for random name)
#   Path: . (current directory)
#   Group: (optional)
#   Tool: claude (or select your tool)
#   Worktree (optional): feat/ui-changes
# Press Enter

# Creates:
#   ✅ New branch: feat/ui-changes
#   ✅ New worktree: ../my-app-worktrees/feat-ui-changes
#   ✅ New session attached to worktree
#   ✅ Launches you into the session

# Repeat for more parallel sessions

File Locations

• Config: ~/.agent-of-empires/config.toml
• Sessions: ~/.agent-of-empires/profiles/<profile>/sessions.json
• Default Worktrees: ../<repo-name>-worktrees/

Error Messages

Pro Tips

• ✅ Use descriptive branch names (visible in TUI)
• ✅ Check preview panel before starting work
• ✅ Run aoe worktree cleanup periodically
• ✅ Use --keep-worktree when preserving work
• ✅ Keep main repo on main/master branch

Two-Terminal Workflow

A practical workflow for using aoe with git worktrees, keeping agent management separate from git operations.

Philosophy

aoe manages your AI coding sessions and provides paired terminals for each session. This separation keeps agent interactions distinct from your shell work while keeping everything organized in one tool.

Setup

Terminal 1: Agent Sessions (Agent View)

Run aoe here in the default Agent View. This terminal is dedicated to:

• Creating new sessions (one per task/feature)
• Monitoring agent session status
• Attaching to sessions when you need to interact with the agent

cd ~/scm/my-project
aoe -p <"personal" or "work" etc, or omit arg to use default profile>

Terminal 2: Git & Shell Operations (Terminal View)

Run aoe here too, but press t to switch to Terminal View. This terminal is for:

• Accessing project-specific terminals at the correct working directory
• Running git commands, builds, and tests
• Any bash/terminal work outside of agent sessions

cd ~/scm/my-project
aoe -p <same profile as Terminal 1>
# Press 't' to switch to Terminal View

Daily Workflow

Starting Work

Generally I keep one agent session open that is located in the main repo (no worktrees). I use the agent for answering questions about the codebase, and the paired terminal for general operations that I want to effect the main branch (like git pulls)

1. Update main (Terminal 2 - Terminal View):

   • Select your main project session and press Enter to attach to its terminal
   • Run git pull origin main
   • Detach with Ctrl+b d

2. Create a session (Terminal 1 - Agent View): In the aoe TUI, create a new session and fill in the git worktree name with what you want the feature branch to be named. This creates a new branch from your updated main and a worktree at ../my-project-worktrees/feat-auth-refactor.

During Work

• Terminal 1 (Agent View): Interact with agents, switch between sessions, monitor status
• Terminal 2 (Terminal View): Access paired terminals, run builds, check git status

Directory Layout

~/scm/
├── my-project/              # Main repo (stays on main branch)
│   └── ...
└── my-project-worktrees/    # All worktrees live here
    ├── feat-auth-refactor/
    ├── feat-new-api/
    └── fix-login-bug/

Keyboard Shortcuts

Tips

• Keep one agent session open and on the main branch (no worktree) for answering questions and using its paired terminal for commands
• Keep main clean: Never work directly in the main repo. Always use worktrees.
• Pull before creating: Always git pull on main before creating new sessions so branches start from recent commits.
• One task, one session: Each worktree maps to one aoe session. This keeps context isolated.
• Let agents stay focused: The agent in each session only sees its worktree. Git operations happen in the paired terminal.

Why This Works

Both terminals run aoe, giving you a unified interface while keeping agent work separate from shell work.

Docker Sandbox - Quick Reference

Overview

Docker sandboxing runs your AI coding agents (Claude Code, OpenCode) inside isolated Docker containers while maintaining access to your project files and credentials.

Key Features:

• One container per session
• Shared authentication across containers (no re-auth needed)
• Automatic container lifecycle management
• Full project access via volume mounts

CLI vs TUI Behavior

One-Liner Commands

# Create sandboxed session
aoe add --sandbox .

# Create sandboxed session with custom image
aoe add --sandbox-image myregistry/custom:v1 .

# Create and launch sandboxed session
aoe add --sandbox -l .

# Remove session (auto-cleans container)
aoe remove <session>

# Remove session but keep container
aoe remove <session> --keep-container

Note: In the TUI, the sandbox checkbox only appears when Docker is available on your system.

Default Configuration

[sandbox]
enabled_by_default = false
default_image = "ghcr.io/njbrake/aoe-sandbox:latest"
auto_cleanup = true
cpu_limit = "4"
memory_limit = "8g"
environment = ["ANTHROPIC_API_KEY"]

Configuration Options

Volume Mounts

Automatic Mounts

Persistent Auth Volumes

Note: Auth persists across containers. First session requires authentication, subsequent sessions reuse it.

Source Code Reference

Volume mounts are defined in src/session/instance.rs in the build_container_config() method (lines 207-274). The actual Docker -v arguments are constructed in src/docker/container.rs in the run_container() function (lines 89-101).

Container Naming

Containers are named: aoe-sandbox-{session_id_first_8_chars}

Example: aoe-sandbox-a1b2c3d4

How It Works

1. Session Creation: When you add a sandboxed session, aoe records the sandbox configuration
2. Container Start: When you start the session, aoe creates/starts the Docker container with appropriate volume mounts
3. tmux + docker exec: Host tmux runs docker exec -it <container> claude (or opencode)
4. Cleanup: When you remove the session, the container is automatically deleted

Environment Variables

Pass API keys through containers by adding them to config:

[sandbox]
environment = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"]

These variables are read from your host environment and passed to containers.

Available Images

AOE provides two official sandbox images:

Dev Sandbox Tools

The dev sandbox (aoe-dev-sandbox) includes everything in the base image plus:

• Rust (rustup, cargo, rustc)
• uv (fast Python package manager)
• Node.js LTS (via nvm, with npm and npx)
• GitHub CLI (gh)

To use the dev sandbox:

# Per-session
aoe add --sandbox-image ghcr.io/njbrake/aoe-dev-sandbox:latest .

# Or set as default in ~/.agent-of-empires/config.toml
[sandbox]
default_image = "ghcr.io/njbrake/aoe-dev-sandbox:latest"

Custom Docker Images

The default sandbox image includes Claude Code, OpenCode, git, and basic development tools. For projects requiring additional dependencies beyond what the dev sandbox provides, you can extend either base image.

Step 1: Create a Dockerfile

Create a Dockerfile in your project (or a shared location):

FROM ghcr.io/njbrake/aoe-sandbox:latest

# Example: Add Python for a data science project
RUN apt-get update && apt-get install -y \
    python3 \
    python3-pip \
    python3-venv \
    && rm -rf /var/lib/apt/lists/*

# Install Python packages
RUN pip3 install --break-system-packages \
    pandas \
    numpy \
    requests

Step 2: Build Your Image

# Build locally
docker build -t my-sandbox:latest .

# Or build and push to a registry
docker build -t ghcr.io/yourusername/my-sandbox:latest .
docker push ghcr.io/yourusername/my-sandbox:latest

Step 3: Configure AOE to Use Your Image

Option A: Set as default for all sessions

Add to ~/.agent-of-empires/config.toml:

[sandbox]
default_image = "my-sandbox:latest"
# Or with registry:
# default_image = "ghcr.io/yourusername/my-sandbox:latest"

Option B: Use per-session via CLI

aoe add --sandbox-image my-sandbox:latest .

Development

Generating the Demo GIF

The demo GIF in the README is created using VHS, a tool that generates terminal GIFs from scripts.

Install VHS

brew install vhs

Regenerate the GIF

The assets/demo.tape file defines the demo script. To regenerate:

# Clear the demo profile (so it starts fresh)
rm -rf ~/.agent-of-empires/profiles/demo

# Ensure demo directories exist
mkdir -p /tmp/demo-projects/api-server /tmp/demo-projects/web-app

# Generate the GIF (run from repo root)
vhs assets/demo.tape

This creates assets/demo.gif.

The demo uses -p demo to run in a separate profile so it doesn’t affect your real sessions.

See the VHS documentation for more options.