> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Understanding the plugin-based architecture of Agent Orchestrator

Agent Orchestrator is built on a flexible plugin architecture with 8 distinct plugin slots. Every abstraction is swappable, allowing you to adapt the system to your specific needs.

## Core Principle

**Push, not pull.** Spawn agents, walk away, get notified when your judgment is needed.

The orchestrator operates as a stateless system with no database — using flat metadata files and JSONL event logs for persistence. This design ensures backwards compatibility and simplicity.

## The 8 Plugin Slots

Agent Orchestrator's architecture is defined by 8 plugin slots. Each slot represents a specific responsibility, and every plugin must implement the interface defined in `packages/core/src/types.ts`.

<Note>
  All plugin interfaces are defined in a single source of truth: [`packages/core/src/types.ts`](https://github.com/ComposioHQ/agent-orchestrator/blob/main/packages/core/src/types.ts)
</Note>

| Slot | Interface | Purpose | Default Plugin |
| - | - | - | - |
| **Runtime** | `Runtime` | Where sessions execute (environment) | tmux |
| **Agent** | `Agent` | AI coding tool adapter | claude-code |
| **Workspace** | `Workspace` | Code isolation mechanism | worktree |
| **Tracker** | `Tracker` | Issue/task tracking | github |
| **SCM** | `SCM` | Source control + PR/CI/reviews | github |
| **Notifier** | `Notifier` | Push notifications to humans | desktop |
| **Terminal** | `Terminal` | Human interaction UI | iterm2 |
| **Lifecycle** | (core) | State machine + reaction engine | (not pluggable) |

### Runtime Plugin

Determines **WHERE** and **HOW** agent sessions execute. Examples include:

* **tmux** (default) — Local terminal sessions
* **docker** — Containerized environments
* **process** — Direct child processes
* **k8s** — Kubernetes pods for cloud-scale orchestration

**Key responsibilities:**

* Create and destroy session environments
* Send messages to running agents
* Capture session output
* Check if sessions are alive
* Provide attachment info for Terminal plugin

### Agent Plugin

Adapter for specific AI coding tools. The plugin knows how to:

* Launch the agent with proper configuration
* Detect agent activity (active, ready, idle, blocked)
* Extract session information (summary, cost, session ID)
* Resume previous sessions
* Set up workspace hooks for automatic metadata updates

**Supported agents:**

* **claude-code** — Anthropic's Claude Code
* **codex** — OpenAI Codex
* **aider** — Aider AI pair programmer
* **opencode** — OpenCode agent

### Workspace Plugin

Manages code isolation — how each session gets its own copy of the repository.

* **worktree** (default) — Git worktrees for shared history
* **clone** — Full repository clones for complete isolation

**Features:**

* Create isolated workspaces per session
* Automatic branch management
* Post-creation hooks (symlinks, dependency installation)
* Workspace restoration for crashed sessions

### Tracker Plugin

Integrates with issue tracking systems to:

* Fetch issue details and descriptions
* Generate branch names from issue IDs
* Create prompts for agents based on issue context
* Check issue completion status
* Update issue state (optional)

**Supported trackers:**

* **github** — GitHub Issues
* **linear** — Linear issue tracker

### SCM Plugin

Manages the entire PR lifecycle:

* Detect PRs created by agents
* Track PR state (open, merged, closed)
* Monitor CI check results
* Fetch code reviews and review comments
* Determine merge readiness
* Execute merge operations

**Supported platforms:**

* **github** — GitHub pull requests

### Notifier Plugin

**The primary interface between orchestrator and human.** Delivers push notifications when:

* Agent needs input or gets stuck
* PR is approved and ready to merge
* CI failures can't be auto-fixed
* Review comments require human judgment

**Supported notifiers:**

* **desktop** — Native OS notifications
* **slack** — Slack messages
* **composio** — Composio platform integration
* **webhook** — Custom HTTP webhooks

### Terminal Plugin

Manages how humans view and interact with running sessions:

* Open sessions in IDE tabs
* Launch browser windows to web terminals
* Attach to tmux/docker sessions
* Open all sessions for a project at once

**Supported terminals:**

* **iterm2** — iTerm2 integration (macOS)
* **web** — Browser-based terminal

### Lifecycle Manager

**Not pluggable.** The core state machine that:

* Polls all sessions periodically
* Detects state transitions (working → pr\_open → ci\_failed → etc.)
* Emits events on transitions
* Triggers automatic reactions
* Escalates to human notification when auto-handling fails

## Component Interaction Flow

<Steps>
  ### Session Spawn

  When you run `ao spawn my-project 123`:

  1. **Tracker** fetches issue details and generates a prompt
  2. **Workspace** creates an isolated git worktree with feature branch
  3. **Agent** generates the launch command with issue context
  4. **Runtime** creates the execution environment (tmux session)
  5. **Agent** launches inside the runtime with the prompt
  6. Session metadata is written to `~/.agent-orchestrator/{hash}-{project}/sessions/{session-id}`

  ### Active Work

  While the agent works:

  1. **Agent** writes code, runs tests, commits changes
  2. **Lifecycle Manager** polls session status every N seconds
  3. **Agent plugin** detects activity state (active/ready/idle/blocked/exited)
  4. When agent creates PR, **SCM** detects it and updates session status
  5. Session transitions through states: `working` → `pr_open`

  ### Automatic Reactions

  When events occur:

  1. **SCM** detects CI failure on PR
  2. **Lifecycle Manager** emits `ci.failing` event
  3. **Reaction engine** checks configured reactions
  4. If `ci-failed.auto: true`, **Runtime** sends CI logs to agent via message
  5. Agent reads logs, fixes issue, pushes new commit
  6. If retries exhausted, **Notifier** escalates to human

  ### Human Notification

  When human judgment needed:

  1. **Lifecycle Manager** determines notification priority
  2. **Notifier** delivers push notification with context
  3. Human reviews PR, makes decision
  4. Human can send instructions: `ao send session-1 "Please add more tests"`
  5. **Runtime** delivers message to agent
</Steps>

## Event-Driven Architecture

The system is driven by **events** rather than continuous polling:

### Event Types

**Session Lifecycle:**

* `session.spawned` — New session created
* `session.working` — Agent is actively working
* `session.stuck` — Agent inactive for threshold period
* `session.needs_input` — Agent waiting for user response
* `session.killed` — Session terminated

**PR Lifecycle:**

* `pr.created` — Agent opened a pull request
* `pr.updated` — PR was updated with new commits
* `pr.merged` — PR was merged
* `pr.closed` — PR was closed without merging

**CI Events:**

* `ci.passing` — All CI checks passed
* `ci.failing` — One or more CI checks failed
* `ci.fix_sent` — Auto-fix sent to agent
* `ci.fix_failed` — Auto-fix attempts exhausted

**Review Events:**

* `review.pending` — PR awaiting review
* `review.approved` — PR approved by reviewer
* `review.changes_requested` — Reviewer requested changes
* `review.comments_sent` — Review comments forwarded to agent

**Merge Events:**

* `merge.ready` — PR approved with passing CI
* `merge.conflicts` — Merge conflicts detected
* `merge.completed` — PR successfully merged

### Event Priority Levels

Events are classified by priority for notification routing:

* **urgent** — Agent stuck, needs input, or errored (immediate attention)
* **action** — PR approved and ready, or merge completed (human decision needed)
* **warning** — CI failure, changes requested, merge conflicts (may auto-resolve)
* **info** — Progress updates, summaries (FYI only)

## Lifecycle State Machine

Sessions progress through defined states:

```
spawning → working → pr_open → ci_failed → working → pr_open
                           ↓
                    review_pending → changes_requested → working → pr_open
                           ↓
                       approved → mergeable → merged
```

**Terminal states** (session ended):

* `killed` — Session terminated
* `merged` — PR merged successfully
* `done` — Work completed
* `terminated` — Force-stopped
* `cleanup` — Being cleaned up
* `errored` — Fatal error occurred

**Intervention states** (needs human):

* `needs_input` — Agent waiting for response
* `stuck` — Agent inactive beyond threshold

## Directory Structure

The architecture enforces convention over configuration:

```
Repo (versioned):
~/path/to/agent-orchestrator/
  agent-orchestrator.yaml              # Config file (single source of truth)
  packages/
    core/                              # Type definitions, services
    cli/                               # Command-line interface
    web/                               # Next.js dashboard
    plugins/                           # All plugins

Runtime Data (not versioned):
~/.agent-orchestrator/                 # Single parent directory
  {hash}-{projectId}/                  # Hash from config location
    sessions/
      {session-id}                     # Flat key=value metadata
    worktrees/
      {session-id}/                    # Git worktrees
    archive/
      {session-id}_{timestamp}         # Archived sessions
    .origin                            # Config path reference
```

<Info>
  The hash is derived from the config file location, ensuring multiple orchestrator instances never collide.
</Info>

## Design Principles

### 1. Convention Over Configuration

All paths are auto-derived. No need to configure:

* Data directories
* Worktree locations
* Session namespaces

The config file location determines everything.

### 2. Single Source of Truth

* **Config:** `agent-orchestrator.yaml` in repo
* **Runtime data:** `~/.agent-orchestrator/` on disk
* **Plugin interfaces:** `packages/core/src/types.ts`

### 3. Zero Path Configuration

Paths are computed from:

* Config file location (for hash)
* Project path (from config)
* Session ID (auto-generated)

No manual path management needed.

### 4. Global Uniqueness

Hash-based namespacing prevents collisions:

* Multiple config checkouts don't conflict
* Projects from same config share hash prefix
* Tmux session names are globally unique

### 5. Stateless Orchestrator

No database required:

* Flat metadata files (`key=value` format)
* JSONL event log for history
* Plugins determine live state on demand

### 6. Plugin Interfaces

Every plugin is a pure implementation:

* Imports interface from `@composio/ao-core`
* Exports `PluginModule<T>` with `satisfies`
* No framework lock-in

### 7. Security First

* Always use `execFile`, never `exec` (prevent shell injection)
* Validate all external input (API, CLI, files)
* No interpolation of user input into shell commands
* Timeouts on all external commands

<Warning>
  **Security Critical:** All plugins must use `execFile` or `spawn` for shell commands. Never use `exec` or interpolate user input into command strings.
</Warning>

## Plugin Development Pattern

Every plugin follows this structure:

```typescript theme={null}
import type { PluginModule, Runtime } from "@composio/ao-core";

export const manifest = {
  name: "tmux",
  slot: "runtime" as const,
  description: "Runtime plugin: tmux sessions",
  version: "0.1.0",
};

export function create(): Runtime {
  return {
    name: "tmux",
    async create(config) {
      // Implement interface method
    },
    async destroy(handle) {
      // Implement interface method
    },
    // ... other interface methods
  };
}

export default { manifest, create } satisfies PluginModule<Runtime>;
```

<Note>
  Always use inline `satisfies PluginModule<T>` — this provides compile-time type checking and prevents interface mismatches.
</Note>

## Next Steps

<Card title="Sessions" icon="clock" href="/concepts/sessions">
  Learn about session lifecycle and state management
</Card>

<Card title="Plugins" icon="puzzle" href="/concepts/plugins">
  Explore the plugin system in detail
</Card>

<Card title="Workflows" icon="workflow" href="/concepts/workflows">
  See how typical workflows operate end-to-end
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.