Agent of Agent of Empires (aoaoe)

An autonomous supervisor for Agent of Empires sessions. Uses OpenCode or Claude Code as the reasoning engine.

This project is a companion to Agent of Empires (AoE) by Nate Brake. AoE is the foundation -- it manages multiple AI coding agents in tmux sessions with git worktrees. aoaoe adds an autonomous supervisor layer on top. You need AoE running first; aoaoe plugs into it.

Self-improvement mode: make self starts aoaoe supervising its own AoE session — reading the roadmap from aoaoe.tasks.json, implementing features, committing, and pushing. It updates itself in real time.

What is this?

AoE is great at spawning and organizing agents, but someone still needs to watch the tmux panes and intervene when agents get stuck, ask questions, or finish their work.

aoaoe is that someone -- except it is an LLM. It polls your AoE sessions, reads agent output, decides when to act, and executes without you needing to be there.

This is the conductor, not the orchestra. AoE manages the sessions. The agents inside do the coding. aoaoe watches everything and steps in when needed.

aoaoe runs in two modes:

1. AoE plugin (recommended for current AoE) -- installs into AoE's plugin system, appears in the dashboard, and drives sessions through the official plugin API. This is the direction agreed with the AoE maintainers in agent-of-empires#553 / PR #2699: orchestration ships as an installable plugin rather than inside AoE core.
2. Standalone daemon (the original mode) -- polls sessions via the aoe CLI and tmux directly. Full pane-content intelligence, works with older AoE versions.

Install as an AoE plugin

Requires AoE >= 1.13 (the plugin runtime) and Node >= 20 on the daemon host.

aoe plugin install gh:Talador12/agent-of-agent-of-empires

The install prompts for the capability grants declared in
aoe-plugin.toml and builds the worker into .aoe-build/.
Everything is dry-run by default: the orchestrator observes, ranks, and
recommends, but executes nothing until you flip the dry_run setting off in
AoE's plugin settings.

What you get:

• Attention queue -- every session ranked by who needs eyes next (status +
  time-in-status escalation), as a dashboard card, a sortable "Attention"
  column, row badges, and a per-session Orchestrator pane.
• Recommendations & notifications -- urgent sessions (errors, long waits)
  trigger deduplicated notifications with the reason.
• Spawn from GitHub issues -- the Orchestrator: spawn command creates one
  session per open issue in spawn_repo (via gh), each seeded with the issue
  as its goal and an idempotency key so reruns never double-spawn. Dry-run
  until spawn_live is enabled.
• Reasoners -- rules (deterministic, zero LLM cost, default), or
  claude-code / opencode for LLM-driven decisions.
• Commands -- Orchestrator: status / tick now / pause / resume / spawn
  in the command palette.

Guardrails: nudges are off by default (allow_nudge) and only ever reach
sessions the orchestrator itself created (enforced by the AoE host);
destructive actions have no plugin primitive at all; ticking has a 5s floor,
per-session action cooldowns, and optional quiet hours. See
DESIGN.md for the full architecture and the security model.

The rest of this README documents the standalone daemon mode.

Prerequisites

You need these installed first:

Tool	What it does	Install
tmux	Terminal multiplexer (AoE uses it)	brew install tmux
Agent of Empires	Manages AI agent sessions	See AoE README
OpenCode or Claude Code	LLM reasoning backend	npm i -g @anthropic-ai/claude-code or see OpenCode docs

Verify they're on your PATH:

aoe --version       # agent-of-empires
tmux -V             # tmux
opencode --version  # if using OpenCode backend
claude --version    # if using Claude Code backend

Install

Pick one:

# npm (recommended)
npm install -g aoaoe

# Homebrew
brew install Talador12/tap/aoaoe

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

# from source
git clone https://github.com/Talador12/agent-of-agent-of-empires
cd agent-of-agent-of-empires && npm install && npm run build && npm link

Verify:

aoaoe --version

Try It Alongside Running Sessions

Already have AoE sessions running? aoaoe is designed to run safely alongside them. Start with zero-risk commands and work your way up:

1. See what aoaoe sees (read-only, no LLM)

aoaoe test-context

Lists all your AoE sessions, resolves project directories, discovers context files (AGENTS.md, claude.md, etc.), and reports sizes. No LLM calls, no tmux writes, no side effects. This is just a diagnostic scan.

2. Full loop, actions only logged (costs LLM tokens)

aoaoe --dry-run

Runs the complete observe-reason-execute pipeline -- polls sessions, captures tmux output, calls the LLM for decisions -- but never executes actions. Instead of typing into your agents' tmux panes, it logs what it would do. Use this to verify the supervisor makes reasonable decisions before letting it act.

3. Full autonomous mode

aoaoe

The real deal. Polls, reasons, and executes -- sending keystrokes to agents, restarting crashed sessions, etc. You can still interrupt at any time with ESC ESC in the chat UI.

Mode	Reads sessions?	Calls LLM?	Touches agents?
test-context	Yes	No	No
--observe	Yes	No	No
--dry-run	Yes	Yes	No
--confirm	Yes	Yes	You approve each action
aoaoe	Yes	Yes	Yes

Self-improvement

aoaoe can supervise its own development. With an aoaoe AoE session open on this repo:

make setup   # install deps, build, create AoE session if missing (one-time)
make self    # aoaoe supervises itself: reads roadmap, implements, commits, pushes
make self-dry  # watch-only — see what it would do without letting it act

The goal in aoaoe.tasks.json drives the session: pick backlog items, implement with tests, commit atomically, push, tag releases. The daemon watches its own tmux pane and nudges the agent when it stalls or needs direction.

Quick Start

aoaoe has two parts: a daemon (the brain) and a chat UI (your window into it). Here's how to get both running.

Step 1: Have AoE sessions running

You need at least one AoE session for aoaoe to supervise. If you don't have any yet:

aoe add ./my-project -t my-agent -c "opencode"   # add an agent
aoe session start my-agent                         # start it
aoe                                                # enter AoE TUI to verify

Step 2: Register aoaoe as an AoE session (one-time)

This adds aoaoe's chat UI as a session inside AoE, so you can access it alongside your agents:

aoaoe register

This creates a session called "aoaoe" that runs the interactive chat UI. You only need to do this once.

Step 3: Start the daemon

In a separate terminal (or tmux pane, or backgrounded):

aoaoe

The daemon starts polling your AoE sessions, reasoning about what it sees, and executing actions. It logs to stderr so you can watch it work.

Step 4: Enter the chat UI

aoe session start aoaoe    # start the aoaoe session (if not already running)
aoe                        # enter AoE TUI, then select "aoaoe"

You're now in the chat UI. Type messages to the reasoner, run /overview to see what all agents are doing, or press ESC ESC to interrupt the current reasoning cycle.

Minimal example (all steps)

# Terminal 1: start the daemon
aoaoe

# Terminal 2: register + start + enter
aoaoe register
aoe session start aoaoe
aoe    # select "aoaoe" in the TUI

Using a different reasoning backend

# Use Claude Code instead of OpenCode
aoaoe --reasoner claude-code

# Use a specific model
aoaoe --reasoner opencode --model anthropic/claude-sonnet-4-20250514
aoaoe --reasoner claude-code --model claude-sonnet-4-20250514

Task System

aoaoe can automatically create and manage AoE sessions from a task list. Define repos you want to work on in aoaoe.tasks.json (next to your config file):

[
  {
    "repo": "github/adventure",
    "sessionTitle": "adventure",
    "sessionMode": "existing",
    "goal": "Process queued TODOs in this existing AoE session"
  },
  {
    "repo": "github/agent-of-agent-of-empires",
    "sessionTitle": "aoaoe-roadmap",
    "sessionMode": "new",
    "tool": "opencode",
    "goal": "Ship next roadmap item with tests"
  },
  {
    "repo": "github/cloud-hypervisor",
    "sessionMode": "auto",
    "goal": "Address PR review feedback"
  }
]

Field	Required	Description
repo	Yes	Path to the project directory (relative to cwd or absolute)
sessionTitle	No	AoE session title to target. Default: derived from repo basename
sessionMode	No	Session allocation strategy: existing (link only), new (create), auto (link or create). Default: auto
tool	No	Agent tool to use (opencode, claude-code, etc.). Default: opencode
goal	No	Goal text injected into the supervisor's context for this task

When the daemon starts, it now auto-imports any currently visible AoE sessions into the task list (mode=existing) so active and inactive sessions are immediately schedulable. Then it reconciles tasks: creates new AoE sessions when needed, links existing sessions by title, and starts linked sessions as needed. Progress is tracked persistently in ~/.aoaoe/task-state.json and survives session cleanup.

Interactive task updates (aoaoe task new/edit/rm or /task ...) also sync back to aoaoe.tasks.json, so your list evolves as you go.

The supervisor can report progress milestones and mark tasks complete via two special actions:

• report_progress — logs a milestone summary to persistent state
• complete_task — marks the task done and cleans up the session

View task status:

aoaoe tasks    # show task progress table

Daemon TUI Commands

The daemon runs an interactive TUI with a rich command set. These commands are available when the daemon is running (started with aoaoe).

Talking to the AI

Command	What it does
(any text)	Send a message -- queued for the next reasoning cycle
!message	Insist -- interrupt + deliver message immediately
/insist <msg>	Same as !message
/explain	Ask the AI to explain what's happening right now

Controls

Command	What it does
/pause	Pause the supervisor (stops reasoning)
/resume	Resume after pause
/mode [name]	Switch mode at runtime: observe, dry-run, confirm, autopilot (no arg = show current)
/interrupt	Interrupt the AI mid-thought
ESC ESC	Same as /interrupt (shortcut)

Navigation

Command	What it does
1-9	Quick-switch: jump to session N
/view [N|name]	Drill into a session's live output (default: 1)
/back	Return to overview from drill-down
/sort [mode]	Sort sessions: status, name, activity, health, default (no arg = cycle)
/compact	Toggle compact mode (dense session panel)
/pin [N|name]	Pin/unpin a session to the top
/bell	Toggle terminal bell on errors/completions
/focus	Toggle focus mode (show only pinned sessions)
/mute [N|name]	Mute/unmute a session's activity entries
/unmute-all	Unmute all sessions at once
/filter [tag]	Filter activity by tag -- presets: errors, actions, system (no arg = clear)
/who	Show fleet status: status, uptime, idle-since, context, errors, group, note
/uptime	Show session uptimes
/top [mode]	Rank sessions by errors (default), burn, or idle
/auto-pin	Toggle auto-pin on error
/note N|name text	Attach a note to a session (no text = clear)
/notes	List all session notes
/group N|name tag	Assign session to a group (lowercase, max 16 chars; no tag = clear)
/groups	List all groups and their members
/group-filter [tag]	Show only sessions in a group (no arg = clear)
/rename N|name [display]	Set custom TUI display name (no display = clear); persisted
/watchdog [N]	Alert if session stalls N minutes (default 10); /watchdog off to disable
/quiet-hours [H-H]	Suppress watchdog+burn alerts during hours (e.g. 22-06); no arg = clear
/broadcast <msg>	Send message to all sessions; /broadcast group:<tag> <msg> for group
/duplicate N [t]	Clone a session (same tool/path) with optional new title
/tag N tag1,tag2	Set freeform tags on a session (no tags = clear); /tags to list
/tag-filter [tag]	Show only sessions with given freeform tag (no arg = clear)
/color N [c]	Set accent dot color: lime amber rose teal sky slate (no color = clear)
/color-all [c]	Set accent color for all sessions at once
/mute-errors	Toggle suppression of error/! action entries in activity log
/pin-all-errors	Pin every session currently in error state
/pin-draining	Pin all draining sessions to the top
/labels	List all active session labels
/sort-by-health	Sort sessions by health score (worst first)
/icon N [emoji]	Set or clear a single emoji shown in the session row
/timeline N [n]	Show last n activity entries for a session (default 30)
/find <text>	Search all session pane outputs for text
/reset-health N	Clear error counts + context history to reset a session's health score
/prev-goal N [n]	Restore nth-most-recent goal for a session (default 1 = latest)
g1-g99	Quick-switch to session 10+ (e.g. g12 jumps to session 12)
/clip [N]	Copy last N activity entries to clipboard (default 20)
/diff N	Show activity since bookmark N
/mark	Bookmark current activity position
/jump N	Jump to bookmark N
/marks	List all bookmarks
/search <pattern>	Filter activity entries by substring (no arg = clear)
Click session	Click an agent card to drill down (click again to go back)
Mouse wheel	Scroll activity (overview) or session output (drill-down)
PgUp / PgDn	Scroll through activity or session output
Home / End	Jump to oldest / return to live

Info

Command	What it does
/status	Show daemon state (mode, reasoner, poll counts, last cycle)
/dashboard	Show full dashboard
/tasks	Show task progress table
/t ... /todo ... /idea ...	Aliases for /task ...
/task [sub] [args]	Task management (list, start, stop, edit, new, rm)
/task <session> :: <goal>	Fast path: update/create task for an existing session and set its goal
:<goal>	Fastest path in drill-down: set goal for that session
just type (in drill-down)	Default behavior: update goal for the focused session
/burn-rate	Show context token burn rates (tokens/min) for all sessions
/ceiling	Show context token usage vs limit for all sessions
/stats	Per-session health, errors (+trend), burn rate, context %, cost, uptime
/top [mode]	Rank sessions by errors (default), burn, or idle
/who	Fleet status: status, uptime, idle-since, cost, errors+trend, group, note
/snapshot [md]	Export session state snapshot to ~/.aoaoe/snapshot-<ts>.json (or .md)
/export-stats	Export /stats output to ~/.aoaoe/stats-<ts>.json
/session-report N	Full markdown report for one session → ~/.aoaoe/report-<name>-<ts>.md
/cost-summary	Show total estimated spend across all sessions
/recall <kw> [N]	Search 7-day persisted history for keyword
/history-stats	Aggregate stats from history: entry counts, top tags, span
/clear-history	Truncate ~/.aoaoe/tui-history.jsonl
/copy [N]	Copy session's current pane output to clipboard (default: current drill-down)
/alias /x /cmd	Create command alias (/x expands to /cmd); no args = list
/ctx-budget	Show context budget allocation across sessions (activity-weighted)
/profile [name]	Show active AoE profiles; optionally switch focus to a named profile
/replay <N|name> [lps]	Play back a session's stored pane output line by line (default 10 lps; run again to stop)
/notify-filter <session> <events...>	Set per-session webhook event filter (session_error, session_done, etc.); no args = list; clear = remove all

Other

Command	What it does
/verbose	Toggle detailed logging
/clear	Clear the screen
/help	Show all commands

TUI Features

• Activity sparkline -- 10-minute activity rate chart in the separator bar (Unicode blocks with color gradient)
• Activity sparkline -- 10-minute activity rate chart in the separator bar (Unicode blocks with color gradient)
• Session cards -- per-session status with pin ▲, mute ◌, note ✎, group ⊹tag, health ⬡N, color ●, tags [tag1,tag2], and activity rate 3/m indicators
• Health score -- composite 0–100 badge (errors, burn rate, context ceiling, stall time); LIME ≥80, AMBER ≥60, ROSE <60; also in compact mode
• Error sparklines -- ROSE 5-bucket mini-chart of recent error frequency in each card (last 5 min)
• Error trend -- ↑/→/↓ arrows in /stats and /who showing error direction
• Idle-since -- time since last output change in idle/done cards and /who output
• Cost tracking -- $N.NN spent parsed from pane output; shown in /stats, /who, /cost-summary
• Session grouping -- /group//group-filter for named group organization; ⊹tag badge in cards
• Session tagging -- /tag for multi-freeform-tag sets; /tag-filter panel filter; [tag1,tag2] badge
• Session rename -- /rename custom TUI display name (bold + original dim); persisted
• Session color -- /color accent ● dot per card (8 colors); /color-all for bulk set; persisted
• Watchdog -- /watchdog N fires on stall; suppressed during /quiet-hours; ⊛Nm header badge
• Burn-rate alerts -- auto "status" alert > 5k tokens/min; suppressed during quiet hours
• Context ceiling warning -- auto alert at 90% context when "X / Y tokens" format available
• Quiet hours -- /quiet-hours HH-HH suppresses watchdog + burn-rate alerts during set hours
• Session timeline -- /timeline N [n] shows last n activity entries filtered by session
• Session report -- /session-report N writes full markdown report to ~/.aoaoe/
• Snapshot export -- /snapshot [md] exports all session state to ~/.aoaoe/
• History search -- /recall <kw> searches 7-day persisted history; /history-stats shows aggregates
• Broadcast -- /broadcast [group:<tag>] <msg> sends to all or group-filtered sessions via tmux
• Duplicate -- /duplicate N [title] clones a session (same tool + path) with new title
• Ranked view -- /top [errors|burn|idle] composite attention ranking; /stats full per-session table
• Sticky preferences -- sort, compact, focus, bell, auto-pin, tag filter, aliases, groups, renames, colors, tags, quiet hours persist across restarts
• Filter pipeline -- mute → suppress (/mute-errors) → tag → search all compose
• Aliases -- /alias /x /cmd shortcuts; up to 50, persisted
• Activity heatmap -- 24-hour colored block chart via aoaoe stats
• Bookmarks -- mark positions, jump back, diff since a bookmark
• Clipboard export -- /clip and /copy copy activity or session pane output to clipboard
• Automatic context compaction -- when a session hits 80% context usage, daemon sends a compaction nudge via tmux; 10-min cooldown per session
• Multi-profile polling -- daemon polls all configured AoE profiles simultaneously; sessions deduped by ID across profiles
• Session replay -- /replay <N|name> [lps] plays back stored pane output in the activity log at configurable speed

Chat UI Commands

The chat UI (aoaoe-chat) runs inside an AoE tmux pane. Register it with aoaoe register, then access via aoe -> select "aoaoe".

Command	What it does
/overview	Show all AoE sessions with tasks, model, tokens, cost. Works without the daemon.
/tasks	Alias for /overview
/status	Daemon connection status + countdown to next reasoning cycle
/progress [--since --json]	What each session accomplished recently
/health	Per-session health scores (0-100) with fleet average
/incident [opts]	Incident quick view: response-flow runbook + recent events (--since, --limit, --json, --ndjson, --follow)
/runbook [section] [--json]	Print operator playbook slice (quickstart, response-flow/incident, all)
/supervisor [opts]	Judge/orchestrator status across tasks/sessions (--all, --since, --limit, --json)
/prompt-template [name]	Set/show reasoner strategy (default, hands-off, aggressive, review-focused, shipping)
/pin-save <name>	Save current pinned sessions as a named preset
/pin-load <name>	Restore a saved pin preset
/pin-presets	List saved pin presets
/interrupt	Interrupt the current reasoner call
/dashboard	Request full dashboard output from daemon
/pause	Pause the daemon (stops reasoning)
/resume	Resume after pause
/sessions	Instant session list from daemon state (no tmux capture needed)
/explain	Ask the AI to explain what's happening right now in plain English
/verbose	Toggle verbose logging
/clear	Clear the screen
/help	Show all commands
ESC ESC	Interrupt the reasoner (same as /interrupt)
(any text)	Send a message to the reasoner -- included in the next reasoning cycle

How /overview works

/overview captures every AoE pane directly via tmux and parses:

• Tasks: OpenCode TODO items ([*] done, [.] in progress, [o] pending)
• Model: Which LLM the agent is using (e.g. "Claude Opus 4.6")
• Context: Token count and cost
• Last line: Most recent meaningful output

This works standalone -- you don't need the daemon running.

How interrupt works

When the daemon is reasoning, press ESC ESC (or type /interrupt) to stop the current LLM call. The daemon will pause and wait for your input. Type a message and it will be included in the next reasoning cycle. This is useful when you want to redirect the supervisor's attention.

Daemon CLI

aoaoe [command] [options]

commands:
  (none)         start the supervisor daemon (interactive TUI)
  init           detect tools + sessions, import history, generate config
  status         quick daemon health check (is it running? what's it doing?)
  runbook        print operator quickstart for day-2 supervision
  runbook --json machine-readable runbook output for tooling
  runbook --section <quickstart|response-flow|incident|all> print only one runbook section
  incident       one-shot incident quick view (response-flow + recent activity)
  incident --since <duration>      filter incident event window (30m, 2h, 1d)
  incident --limit <N>             cap incident events shown (default: 5)
  incident --json                  machine-readable incident output
  incident --ndjson                emit compact one-line JSON snapshots
  incident --watch                 stream incident snapshots continuously
  incident --follow                shortcut for --watch --changes-only --heartbeat 30
  incident --changes-only          emit only when incident state changes (implies --watch)
  incident --heartbeat <sec>       keepalive interval (implies --changes-only + --watch)
  incident --interval <ms>         watch refresh interval (default: 5000, min: 500)
  supervisor     one-shot supervisor/task/session orchestration status
  supervisor --all                 show full recent supervisor event buffer
  supervisor --since <duration>    filter events to a time window (30m, 2h, 7d)
  supervisor --limit <N>           cap number of events shown (default: 5)
  supervisor --json                machine-readable output for automation
  supervisor --ndjson              emit compact one-line JSON snapshots
  supervisor --watch               stream supervisor snapshots continuously
  supervisor --changes-only        emit only when state changes (implies --watch)
  supervisor --heartbeat <sec>     keepalive interval (implies --changes-only + --watch)
  supervisor --interval <ms>       watch refresh interval (default: 5000, min: 500)
  config         show the effective resolved config (defaults + file)
  config --validate  validate config + check tool availability
  config --diff  show only fields that differ from defaults
  notify-test    send a test notification to configured webhooks
  doctor         comprehensive health check (config, tools, daemon, disk)
  logs           show recent conversation log entries
  logs --actions show action log entries (from ~/.aoaoe/actions.log)
  logs --grep <pattern>  filter log entries by substring or regex
  logs -n <count>        number of entries to show (default: 50)
  export         export session timeline as JSON or Markdown for post-mortems
  export --format <json|markdown>  output format (default: json)
  export --output <file>           write to file (default: stdout)
  export --last <duration>         time window: 1h, 6h, 24h, 7d (default: 24h)
  task           manage tasks and sessions (list, reconcile, start, stop, new, rm, edit, help)
  task templates show available task templates (roadmap, pr-review, bugfix, etc.)
  task new <t> <p> --template roadmap  create task with template goal
  task start-all|stop-all|pause-all|resume-all  batch fleet management
  tasks          show task progress (from aoaoe.tasks.json)
  tasks --json   machine-readable task state with live session status
  progress       per-session accomplishment digest (last 24h)
  progress --since <dur> --json  filter window + machine-readable output
  health         per-session health scores (0-100, fleet average)
  health --json  machine-readable health output
  adopt          import all untracked live AoE sessions as tasks
  adopt --template roadmap  apply a template goal to adopted sessions
  backup [path]  backup ~/.aoaoe/ state + config to tarball
  restore <path> restore from backup tarball or directory
  sync init <url> set up git-based state sharing with remote repo
  sync push       push local state to sync remote
  sync pull       pull remote state and restore locally
  sync diff       show changes since last push
  sync status     show sync repo status
  export --tasks  export task history as JSON or markdown
  export --tasks --format md  markdown format with progress timelines
  history        review recent actions (from ~/.aoaoe/actions.log)
  test-context   scan sessions + context files (read-only, no LLM, safe)
  test           run integration tests (requires aoe, opencode, tmux)
  register       register aoaoe as an AoE session (one-time setup)

options:
  --reasoner <opencode|claude-code>  reasoning backend (default: opencode)
  --poll-interval <ms>               poll interval in ms (default: 10000)
  --port <number>                    opencode server port (default: 4097)
  --health-port <number>             start HTTP health check server on this port
  --model <model>                    model to use
  --profile <name>                   aoe profile (default: default)
  --dry-run                          run full loop but only log actions (costs
                                     LLM tokens, but never touches sessions)
  --observe                          observe only — no LLM calls, no execution,
                                      zero cost. shows what the daemon sees.
  --confirm                          ask before each action — the AI proposes,
                                      you approve with y/n before it runs.
  --verbose, -v                      verbose logging
  --help, -h                         show help
  --version                          show version

init options:
  --force, -f                        overwrite existing config

register options:
  --title, -t <name>                 session title in AoE (default: aoaoe)

Supervisor Streaming Examples

# Human-readable watch output (change-only)
aoaoe supervisor --watch --changes-only --heartbeat 60

# NDJSON stream for pipes/collectors
aoaoe supervisor --watch --ndjson --changes-only --heartbeat 30

# Filter to the last 2 hours and show only 20 events
aoaoe supervisor --since 2h --limit 20

JSON/NDJSON payloads include emitReason with one of:

• snapshot (one-shot invocation)
• interval (periodic watch tick)
• change (watch emission caused by state change)
• heartbeat (keepalive emission from --heartbeat)

Incident Streaming Examples

# One-shot incident snapshot (human readable)
aoaoe incident --since 30m --limit 10

# Fast follow mode (alias for --watch --changes-only)
aoaoe incident --follow --heartbeat 30 --ndjson

# NDJSON incident stream for monitors (change-only + keepalive)
aoaoe incident --watch --ndjson --changes-only --heartbeat 30

# JSON watch stream (compact one object per tick in watch mode)
aoaoe incident --watch --json --interval 5000

Operator Playbook

Use this when running aoaoe as a long-lived judge over many AoE sessions.

# 1) Start low-noise supervision stream in a side pane
aoaoe supervisor --watch --ndjson --changes-only --heartbeat 30

# 2) If sessions/tasks drift, force immediate reconciliation
aoaoe task reconcile

# 3) If a specific session needs new direction, inject a goal quickly
aoaoe-chat
# then type: /task <session> :: <new goal>

Recommended response flow:

• emitReason=change spikes: inspect /supervisor --since 30m --limit 20
• stalled task (pending/paused too long): run aoaoe task reconcile, then nudge via /task ... :: ...
• noisy but unchanged systems: keep --changes-only --heartbeat 30 so monitors still get liveness

Task Templates

Create tasks with built-in goal presets instead of writing JSON by hand:

aoaoe task templates                       # list available templates
aoaoe task new my-project ./path --template roadmap
aoaoe task new bugfix-auth ./path --template bugfix

Built-in templates: roadmap, roadmap-strict, pr-review, bugfix, explore, ci-fix

Custom templates: add to ~/.aoaoe/templates.json

Prompt Templates

Switch the reasoner's supervision strategy at runtime:

/prompt-template hands-off    # minimal intervention
/prompt-template aggressive   # proactive nudging
/prompt-template shipping     # focus on commits and pushes

Or set in config: "promptTemplate": "hands-off"

Pin Presets

Save and restore named sets of pinned sessions:

/pin-save work              # save current pins
/pin-load work              # restore later
/pin-presets                # list all saved presets

Configuration

Config lives at ~/.aoaoe/aoaoe.config.json (canonical, written by aoaoe init). A local aoaoe.config.json in cwd overrides for development. Defaults work fine without a config file:

{
  "reasoner": "opencode",
  "pollIntervalMs": 10000,
  "opencode": {
    "port": 4097,
    "model": "anthropic/claude-sonnet-4-20250514"
  },
  "claudeCode": {
    "model": "claude-sonnet-4-20250514",
    "yolo": true,
    "resume": true
  },
  "aoe": {
    "profile": "default"
  },
  "policies": {
    "maxIdleBeforeNudgeMs": 120000,
    "maxErrorsBeforeRestart": 3,
    "autoAnswerPermissions": true
  },
  "sessionDirs": {
    "adventure": "github/adventure",
    "cloudchamber": "cc/cloudchamber"
  },
  "contextFiles": [],
  "notifications": {
    "webhookUrl": "https://example.com/webhook",
    "slackWebhookUrl": "https://hooks.slack.com/services/T.../B.../xxx",
    "events": ["session_error", "session_done", "daemon_started", "daemon_stopped"]
  }
}

Field	Description	Default
reasoner	"opencode" or "claude-code"	"opencode"
pollIntervalMs	How often to check AoE sessions (ms)	10000
opencode.port	Port for opencode serve	4097
opencode.model	Model in provider/model format	(OpenCode default)
claudeCode.model	Anthropic model name	(Claude Code default)
claudeCode.yolo	Skip permissions in Claude Code	true
claudeCode.resume	Maintain session across calls	true
aoe.profile	AoE profile to monitor	"default"
policies.maxIdleBeforeNudgeMs	Nudge idle agents after this long	120000
policies.maxErrorsBeforeRestart	Restart after N consecutive errors	3
policies.autoAnswerPermissions	Auto-approve permission prompts	true
policies.allowDestructive	Allow remove_agent and stop_session actions	false
policies.maxStuckNudgesBeforePause	Auto-pause task after N nudges with no progress (0 = disabled)	0
policies.quietHours	Skip reasoning during these hours, e.g. "01:00-06:00" (polling continues)	(none)
promptTemplate	Reasoner prompt strategy: default, hands-off, aggressive, review-focused, shipping	"default"
policies.userActivityThresholdMs	Ignore sessions with recent human keystrokes	30000
policies.actionCooldownMs	Minimum ms between actions on the same session	30000
protectedSessions	Session titles that are observe-only (no actions)	[]
sessionDirs	Map session titles to project directories (relative to cwd or absolute). Bypasses heuristic directory search.	{}
contextFiles	Extra AI instruction file paths to load from each project root	[]
captureLinesCount	Number of tmux lines to capture per session (-S flag)	100
healthPort	Start HTTP health check server on this port (e.g. 4098). GET /health returns JSON status.	(none)
notifications.webhookUrl	Generic webhook URL (POST JSON)	(none)
notifications.slackWebhookUrl	Slack incoming webhook URL (block kit format)	(none)
notifications.events	Filter which events fire (omit to send all). Valid: session_error, session_done, action_executed, action_failed, daemon_started, daemon_stopped	(all)
notifications.maxRetries	Retry failed webhook deliveries with exponential backoff (1s, 2s, 4s, ...)	0 (no retry)
tuiHistoryRetentionDays	How many days of TUI history to replay on startup (1-365)	7

Also reads .aoaoe.json as an alternative config filename.

sessionDirs — explicit project directory mapping

By default, aoaoe resolves project directories by searching subdirectories (up to 2 levels deep) for a folder name matching each session title. This works great for standard layouts like repos/github/adventure/.

For non-standard layouts or when the session title doesn't match the directory name, use sessionDirs to provide explicit mappings:

{
  "sessionDirs": {
    "adventure": "github/adventure",
    "cloudchamber": "cc/cloudchamber",
    "my-agent": "/absolute/path/to/project"
  }
}

Paths can be relative (resolved from the directory where you run aoaoe) or absolute. Case-insensitive matching is used for session title lookup. If a mapped path doesn't exist on disk, aoaoe falls back to heuristic search.

Use aoaoe test-context to verify resolution.

notifications — webhook alerts for daemon events

aoaoe can send webhook notifications when significant events occur (session errors, task completions, daemon start/stop). Supports generic JSON webhooks and Slack incoming webhooks with block kit formatting.

{
  "notifications": {
    "webhookUrl": "https://example.com/webhook",
    "slackWebhookUrl": "https://hooks.slack.com/services/T.../B.../xxx",
    "events": ["session_error", "session_done", "daemon_started", "daemon_stopped"]
  }
}

Both webhook URLs are optional — configure one or both. The events array filters which event types fire (omit it to receive all events). Notifications are fire-and-forget with a 5s timeout and 60s rate limiting per event+session combo to prevent spam.

Run aoaoe notify-test to verify your webhook configuration.

How It Works

┌──────────────────────────────────────────────────────┐
│                    aoaoe daemon                      │
│                                                      │
│  ┌───────────┐   ┌─────��────────┐   ┌───────────┐    │
│  │  Poller   │──▶│   Reasoner   │──▶│ Executor  │    │
│  │           │   │ ┌──────────┐ │   │           │    │
│  │ aoe CLI + │   │ │ OpenCode │ │   │ tmux send │    │
│  │ tmux cap  │   │ │  server  │ │   │ keys, aoe │    │
│  │           │   │ ├──────────┤ │   │ CLI cmds  │    │
│  │           │   │ │  Claude  │ │   │           │    │
│  │           │   │ │   Code   │ │   │           │    │
│  │           │   │ └──────────┘ │   │           │    │
│  └───────────��   └──────────────┘   └───────────┘    │
│                                                      │
│  ┌────────────────────────────────────────────────┐  │
│  │           Chat UI (aoaoe-chat)                 │  │
│  │    runs inside AoE tmux pane, reads state      │  │
│  │    from ~/.aoaoe/ via file-based IPC           │  │
│  └────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────┘
         │                              │
         ▼                              ▼
    AoE sessions                  LLM Provider
    (tmux panes)              (local or remote)

Three loops

Poller (every N seconds, configurable):

• Calls aoe list --json to get all session IDs, statuses, and tools
• For each active session: tmux capture-pane -t <session> -p -S -100
• Diffs against previous capture to detect new output
• Builds an observation payload

Reasoner (on new observations):

• Sends observation to the configured LLM backend
• System prompt defines the supervisor role, policies, and available actions
• Receives back a structured JSON action decision

Executor (on decisions):

• tmux send-keys -- inject a prompt into an agent
• aoe session start/stop/restart -- lifecycle management
• aoe add / aoe remove -- spawn or tear down agents

Supervisor behavior

The LLM supervisor follows these policies:

• If an agent is stuck or idle too long, nudge it with context or a rephrased task
• If an agent asks a question and is waiting for input, answer it
• If an agent finishes its task, acknowledge and optionally assign follow-up work
• If a session crashes, restart it
• Do NOT micromanage -- only intervene when there is a clear problem or decision needed

Available actions

The reasoner returns structured JSON decisions:

{ "action": "send_input", "session": "<id>", "text": "<prompt>" }
{ "action": "start_session", "session": "<id>" }
{ "action": "stop_session", "session": "<id>" }
{ "action": "create_agent", "path": "<dir>", "title": "<name>", "tool": "<agent>" }
{ "action": "remove_agent", "session": "<id>" }
{ "action": "report_progress", "session": "<id>", "summary": "<milestone>" }
{ "action": "complete_task", "session": "<id>", "summary": "<final status>" }
{ "action": "wait" }

Reasoning Backends

Backend	Interface	Stateful	Model Flexibility
OpenCode	opencode serve + SDK	Yes (long-running session)	Any provider via OpenCode config
Claude Code	claude --print subprocess	Via --resume	Anthropic models

OpenCode backend

Runs opencode serve as a headless HTTP server. Uses the OpenCode JS SDK to maintain a long-running session with full context. Works with any model provider configured in OpenCode (Anthropic, OpenAI, Ollama, etc.).

Claude Code backend

Calls claude --print --output-format json as a subprocess. System prompt injected via --append-system-prompt. Session continuity via --resume <session_id>.

IPC and State Files

The daemon and chat UI communicate via files in ~/.aoaoe/:

File	Written by	Read by	Purpose
daemon-state.json	daemon	chat UI	Current phase, countdown, per-session state
conversation.log	daemon	chat UI	Observations, reasoning, actions log
pending-input.txt	chat UI	daemon	User messages queued for next reasoning cycle
interrupt	chat UI	daemon	Flag file -- presence triggers interrupt
chat.pid	chat UI	daemon	Chat process PID for detection
actions.log	daemon	--	Persistent action history (JSONL)

Intelligence Modules

aoaoe includes 196 intelligence modules that run every daemon tick without LLM calls — pure computation, zero runtime dependencies. They cover fleet observability, cost management, goal tracking, scheduling, health monitoring, and operator tooling.

Reasoning Pipeline (8 gates, runs before every LLM call):

• Token quota → fleet rate limiter → observation cache → priority filter → context compressor → LLM call → approval workflow → cost tracker

Core Per-Tick Autonomous Systems:

• Session summarizer, conflict detector + auto-resolver, goal completion detector, cost budget enforcer
• Adaptive poll controller, fleet SLA monitor, progress velocity tracker, recovery playbook
• Dependency scheduler, session graduation (trust ladder), workflow engine

Fleet Intelligence (on-demand via 197 TUI /commands):

• Cost tracking: budgets, forecasts, trends, anomalies, chargebacks, optimization recommendations
• Goal management: auto-priority, cascading, decomposition, NL parsing, confidence estimation, burndown charts
• Observability: incident timeline, event bus, health scoring, diagnostics, structured logs, pattern evolution
• Operations: shift handoff, compliance, runbooks, auto-scaler, canary mode, graceful shutdown
• API: REST server with OpenAPI spec, SSE events, webhooks, bearer auth, rate limiting, pagination

See AGENTS.md for the full module list with descriptions.

Project Structure

src/
  # ── core daemon (the 15 files that make it go) ──
  index.ts            # daemon entry point, main loop, subcommands
  loop.ts             # extracted tick logic (poll->reason->execute), testable with mocks
  config.ts           # config loader, CLI arg parser, validation
  types.ts            # shared types (SessionSnapshot, Action, DaemonState, etc.)
  poller.ts           # aoe CLI + tmux capture-pane wrapper
  executor.ts         # maps action decisions to shell commands
  tui.ts              # in-place terminal UI (alternate screen, scroll, sparklines)
  input.ts            # stdin readline + keypress handlers (/commands)
  init.ts             # `aoaoe init`: auto-discover tools, generate config
  context.ts          # discoverContextFiles, resolveProjectDir, loadSessionContext
  health.ts           # HTTP health check endpoint
  daemon-state.ts     # IPC state file + interrupt flag
  task-manager.ts     # task orchestration: definitions, persistent state

  # ── reasoner backends ──
  reasoner/
    index.ts          # common Reasoner interface + factory
    prompt.ts         # system prompt + observation formatting
    parse.ts          # response parsing, JSON extraction, action validation
    opencode.ts       # OpenCode HTTP backend (native fetch to opencode serve)
    claude-code.ts    # Claude Code subprocess backend (claude --print)

  # ── CLI tools ──
  chat.ts             # interactive chat UI (aoaoe-chat binary)
  tail.ts             # live-stream daemon activity to another terminal
  stats.ts            # aggregate statistics + activity heatmap
  replay.ts           # play back tui-history.jsonl with timing
  export.ts           # timeline export (JSON/Markdown)

  # ── 196 intelligence modules (*.ts + *.test.ts pairs) ──
  # fleet observability, cost management, goal tracking, scheduling,
  # health monitoring, operator tooling — see AGENTS.md for full list

Related Projects

• Agent of Empires -- the session manager this project controls
• OpenCode -- AI coding agent, used as a reasoning backend
• Claude Code -- Anthropic's CLI agent, used as a reasoning backend

License

MIT License -- see LICENSE for details.