agent-of-empires/agent-of-empires

Agent of Empires (AoE) – Quick Overview

What it is: A lightweight session manager that lets you run, monitor, and control AI coding agents on Linux or macOS. Each agent lives in its own persistent tmux session, so the work keeps running even if you close the terminal or lose an SSH connection.

Why it matters: When you experiment with multiple LLM‑driven coding assistants (Claude, GPT‑4, etc.) you often need separate environments, git worktrees, or container sandboxes. AoE ties all that together with a tidy TUI, a web dashboard (desktop + mobile), a CLI, and an HTTP API.

---

Core Features

Feature	What it does
Multi‑interface	TUI, web UI, CLI, and HTTP API – pick whatever fits your workflow.
Persistent sessions	Agents run inside tmux; they survive terminal closes, SSH drops, or crashes.
Git worktree & multi‑repo support	Manage separate worktrees per agent, making branch‑specific work easy.
Container sandboxing	Optional isolation via Docker, Podman, or Apple Containers.
Structured view & diff reviewer	See agent output, file diffs, and status in a clean UI; mobile‑friendly view for phones.
Custom commands & hooks	Define per‑agent commands, repo hooks, and profiles for repeatable setups.
Notifications & status detection	Real‑time feedback when an agent finishes a task or hits an error.

---

How It Works

1. AoE creates a tmux session for each AI agent you add.
2. The session runs the command you specify (e.g., claude for Claude Code).
3. AoE tracks the session, exposing its status via the TUI, web UI, or API.
4. You can detach (Ctrl+b d) and later re‑attach without losing state.
5. Optional sandboxing runs the session inside a Docker/Podman/Apple Container, keeping the host clean.

---

Getting Started

# Install (requires tmux, Docker optional)
brew install aoe                     # macOS Homebrew
# or
curl -fsSL https://raw.githubusercontent.com/agent-of-empires/agent-of-empires/main/scripts/install.sh | bash

# Launch the TUI
aoe

# Add a coding agent (example with Claude Code)
aoe add --cmd claude

# Start the web dashboard (access from any browser)
aoe serve

Full docs: Quick start, CLI reference, and API docs are linked from the README.

---

When to Use AoE

• Multiple agents: Run several LLM‑based coders side‑by‑side, each with its own git context.
• Long‑running jobs: Keep agents alive across SSH sessions or terminal crashes.
• Isolation needs: Test code in containers without polluting the host.
• Team visibility: Share the web dashboard so collaborators can watch progress from a laptop or phone.

---

Limitations

• Works only on Linux/macOS (Windows via WSL2).
• Depends on tmux; no native Windows support.
• AI tool support is whatever you can invoke from the command line; AoE itself does not provide the models.

---

Contributing & Community

• Discord: Live office‑hours every Tuesday 9 AM ET.
• GitHub: Follow the roadmap, open issues, and submit PRs per the CONTRIBUTING.md guidelines.
• License: MIT (with a small Apache‑2.0 component).

---

Bottom line: Agent of Empires is a practical, open‑source orchestrator for AI coding agents, giving you persistent, sandboxed, and observable sessions without reinventing tmux.