How AO turns one task into a durable, observable coding agent.
Agent Orchestrator (AO) is a pluggable TypeScript monorepo for spawning AI coding agents in isolated workspaces, supervising their lifecycle, wiring PR/CI/review feedback loops, and exposing all of it through a Next.js dashboard with live terminal attachment.
packages/**One-screen architecture
The high-level model in CLAUDE.md describes AO as parallel AI coding agents, each in an isolated git worktree with its own PR, supervised from one dashboard CLAUDE.md:3-5. The source verifies that the implementation is centered on a small core, pluggable edges, and flat-file persistence.
flowchart LR
User["Human / Orchestrator"]:::user --> CLI["ao CLI\nstart · spawn · stop · restore"]:::cli
CLI --> Core["@aoagents/ao-core\nConfig · Registry · Session Manager\nLifecycle Manager · Metadata"]:::core
Config["agent-orchestrator.yaml\nZod validated"]:::file --> Core
subgraph Slots["Plugin extension boundary"]
Runtime["Runtime\ntmux / process"]:::runtime
Agent["Agent\nClaude Code / Codex / OpenCode / Aider / Cursor"]:::agent
Workspace["Workspace\nworktree / clone"]:::workspace
Tracker["Tracker\nGitHub / Linear / GitLab"]:::tracker
SCM["SCM\nPR · CI · reviews"]:::scm
Notifier["Notifier\ndesktop / Slack / Discord / webhook"]:::notifier
Terminal["Terminal\niTerm2 / web"]:::terminal
end
Core --> Runtime
Core --> Agent
Core --> Workspace
Core --> Tracker
Core --> SCM
Core --> Notifier
Core --> Terminal
Core --> Lifecycle["Lifecycle\ncore state machine + poller"]:::lifecycle
Lifecycle --> Events["Events + reactions"]:::event
Events --> Notifier
Core --> Store["Flat-file state\n~/.agent-orchestrator"]:::file
Core --> WebAPI["Next.js API routes"]:::web
WebAPI --> Mux["Mux WebSocket\nsession snapshots + terminal streams"]:::web
Mux --> Dashboard["React dashboard\nKanban + xterm.js"]:::web
classDef core fill:#172554,stroke:#60a5fa,color:#eff6ff,stroke-width:2px;
classDef cli fill:#0f172a,stroke:#94a3b8,color:#e2e8f0;
classDef file fill:#1e293b,stroke:#64748b,color:#e2e8f0;
classDef user fill:#312e81,stroke:#a78bfa,color:#f5f3ff;
classDef runtime fill:#164e63,stroke:#22d3ee,color:#ecfeff;
classDef agent fill:#4c1d95,stroke:#a78bfa,color:#faf5ff;
classDef workspace fill:#064e3b,stroke:#34d399,color:#ecfdf5;
classDef tracker fill:#78350f,stroke:#fbbf24,color:#fffbeb;
classDef scm fill:#831843,stroke:#f472b6,color:#fdf2f8;
classDef notifier fill:#7c2d12,stroke:#fb923c,color:#fff7ed;
classDef terminal fill:#1e3a8a,stroke:#60a5fa,color:#eff6ff;
classDef lifecycle fill:#7f1d1d,stroke:#fb7185,color:#fff1f2;
classDef web fill:#0f766e,stroke:#2dd4bf,color:#f0fdfa;
classDef event fill:#3f3f46,stroke:#a1a1aa,color:#fafafa;
Core owns orchestration
session-manager.ts owns spawn/kill/restore/send, while lifecycle-manager.ts owns detection, state transitions, reactions, and notifications packages/core/src/session-manager.ts:1-12 packages/core/src/lifecycle-manager.ts:1-10.
Plugins own replaceable integrations
The public contract is PluginModule<T>: a manifest, a create function, and optional detection. The registry normalizes default/named exports and loads built-ins/configured plugins packages/core/src/types.ts:1728-1753 packages/core/src/plugin-registry.ts:297-312.
Files are the database
Session metadata lives under ~/.agent-orchestrator/projects/{projectId}/sessions/{sessionId}.json; status is computed from canonical lifecycle when read packages/core/src/metadata.ts:1-11 packages/core/src/metadata.ts:159-163.
Repository layout and build topology
The root workspace includes both first-party packages and plugin packages via packages/* and packages/plugins/* pnpm-workspace.yaml:1-3. The root build script runs recursive pnpm builds package.json:12-27; workspace dependencies make the effective topology core → plugins → cli/web, matching the high-level docs CLAUDE.md:11-33.
flowchart TB Root["Root workspace\nNode >=20.18.3 · pnpm 9.15.4"]:::root --> Core["packages/core\ninterfaces · config · lifecycle · metadata"]:::core Root --> Plugins["packages/plugins/*\nagent · runtime · workspace · tracker · scm · notifier · terminal"]:::plugins Root --> CLI["packages/cli\nao command · start/stop · supervisor"]:::app Root --> Web["packages/web\nNext.js 15 dashboard · mux WS · xterm.js"]:::app Root --> AO["packages/ao\nglobal CLI wrapper"]:::app Root --> Tests["packages/integration-tests"]:::test Root --> NotifierMac["packages/notifier-macos"]:::plugins Core --> Plugins Core --> CLI Core --> Web Plugins --> CLI Plugins --> Web Web --> CLI classDef root fill:#0f172a,stroke:#94a3b8,color:#f8fafc; classDef core fill:#172554,stroke:#60a5fa,color:#eff6ff,stroke-width:2px; classDef plugins fill:#312e81,stroke:#a78bfa,color:#f5f3ff; classDef app fill:#064e3b,stroke:#34d399,color:#ecfdf5; classDef test fill:#78350f,stroke:#fbbf24,color:#fffbeb;
| Layer | What lives there | Representative source |
|---|---|---|
| Core | Typed integration contracts, config loader, plugin registry, lifecycle, session manager, path and metadata helpers. | packages/core/src/types.ts:3-18 |
| Plugins | Concrete implementations. For example, tmux exports a runtime manifest/create/default module and Codex exports an agent manifest/create/detect/default module. | packages/plugins/runtime-tmux/src/index.ts:21-26 packages/plugins/agent-codex/src/index.ts:41-47 |
| CLI | Packages the command surface and depends on core, web, and many built-in plugins. | packages/cli/package.json:35-61 |
| Web | Next.js dashboard, API routes, WebSocket mux, xterm.js terminal client; depends on core, selected plugins, Next/React/ws/xterm. | packages/web/package.json:48-70 |
Why this split?
The core stays stable and testable while every environment-specific edge is swappable. New agents, SCMs, notifiers, or terminal UIs can be introduced as packages without changing the state machine or session manager contracts.
The plugin-slot model
AO documents eight architectural slots, but the TypeScript PluginSlot union exposes seven loadable plugin slots; Lifecycle is intentionally core/non-pluggable CLAUDE.md:80-96 packages/core/src/types.ts:1718-1726. The interfaces are all centralized in types.ts, which makes plugin changes explicit and reviewable packages/core/src/types.ts:3-18.
| Slot | Interface lines | Responsibility | Examples / defaults |
|---|---|---|---|
| Runtime | packages/core/src/types.ts:386-424 | Create, attach to, send input to, and destroy the process environment where an agent runs. | tmux, process |
| Agent | packages/core/src/types.ts:477-576 | Define how to detect, launch, prompt, and observe a particular coding tool. | Claude Code, Codex, OpenCode, Aider, Cursor, Grok, Kimi |
| Workspace | packages/core/src/types.ts:650-688 | Create isolated code workspaces and clean/restore them. | worktree, clone |
| Tracker | packages/core/src/types.ts:707-749 | Fetch issue/task context and update external task status. | GitHub, GitLab, Linear |
| SCM | packages/core/src/types.ts:786-900 | Inspect branches, PRs, CI checks, review comments, and mergeability. | GitHub, GitLab |
| Notifier | packages/core/src/types.ts:1160-1181 | Deliver lifecycle and attention notifications to humans. | Desktop, Slack, Discord, webhook, Composio |
| Terminal | packages/core/src/types.ts:1196-1215 | Open or attach a human-facing terminal UI. | iTerm2, web terminal |
| Lifecycle | packages/core/src/lifecycle-manager.ts:1-10 | Core state machine, polling loop, reactions, escalation, cleanup. Not a registry plugin. | Built into @aoagents/ao-core |
Registry and discovery
Built-in packages are enumerated by slot in plugin-registry.ts packages/core/src/plugin-registry.ts:38-72. The registry supports register, get, list, loadBuiltins, and loadFromConfig packages/core/src/plugin-registry.ts:420-623.
Export contract
A plugin module exports manifest, create(config?), and optional detect. The registry also handles default-export modules packages/core/src/types.ts:1728-1753 packages/core/src/plugin-registry.ts:297-312.
// Shape verified in packages/core/src/types.ts:1728-1753
export interface PluginModule<T> {
manifest: PluginManifest;
create(config?: Record<string, unknown>): T | Promise<T>;
detect?(): Promise<boolean>;
}Canonical state machine + derived legacy status
AO separates durable lifecycle truth from UI/back-compat display status. Canonical lifecycle has eight states and structured reasons packages/core/src/types.ts:29-57; legacy SessionStatus remains a broader display/API vocabulary packages/core/src/types.ts:118-137.
stateDiagram-v2
[*] --> not_started: metadata reserved
not_started --> working: runtime created + agent launched
working --> idle: ready / no activity / waiting on PR
working --> needs_input: agent explicitly waits for human
working --> detecting: runtime or agent signal is uncertain
working --> done: agent reports completion without further action
working --> terminated: fatal reason
idle --> working: new activity / human sends instruction
idle --> detecting: stale runtime suspicion
idle --> terminated: auto_cleanup / pr_merged / manually_killed
needs_input --> working: human response sent
needs_input --> stuck: waiting too long / escalation exhausted
needs_input --> terminated: manually_killed
detecting --> working: probe resolves alive
detecting --> stuck: probe cannot recover
detecting --> terminated: runtime_lost / probe_failure / agent_process_exited
stuck --> working: agent recovers / restore succeeds
stuck --> terminated: manually_killed / error_in_process
done --> [*]
terminated --> [*]
note right of terminated
Terminal reasons include:
manually_killed, pr_merged, auto_cleanup,
runtime_lost, agent_process_exited,
probe_failure, error_in_process
end note
Canonical storage
createInitialCanonicalLifecycle creates new lifecycle objects, while parseCanonicalLifecycle accepts new lifecycle or legacy statePayload data packages/core/src/lifecycle-state.ts:162-193 packages/core/src/lifecycle-state.ts:415-430.
Legacy status is computed
deriveLegacyStatus maps canonical state/reason and PR runtime metadata into UI statuses. Metadata patches deliberately do not persist status; it is computed on read packages/core/src/lifecycle-state.ts:432-488 packages/core/src/lifecycle-state.ts:490-505.
Why canonical vs legacy?
Canonical lifecycle keeps the durable state space compact and reasoned: terminated plus runtime_lost is different from terminated plus pr_merged. The old status vocabulary can still represent dashboard buckets like ci_failed, review_pending, approved, or mergeable by deriving them from canonical lifecycle plus PR state packages/core/src/lifecycle-state.ts:432-488.
Detection and precedence
determineStatus probes runtime, agent activity/process, PR state, fresh self-reports, idle thresholds, and uncertain detecting decisions packages/core/src/lifecycle-manager.ts:900-1397. Fresh agent reports outrank weak inference, but not runtime death, waiting-input, or SCM truth packages/core/src/lifecycle-manager.ts:1299-1328.
Polling and reactions
The manager enriches PR metadata, checks each session, persists transitions, emits events, notifies humans, dispatches CI/review/conflict work, and performs merge cleanup last packages/core/src/lifecycle-manager.ts:530-748 packages/core/src/lifecycle-manager.ts:2438-2765.
Poll
pollAll lists sessions, batch-enriches PRs, checks sessions concurrently, prunes old state, and can stop when all work is complete packages/core/src/lifecycle-manager.ts:2865-3043.
Decide
resolveProbeDecision is part of the path that turns uncertain runtime/activity evidence into a stable lifecycle transition packages/core/src/lifecycle-manager.ts:1202-1214.
React
Reactions can retry, escalate, send instructions to agents, and call notifiers packages/core/src/lifecycle-manager.ts:1399-1624 packages/core/src/lifecycle-manager.ts:2261-2307.
Clean
PR merge cleanup is intentionally deferred while agents are busy and delegates deletion to sessionManager.kill when safe packages/core/src/lifecycle-manager.ts:2309-2436.
Spawn, list, kill, send, restore
The session manager is the imperative coordinator. Its own header summarizes the contract: create workspace, create runtime, launch agent, list metadata plus live runtime state, kill, cleanup, and send packages/core/src/session-manager.ts:1-12.
flowchart LR Task["User task / issue"] --> Resolve["Resolve project + plugins"]:::core Resolve --> Tracker["Fetch issue context\n(optional tracker)"]:::tracker Tracker --> Reserve["Reserve session id\nO_EXCL metadata"]:::file Reserve --> Branch["Compute branch"]:::workspace Branch --> Workspace["workspace.create + hooks"]:::workspace Workspace --> Prompt["buildPrompt\nbase + config + rules + task"]:::prompt Prompt --> AgentConfig["agent.getLaunchConfig"]:::agent AgentConfig --> Runtime["runtime.create\nAO env vars"]:::runtime Runtime --> Metadata["write metadata\ncanonical lifecycle"]:::file Metadata --> Post["postLaunchSetup / initial send"]:::agent classDef core fill:#172554,stroke:#60a5fa,color:#eff6ff; classDef tracker fill:#78350f,stroke:#fbbf24,color:#fffbeb; classDef file fill:#1e293b,stroke:#64748b,color:#e2e8f0; classDef workspace fill:#064e3b,stroke:#34d399,color:#ecfdf5; classDef prompt fill:#312e81,stroke:#a78bfa,color:#f5f3ff; classDef agent fill:#4c1d95,stroke:#a78bfa,color:#faf5ff; classDef runtime fill:#164e63,stroke:#22d3ee,color:#ecfeff;
| Operation | What it does | Source |
|---|---|---|
| Resolve plugins | Locates project-scoped runtime/agent/workspace/tracker/scm/notifier/terminal instances through the registry. | packages/core/src/session-manager.ts:902-918 |
| Spawn | Reserves IDs, creates workspace, builds prompt, configures agent, creates runtime with AO environment, writes metadata, then does post-launch setup. Rollback is guarded by a cleanup stack. | packages/core/src/session-manager.ts:1212-1598 |
| Orchestrator spawn | Uses the same primitives but launches an AO orchestrator session with generated prompt and permissionless settings. | packages/core/src/session-manager.ts:1619-2070 packages/core/src/session-manager.ts:1871-1888 |
| List / get | Reads metadata across projects, enriches runtime state, and computes display status. get fetches one enriched record. | packages/core/src/session-manager.ts:2235-2368 packages/core/src/session-manager.ts:2386-2443 |
| Kill / cleanup | Destroys runtime and workspace, handles idempotency, and writes canonical terminated lifecycle. | packages/core/src/session-manager.ts:2445-2607 packages/core/src/session-manager.ts:2609-2801 |
| Send / restore | Prepares or restores runtime as needed, sends input, and can rebuild workspace/runtime for restorable sessions. | packages/core/src/session-manager.ts:2803-3119 packages/core/src/session-manager.ts:3271-3618 |
| Claim PR | Attaches an existing pull request to a session record. | packages/core/src/session-manager.ts:3121-3244 |
Important invariant: list can detect stale runtimes, but not terminate them
sessionManager.list() may persist a detecting state with runtime_lost when a tmux/process runtime disappears, but comments make the lifecycle manager the “single authority on terminal decisions” packages/core/src/session-manager.ts:2303-2306 packages/core/src/session-manager.ts:2324-2348.
Flat files, no database
AO persists durable state in YAML and JSON files under a project-oriented layout. Current V2 paths are under ~/.agent-orchestrator/projects/{projectId}; older hash-based helpers remain marked deprecated/legacy in paths.ts packages/core/src/metadata.ts:1-11 packages/core/src/paths.ts:1-15 packages/core/src/paths.ts:152-200.
flowchart TB
LocalConfig["agent-orchestrator.yaml\nnearest config found from cwd"]:::yaml
GlobalConfig["~/.agent-orchestrator/config.yaml\nregistered projects + identity"]:::yaml
Home["~/.agent-orchestrator"]:::dir
Home --> GlobalConfig
Home --> Running["running.json\ncurrent ao start PID / port / projects"]:::json
Home --> LastStop["last-stop.json\nsessions stopped by ao stop / Ctrl+C"]:::json
Home --> Projects["projects/{projectId}/"]:::dir
Projects --> Sessions["sessions/{sessionId}.json\nsession metadata + lifecycle"]:::json
Projects --> Orchestrator["orchestrator.json\norchestrator session metadata"]:::json
Projects --> Worktrees["worktrees/{sessionId}/\nagent workspaces"]:::dir
Projects --> Feedback["feedback / code-reviews"]:::dir
LocalConfig --> Loader["loadConfig()\nYAML + Zod + defaults"]:::core
GlobalConfig --> Loader
classDef yaml fill:#312e81,stroke:#a78bfa,color:#f5f3ff;
classDef json fill:#1e293b,stroke:#94a3b8,color:#e2e8f0;
classDef dir fill:#064e3b,stroke:#34d399,color:#ecfdf5;
classDef core fill:#172554,stroke:#60a5fa,color:#eff6ff;
Config
config.ts loads agent-orchestrator.yaml, validates with Zod, applies defaults, and expands paths packages/core/src/config.ts:1-11 packages/core/src/config.ts:247-381 packages/core/src/config.ts:927-959 packages/core/src/config.ts:996-1018. Resolution checks AO_CONFIG_PATH, cwd parents, global config, and legacy locations packages/core/src/config.ts:747-822.
Global project registry
The global config path can come from AO_GLOBAL_CONFIG, XDG, or ~/.agent-orchestrator/config.yaml packages/core/src/global-config.ts:75-99. It is loaded/saved atomically and merges global identity with local project behavior packages/core/src/global-config.ts:341-384 packages/core/src/global-config.ts:857-886.
Metadata
metadataPath, readMetadata, atomic writes, locked mutation, list, and O_EXCL ID reservation provide file-backed session state packages/core/src/metadata.ts:137-146 packages/core/src/metadata.ts:280-325 packages/core/src/metadata.ts:331-459 packages/core/src/metadata.ts:508-546.
CLI process state
running.json tracks the active ao start process and dashboard port; last-stop.json stores sessions killed by stop/Ctrl+C so startup can offer restore packages/cli/src/lib/running-state.ts:16-29 packages/cli/src/lib/running-state.ts:171-205 packages/cli/src/lib/running-state.ts:311-353.
Why flat files?
AO is a local developer tool that needs transparent, inspectable, crash-resilient state rather than a server database. Atomic JSON writes and file locks keep session metadata durable while keeping setup to “install packages and run ao start.”
From ao start to dashboard render
The user-facing flow begins in the CLI, starts the dashboard and project supervisors, ensures an orchestrator session, then uses core services and web API routes to render session state.
sequenceDiagram autonumber actor Human participant CLI as ao CLI participant Config as Config loader participant Registry as Plugin registry participant SM as SessionManager participant LM as LifecycleManager participant Store as Flat files participant API as Next.js API participant Mux as mux WebSocket participant UI as React dashboard Human->>CLI: ao start CLI->>Config: load agent-orchestrator.yaml + global config Config->>Registry: create registry + load/register plugins CLI->>SM: createSessionManager(config, registry) CLI->>API: start dashboard server CLI->>SM: ensure orchestrator session SM->>Store: write orchestrator/session metadata CLI->>LM: start per-project lifecycle worker LM->>SM: list sessions SM->>Store: read metadata + enrich runtime state LM->>Registry: query SCM / agent / runtime plugins LM->>Store: persist lifecycle transitions + events UI->>API: GET /api/sessions initial snapshot API->>SM: list/listCached sessions API->>Store: read supplemental metadata API-->>UI: sessions + stats + orchestrators UI->>Mux: open WebSocket Mux->>API: poll /api/sessions/patches every 3s Mux-->>UI: session snapshot / terminal messages UI-->>Human: Kanban, detail, xterm terminal
CLI startup
runStartup starts the dashboard and resolves the port, ensures an orchestrator session, starts the project supervisor, restores last-stop sessions if requested, then registers running.json with PID, config path, port, and projects packages/cli/src/commands/start.ts:900-949 packages/cli/src/commands/start.ts:953-1019 packages/cli/src/commands/start.ts:1021-1160 packages/cli/src/commands/start.ts:1746-1757.
Lifecycle workers
The project supervisor reconciles lifecycle workers based on non-terminal sessions and runs a 60-second supervisor loop. Each worker creates a lifecycle manager and starts it with the default 30-second interval packages/cli/src/lib/project-supervisor.ts:118-240 packages/cli/src/lib/lifecycle-service.ts:30-75.
Web services
Web uses a singleton service module to load dashboard config, create a registry, register static plugins, and create session/lifecycle managers. Comments clarify that CLI polling is authoritative and web lifecycle is mainly for webhook checks packages/web/src/lib/services.ts:1-13 packages/web/src/lib/services.ts:104-133.
API and live transport
/api/sessions lists, filters, serializes, and enriches sessions packages/web/src/app/api/sessions/route.ts:72-201. /api/sessions/patches returns lightweight dashboard patches from cached sessions packages/web/src/app/api/sessions/patches/route.ts:8-44.
Verified current-source note about SSE
Older high-level docs mention an SSE stream. In the current source inspected for this document, live dashboard updates are implemented through the mux WebSocket: the server polls /api/sessions/patches every 3 seconds and broadcasts snapshots, while the client merges mux updates and uses full refreshes for membership/staleness. No current text/event-stream/EventSource route was found in the web package during this audit packages/web/server/mux-websocket.ts:1-7 packages/web/server/mux-websocket.ts:77-198 packages/web/src/hooks/useSessionEvents.ts:148-340.
Dashboard, mux WebSocket, and xterm.js
The dashboard is a Next.js 15 app with React 19 and xterm.js. It reads session snapshots from API routes, subscribes to mux WebSocket messages, and renders project-scoped Kanban lanes while the sidebar can include all projects.
Session data
Dashboard.tsx calls useSessionEvents and intentionally does not filter session events by project at the hook boundary; it filters the Kanban client-side and groups sessions by attention level packages/web/src/components/Dashboard.tsx:146-179 packages/web/src/components/Dashboard.tsx:287-300.
Mux provider
MuxProvider builds the WebSocket URL, reconnects, re-opens terminal streams, subscribes to session and notification channels, and handles terminal/session/notification messages packages/web/src/providers/MuxProvider.tsx:84-237.
Terminal setup
DirectTerminal delegates xterm setup to useXtermTerminal, which dynamically imports xterm/addons, opens a mux terminal, sends input/resizes, and re-sends dimensions after reconnect packages/web/src/components/DirectTerminal.tsx:35-72 packages/web/src/components/terminal/useXtermTerminal.ts:80-115 packages/web/src/components/terminal/useXtermTerminal.ts:278-390.
HTTP refresh path
The session API routes remain the canonical refresh/snapshot path. The patch endpoint is intentionally lightweight and is polled by the mux broadcaster rather than every browser tab polling independently packages/web/src/app/api/sessions/route.ts:72-201 packages/web/server/mux-websocket.ts:170-198.
Prompt assembly and orchestrator prompt generation
Agent prompts are intentionally layered so AO can enforce operational behavior while still letting project configuration and repository rules shape local coding style.
flowchart LR Base["Layer 1: Base AO agent prompt\nmanaged session lifecycle + PR workflow"]:::base Config["Layer 2: Config-derived context\nproject name, repo, agent behavior, defaults"]:::config Rules["Layer 3: User rules\nagentRules + agentRulesFile"]:::rules Task["Task / issue prompt"]:::task Agent["Coding agent launch config"]:::agent Base --> Config --> Rules --> Task --> Agent OrchTemplate["orchestrator.md template"]:::base --> OrchData["project + dashboard + reactions + rules"]:::config --> OrchPrompt["Orchestrator session prompt"]:::agent classDef base fill:#172554,stroke:#60a5fa,color:#eff6ff; classDef config fill:#064e3b,stroke:#34d399,color:#ecfdf5; classDef rules fill:#78350f,stroke:#fbbf24,color:#fffbeb; classDef task fill:#312e81,stroke:#a78bfa,color:#f5f3ff; classDef agent fill:#4c1d95,stroke:#a78bfa,color:#faf5ff;
Agent prompt builder
prompt-builder.ts documents the three layers, defines the base agent prompt, gathers config-derived context, reads user rules from config/files, then builds the final prompt with optional orchestrator back-channel instructions and task content packages/core/src/prompt-builder.ts:1-11 packages/core/src/prompt-builder.ts:21-57 packages/core/src/prompt-builder.ts:111-182 packages/core/src/prompt-builder.ts:188-237.
Orchestrator prompt
orchestrator-prompt.ts renders the bundled orchestrator.md template with project path/name/repo/default branch, session prefix, dashboard port, reaction descriptions, and orchestrator rules packages/core/src/orchestrator-prompt.ts:1-8 packages/core/src/orchestrator-prompt.ts:33-68 packages/core/src/orchestrator-prompt.ts:144-199.
Why layers?
Base behavior protects AO invariants such as PR creation, status reporting, and lifecycle signals. Config and repo rules then adapt that behavior to a project without forking agent plugins or the session manager.
Cross-platform abstractions
AO treats macOS, Linux, and Windows as first-class. The project’s golden rule is to avoid ad-hoc process.platform === "win32" checks and centralize branching in helpers from @aoagents/ao-core docs/CROSS_PLATFORM.md:9-19.
Central helper module
platform.ts defines isWindows, isMac, isLinux, chooses default runtime (process on Windows, tmux elsewhere), resolves shells, kills process trees, finds PIDs by port, and normalizes env defaults packages/core/src/platform.ts:8-29 packages/core/src/platform.ts:44-62 packages/core/src/platform.ts:88-143 packages/core/src/platform.ts:154-245.
Deep compatibility guide
docs/CROSS_PLATFORM.md inventories helpers and calls out Windows gotchas such as PowerShell vs bash, PATH wrappers, process probing, localhost binding, and agent-plugin specifics docs/CROSS_PLATFORM.md:43-68 docs/CROSS_PLATFORM.md:172-181.
Why centralize OS branching?
Platform checks are otherwise hard to mock and easy to regress. A single helper layer lets tests simulate Windows/macOS/Linux behavior and keeps plugin/runtime code from silently drifting into POSIX-only assumptions.
Key files for future readers
If you are new to AO, read these files in order. The list is intentionally biased toward source of truth over high-level docs.
Orientation: CLAUDE.md:3-33 skills/agent-orchestrator/SKILL.md:7-27
Workspace/package shape: pnpm-workspace.yaml:1-3 package.json:7-27 packages/cli/package.json:35-61 packages/web/package.json:48-70
Core interfaces and plugins: packages/core/src/types.ts:3-18 packages/core/src/types.ts:1718-1753 packages/core/src/plugin-registry.ts:38-72 packages/core/src/plugin-registry.ts:420-623
Lifecycle: packages/core/src/lifecycle-state.ts:45-127 packages/core/src/lifecycle-state.ts:432-505 packages/core/src/lifecycle-manager.ts:900-1397 packages/core/src/lifecycle-manager.ts:2438-3043
Session orchestration: packages/core/src/session-manager.ts:1212-1598 packages/core/src/session-manager.ts:2235-2368 packages/core/src/session-manager.ts:2445-2801 packages/core/src/session-manager.ts:3271-3618
Storage/config: packages/core/src/metadata.ts:1-11 packages/core/src/paths.ts:112-145 packages/core/src/config.ts:247-381 packages/core/src/global-config.ts:75-99 packages/cli/src/lib/running-state.ts:16-29
CLI + web flow: packages/cli/src/commands/start.ts:900-1019 packages/cli/src/lib/project-supervisor.ts:118-240 packages/web/src/lib/services.ts:104-133 packages/web/server/mux-websocket.ts:77-198 packages/web/src/hooks/useSessionEvents.ts:148-340
Prompt/platform: packages/core/src/prompt-builder.ts:1-237 packages/core/src/orchestrator-prompt.ts:1-199 packages/core/src/platform.ts:8-245 docs/CROSS_PLATFORM.md:9-68