agent-of-empires

Creates and manages isolated tmux sessions for AI coding agents (Claude Code, OpenCode, Mistral Vibe, Gemini CLI, etc.) through a Rust-based wrapper that abstracts tmux complexity. Each session is assigned a unique 8-character UUID and human-readable title, with lifecycle management (attach/detach/kill) exposed via CLI and TUI. The system maintains session state in persistent storage keyed by profile, enabling recovery and resumption across terminal restarts.

Maintains multiple independent profiles (contexts) where each profile has its own session storage, worktree configuration, and Docker sandbox settings. Profiles are stored in a configuration directory and loaded on-demand, enabling developers to switch between completely isolated workspaces (e.g., 'project-a', 'project-b', 'experimentation') without session collision. The Storage system (src/session/storage.rs) provides profile-keyed persistence with automatic directory creation and cleanup.

Supports multiple AI coding agent providers (Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, Pi.dev, GitHub Copilot CLI, Factory Droid Coding) with agent-specific configuration and status detection patterns. Each agent type has a profile in AGENTS.md defining its CLI invocation, output patterns for status detection, and configuration requirements. The system abstracts agent differences, allowing users to create sessions for any supported agent without learning provider-specific details.

Persists session metadata (title, agent type, working directory, group membership, parent-child relationships) to disk in profile-scoped storage, enabling sessions to survive terminal restarts, SSH disconnections, and system reboots. When aoe is restarted, it reads session metadata from storage and can reattach to existing tmux sessions or recreate them if they were lost. The system maintains a session index for fast lookup and supports session cleanup (removing orphaned metadata for deleted sessions).

Allows users to define session templates and default configurations in YAML files (profile configuration, worktree settings, Docker sandbox config, agent defaults). When creating a session, users can reference a template to inherit configuration, reducing repetitive setup. Configuration is hierarchical: global defaults, profile-level defaults, and session-level overrides. The system validates configuration on load and provides helpful error messages for invalid settings.

Organizes sessions into a tree structure (GroupTree in src/session/group_tree.rs) where sessions can be nested under logical groups (e.g., 'frontend', 'backend', 'experiments'). Groups are displayed hierarchically in the TUI and can be collapsed/expanded for navigation. The system supports sub-sessions and parent-child relationships, enabling developers to logically cluster related agent sessions and manage them as units.

Monitors tmux session processes to automatically detect and classify agent state as Running, Waiting, or Idle by parsing agent-specific output patterns and process introspection. The status detection implementation (src/session/instance.rs and src/tmux/) analyzes terminal output and process trees to infer whether an agent is actively executing code, waiting for user input, or idle. Status is cached and updated on-demand to avoid expensive polling.

Creates and manages Git worktrees for each session, enabling parallel development branches without switching the main working directory. When a session is created with worktree support, the system automatically creates a new worktree at a path derived from a configurable template (e.g., ~/.agent-of-empires/worktrees/{profile}/{session-id}), checks out a specified branch, and cleans up the worktree when the session is destroyed. This allows multiple agents to work on different branches simultaneously without file system conflicts.

Optionally isolates agent execution inside Docker containers with configurable volume mounts for code directories, authentication files, and other resources. When sandbox mode is enabled (via configuration), sessions are launched inside a Docker container with the specified image, with volumes mounted to provide access to the host's code and credentials. The system manages container lifecycle (creation, attachment, cleanup) and supports custom images and environment variable injection.

Provides a terminal user interface (TUI) built with a Rust UI framework (likely Ratatui or similar, based on Rust ecosystem conventions) that displays sessions in a hierarchical tree view with real-time status indicators, search/filtering, and interactive controls. The TUI allows users to create, attach, detach, and delete sessions without CLI commands, with keyboard navigation (arrow keys, Enter, etc.) and a preview panel showing session details. The interface is responsive and updates session status on-demand.

Exposes core session and worktree operations through a command-line interface with subcommands like 'aoe add' (create session), 'aoe session' (manage sessions), 'aoe worktree' (manage worktrees), and others. Each command accepts flags and arguments for configuration (e.g., --agent-type, --branch, --group), with help text and validation. The CLI is the primary interface for scripting and automation, complementing the TUI for interactive use.

Enables creating new sessions as 'forks' of existing sessions, inheriting configuration (agent type, worktree branch, Docker sandbox settings) while maintaining a parent-child relationship in the session tree. When a session is forked, a new session is created with the same configuration but a new UUID and working directory (via git worktree), and the parent-child relationship is recorded in storage. This allows developers to branch off experiments from a baseline session without manual reconfiguration.

Optimizes the TUI and session management for mobile SSH connections by providing a responsive, low-bandwidth interface that works over high-latency, lossy connections. The TUI is designed to minimize redraws and support mobile-friendly keyboard shortcuts (e.g., single-key commands instead of multi-key combinations). Sessions persist across SSH disconnections (via tmux), and the TUI can be resumed without losing state. The system supports SSH key-based authentication and works with standard SSH clients on iOS/Android.