GitHub - njbrake/agent-of-empires: Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, Pi.dev Coding Agent Terminal Session manager via tmux and git Worktrees

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, and Pi.dev
• 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, and Pi.dev. 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: anthropics/claude-code#1913

Development

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

# Debug logging
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.