Stop Juggling AI Agents! Use Agent of Empires Instead

What if I told you that your AI coding workflow is secretly broken? Not the agents themselves—Claude Code is brilliant, Codex CLI is fast, Gemini CLI is surprisingly capable. The problem is you. You're the bottleneck. You're the human router frantically switching between terminal tabs, trying to remember which branch Claude is destroying, whether Gemini finished that refactor, or if Codex is stuck waiting for your approval on a permission it asked twenty minutes ago.

Here's the dirty secret nobody talks about: running one AI agent is trivial. Running five in parallel is a part-time job. Each lives in its own terminal session. Each mutates your git history differently. Each demands attention at random moments. And when your SSH connection drops? Good luck reconstructing where everything stood.

I spent weeks in this chaos until I discovered what top developers are already using. A tool that transforms this nightmare into a single glance. Meet Agent of Empires—the terminal session manager built specifically for AI coding agents that turns parallel agent orchestration from a migraine into a superpower.

What is Agent of Empires?

Agent of Empires (AoE) is an open-source terminal session manager for AI coding agents, created by Nate Brake, a Machine Learning Engineer at Mozilla.ai. Built in Rust for performance and reliability, it runs on Linux and macOS (WSL2 for Windows users), providing a unified interface to create, monitor, and control multiple AI agents simultaneously.

The project exploded in popularity because it solves a genuinely novel problem. As AI coding tools proliferated—Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, Cursor CLI, Copilot CLI, and more—developers found themselves managing an increasingly fragmented workflow. Each tool wants its own terminal session. Each operates on your codebase independently. There's no native way to see status across all of them, isolate their changes, or access them remotely.

AoE changes everything by wrapping each agent in a persistent tmux session and exposing unified control through three interfaces: a rich Terminal User Interface (TUI), a web dashboard accessible from any browser, and a command-line interface for scripting and automation. The web dashboard even works as a Progressive Web App (PWA) on your phone, meaning you can approve tool calls or check agent status while grabbing coffee.

What makes AoE genuinely different from generic terminal multiplexers is its agent-aware semantics. It doesn't just show you terminal sessions—it understands what each agent is doing. Running? Waiting for input? Idle? Error state? This status detection, combined with automatic git worktree management and optional Docker sandboxing, creates an orchestration layer that generic tools simply cannot match.

Key Features That Make AoE Essential

Multi-Agent Ecosystem Support AoE auto-detects installed agents on your system and supports the complete landscape: Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, Cursor CLI, Copilot CLI, Pi.dev, Factory Droid, Hermes, Kiro CLI, and Qwen Code. No configuration wrestling—if it's installed, AoE knows how to launch it.

Three Interface Paradigms The TUI provides keyboard-driven visual management with contextual help. The web dashboard renders real agent terminals in-browser with session switching and diff review. The CLI enables automation and integration with tools like OpenClaw. Each interface serves different contexts: deep focus work, mobile oversight, and scripted pipelines.

Persistent Sessions via tmux Every agent runs in its own tmux session. Close your laptop, drop your SSH connection, kill your terminal—your agents keep running. Reopen AoE and everything resumes exactly where you left it. The critical shortcut to know: Ctrl+b d detaches from any session back to the TUI.

Git Worktree Automation Run parallel agents on different branches of the same repository without conflicts. AoE automatically sets up git worktrees, so Claude can refactor your API on feature/new-auth while Gemini writes tests on feature/test-coverage—both operating on isolated working trees derived from the same repository.

Docker Sandboxing Isolate agents in containers with shared authentication volumes. When you don't trust an experimental agent or need clean dependency environments, sandboxing prevents contamination of your host system while maintaining access to necessary credentials.

Remote Mobile Access Press R in the TUI to expose your dashboard over HTTPS with QR code authentication. Uses Tailscale Funnel for stable URLs (PWAs keep working across restarts) or Cloudflare Tunnel as fallback. Check on your agents from your phone without VPN configuration nightmares.

Session Resume for Claude Persist and resume Claude conversations across reboots and upgrades. Your conversation context survives system maintenance—no more losing half-hour deep dives into architectural decisions because Docker needed a restart.

Cockpit: Native Agent Rendering (Alpha) An opt-in mobile-first interface using the Agent Client Protocol, displaying plan panels, tool-call cards, and swipe-to-approve interactions. This isn't just a terminal mirror—it's a purpose-built agent interaction surface for touch devices.

Real-World Use Cases Where AoE Dominates

Microservice Refactoring with Parallel Agents

You're modernizing a monolith to microservices. Claude Code rewrites the user service on one branch, Codex CLI handles the payment service on another, and Gemini CLI generates OpenAPI specifications on a third. Without AoE, you're context-switching between three terminals, constantly checking git status, and praying nobody force-pushes. With AoE, one dashboard shows all three statuses. Worktrees prevent cross-contamination. You review diffs without leaving the TUI.

Mobile Approval Workflows

You're in a meeting and Claude hits a permission boundary—should it delete that legacy migration file? Without AoE, you rush back to your desk or risk context loss. With AoE's remote access, your phone buzzes with a PWA notification. Swipe to approve. The agent continues. Your meeting continues. Zero friction.

Safe Experimentation with Untrusted Agents

A new agent drops—Factory Droid promises incredible code generation but you're skeptical. Instead of risking your working tree, you launch it in AoE's Docker sandbox with a fresh worktree. It runs, it generates, you review the diff in AoE's built-in viewer. If it's garbage, one keybinding deletes the session and worktree. Your main branch remains pristine.

Long-Running Autonomous Tasks

You need Codex CLI to migrate 500 test files overnight. Start it in AoE, verify it's running, close your laptop, go to sleep. Check progress from your phone at breakfast. If it's stuck on an edge case, intervene remotely. If it's done, review the massive diff over coffee. The session persisted through your laptop's sleep cycle because tmux runs server-side.

Multi-Repository Coordination

Your feature spans three repositories: frontend, backend, and shared types. AoE's multi-repo workspaces let you drive a single session across all three git repositories simultaneously. One agent context, multiple codebases, coordinated commits. No more cd ../../other-repo chaos.

Step-by-Step Installation & Setup Guide

Agent of Empires requires tmux (essential for session persistence) and optionally Docker for sandboxing. Here's how to get running in under two minutes.

Prerequisites

# Verify tmux is installed
tmux -V
# Should output version 3.x or higher

# Optional: verify Docker for sandboxing
docker --version

Installation Methods

Quick Install (Recommended)

# One-liner for Linux and macOS
curl -fsSL \
  https://raw.githubusercontent.com/njbrake/agent-of-empires/main/scripts/install.sh \
  | bash

This script detects your platform, downloads the appropriate binary, and places it in your PATH.

Homebrew (macOS and Linux)

# Clean, updatable package management
brew install aoe

# Verify installation
aoe --version

Nix (Declarative environments)

# Run without installing
nix run github:njbrake/agent-of-empires

# Or add to your flake.nix for reproducible environments

Build from Source (Rust toolchain required)

# Clone the repository
git clone https://github.com/njbrake/agent-of-empires
cd agent-of-empires

# Release build optimized for performance
cargo build --release

# Binary available at ./target/release/aoe

Initial Configuration

AoE stores configuration in standard directories:

• macOS: ~/.agent-of-empires/
• Linux: ~/.config/agent-of-empires/

Profiles let you separate workspaces for different projects or clients. Create a profile for your work repository, another for open source contributions, keeping agent histories and preferences isolated.

First Launch

# Start the TUI interface
aoe

# The interface loads with contextual help. Press ? anytime for keybindings.
# The bottom information bar adapts to your current context.

REAL Code Examples from the Repository

Let's examine actual usage patterns from the Agent of Empires documentation, with detailed explanations of what each command accomplishes.

Example 1: Creating Your First Agent Session

# Launch the TUI dashboard
aoe

# From the TUI, or directly from shell: create a Claude Code session
aoe add --cmd claude

Before: This is your entry point. The aoe command without arguments launches the rich terminal interface showing all existing sessions, their statuses, and available actions. The aoe add --cmd claude variant creates a session programmatically—useful in scripts or when you know exactly which agent you want.

After: AoE detects your installed claude command, creates a dedicated tmux session named with a unique identifier, and attaches your terminal to it. The session immediately appears in your TUI with status "running." When you detach with Ctrl+b d, Claude continues processing in the background. Reopen aoe and you'll see Claude's current status—still running, waiting for your input on a tool call, or idle after completing its task.

Example 2: Starting the Web Dashboard

# Launch the web server for browser access
aoe serve

# Or from within the TUI, press R to start with automatic HTTPS

Before: The web dashboard transforms AoE from a local-only tool into a remotely accessible control plane. This is essential for phone access, sharing sessions with teammates, or operating from devices without terminal environments.

After: AoE starts an HTTP server (default port 8080 for release builds, 8081 for debug). The TUI's R keybinding goes further—it automatically provisions HTTPS via Tailscale Funnel if available, generating a stable URL and QR code for instant phone pairing. With Tailscale, your PWA installation persists across server restarts. Without Tailscale, Cloudflare Tunnel provides equivalent functionality. The web interface renders actual agent terminals using xterm.js, so you're seeing real output, not sanitized summaries.

Example 3: Mobile SSH Resilience Pattern

# When connecting from mobile SSH clients like Termius or Blink,
# wrap AoE in a parent tmux session for extra resilience

tmux new-session -s main
aoe

Before: Mobile SSH clients are notorious for aggressive connection timeouts. Without protection, a dropped connection kills your AoE TUI session, forcing you to reconnect and navigate back to your context.

After: The nested tmux architecture provides two layers of persistence. Your mobile client's connection drops? The outer main session survives on the server. Reconnect, reattach to main, and your AoE TUI is exactly as you left it. The critical navigation: after attaching to an agent session with Enter, use Ctrl+b L (that's capital L) to toggle back to the AoE TUI without detaching from the agent. This two-level tmux model—AoE's internal sessions plus your wrapper session—makes mobile operation genuinely viable, not theoretically possible but practically frustrating.

Example 4: Development and Debug Workflow

# Standard Rust development cycle
cargo check          # Fast type-checking without full compilation
cargo test           # Run the test suite
cargo fmt            # Enforce consistent formatting
cargo clippy         # Lint for idiomatic Rust and common mistakes
cargo build --release  # Optimized production binary

# Enable debug logging for troubleshooting
AGENT_OF_EMPIRES_DEBUG=1 cargo run

# View structured logs with intelligent viewer selection
# Priority: lnav > bat > less > stdout
aoe logs

# Common log viewing options:
aoe logs --serve      # View the web dashboard daemon log
aoe logs --all        # Merge application and daemon logs
aoe logs --follow     # Live-tail for real-time debugging
aoe logs --path       # Print resolved log file location
aoe logs --no-pager   # Plain text output for piping

Before: Debugging terminal applications is notoriously painful—logs scattered, no structured viewer, production vs. development behavior diverging silently.

After: AoE's debug system demonstrates sophisticated developer experience design. The AGENT_OF_EMPIRES_DEBUG=1 environment variable activates verbose logging without code changes. Crucially, debug builds use completely isolated namespaces—app data in ~/.agent-of-empires-dev, tmux sessions prefixed aoe_dev_, default port 8081. You can run a development build alongside your production AoE installation without collision. The aoe logs command implements intelligent viewer detection, automatically using lnav for structured parsing if available, falling back through bat (syntax highlighting), less (standard paging), to plain stdout. The --serve, --all, --follow flags cover every debugging scenario from daemon issues to live monitoring.

Advanced Usage & Best Practices

Profile-Based Project Isolation Create distinct profiles for each client or major project. Profiles maintain separate session histories, configuration, and default agents. Switch contexts completely without session pollution.

Repository Configuration with Hooks Use per-project .aoe/config.toml files to define default agents, pre-session hooks for environment setup, and post-session cleanup. Automate dependency installation, secret injection, or notification webhooks.

Agent Command Overrides Wrap agents with custom scripts or sandboxed executables per project. Need Claude to always run with specific environment variables? Override the command in configuration rather than remembering flags.

tmux Status Bar Integration Install AoE's tmux status bar components for at-a-glance session monitoring even when not in the TUI. See agent counts and critical statuses from any tmux context.

Sound Effects for Asynchronous Awareness Enable audible notifications for state changes. When you're deep in documentation and Claude finishes its task, you'll hear it—no compulsive status checking required.

HTTP API for External Orchestration The REST API enables integration with CI/CD pipelines, custom dashboards, or higher-level orchestrators. Trigger sessions, query statuses, and retrieve diffs programmatically.

Comparison with Alternatives

The pattern is clear: generic tools provide persistence, but only AoE understands what you're persisting. The gap isn't features for feature's sake—it's the difference between "terminal sessions exist" and "your agents are productive."

FAQ

Does Agent of Empires work on Windows? Only through WSL2. AoE depends on tmux and POSIX process semantics that native Windows cannot provide. Install WSL2 with your preferred Linux distribution, then follow standard Linux installation.

What happens when I close the AoE TUI? Absolutely nothing critical. Sessions are independent tmux processes. Open and close aoe as frequently as needed. Sessions persist until explicitly deleted. This is the core reliability guarantee.

Can I still use raw tmux with AoE sessions? Yes—every AoE session is a standard tmux session. Run tmux ls to see them, tmux attach -t <name> to connect directly. AoE adds management layers without removing underlying access.

How does AoE handle agent authentication? AoE doesn't intercept or manage agent credentials. Each agent uses its native authentication (Claude's API key, Copilot's GitHub session, etc.). Docker sandboxing mounts shared auth volumes so isolated agents retain necessary access.

Is the web dashboard secure for production code? The R keybinding generates HTTPS with passphrase authentication. Tailscale Funnel provides stable URLs within your tailnet. For additional security, run AoE on a dedicated orchestration host rather than your development machine.

What's the performance overhead? Minimal. AoE itself is a Rust binary using negligible resources. Each agent's resource consumption is determined by the agent, not AoE. The tmux wrapper adds effectively zero overhead.

How do I contribute or report issues? The project is MIT-licensed and actively maintained. Check the development documentation for local setup, run cargo test before submitting PRs, and join the Discord community for discussion.

Conclusion

Agent of Empires represents a fundamental shift in how we interact with AI coding tools. The individual agents—Claude, Codex, Gemini, and their competitors—will continue improving. But the orchestration layer between you and your agents was a gaping void that AoE fills with surgical precision.

I've used raw tmux for years. I've scripted custom worktree workflows. I've cobbled together SSH tunnels for remote access. AoE makes all of that feel like the primitive workaround it always was. The status detection, the one-key remote access, the automatic isolation, the session resume—these aren't conveniences, they're enablers of genuinely parallel agent workflows that were previously too chaotic to attempt.

If you're running more than one AI agent, or you want to, or you tried and gave up on the complexity: install Agent of Empires today. The Homebrew one-liner takes thirty seconds. The time you'll reclaim from context-switching alone pays for the learning curve in a single afternoon.

⭐ Star Agent of Empires on GitHub to support the project and discover the web dashboard, Cockpit alpha, and advanced configuration guides. Your future self—managing five agents from a beach with your phone—will thank you.