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

# Plugins

> Understanding the plugin system and how to use different plugin implementations

Agent Orchestrator's flexibility comes from its **plugin architecture**. Every major component — from where sessions run to how notifications are delivered — is swappable via plugins.

## Plugin System Overview

A **plugin** is a TypeScript module that implements one of the 8 plugin interfaces defined in `packages/core/src/types.ts`. Each plugin:

* Exports a `manifest` object describing itself
* Exports a `create()` function that returns the plugin implementation
* Uses `satisfies PluginModule<T>` for compile-time type safety

### Plugin Structure

Every plugin follows this pattern:

```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) { /* ... */ },
    async destroy(handle) { /* ... */ },
    async sendMessage(handle, message) { /* ... */ },
    async getOutput(handle, lines) { /* ... */ },
    async isAlive(handle) { /* ... */ },
  };
}

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

<Note>
  The `satisfies PluginModule<T>` syntax ensures compile-time checking that your plugin correctly implements all required interface methods.
</Note>

## The 8 Plugin Slots

### 1. Runtime Plugin

**Slot:** `runtime`\
**Interface:** `Runtime`\
**Purpose:** Determines WHERE and HOW agent sessions execute

**Available Plugins:**

<Tabs>
  <Tab title="tmux (default)">
    **Local tmux sessions**

    Pros:

    * Native terminal access
    * Persist across disconnects
    * Easy to attach and monitor
    * Minimal overhead

    Cons:

    * Local machine only
    * Requires tmux installed

    **Configuration:**

    ```yaml theme={null}
    defaults:
      runtime: tmux
    ```
  </Tab>

  <Tab title="process">
    **Direct child processes**

    Pros:

    * No dependencies
    * Simplest implementation
    * Works everywhere

    Cons:

    * Dies if orchestrator stops
    * No persistence
    * Limited monitoring

    **Configuration:**

    ```yaml theme={null}
    defaults:
      runtime: process
    ```
  </Tab>

  <Tab title="docker">
    **Docker containers**

    Pros:

    * Complete isolation
    * Reproducible environments
    * Resource limits
    * Works on any Docker host

    Cons:

    * Requires Docker
    * Higher overhead
    * More complex setup

    **Configuration:**

    ```yaml theme={null}
    defaults:
      runtime: docker
    ```
  </Tab>

  <Tab title="k8s">
    **Kubernetes pods**

    Pros:

    * Cloud-scale orchestration
    * High availability
    * Resource management
    * Multi-node distribution

    Cons:

    * Requires K8s cluster
    * Most complex setup
    * Higher latency

    **Configuration:**

    ```yaml theme={null}
    defaults:
      runtime: k8s
    ```
  </Tab>
</Tabs>

**Interface Methods:**

```typescript theme={null}
interface Runtime {
  create(config: RuntimeCreateConfig): Promise<RuntimeHandle>;
  destroy(handle: RuntimeHandle): Promise<void>;
  sendMessage(handle: RuntimeHandle, message: string): Promise<void>;
  getOutput(handle: RuntimeHandle, lines?: number): Promise<string>;
  isAlive(handle: RuntimeHandle): Promise<boolean>;
  getMetrics?(handle: RuntimeHandle): Promise<RuntimeMetrics>;
  getAttachInfo?(handle: RuntimeHandle): Promise<AttachInfo>;
}
```

### 2. Agent Plugin

**Slot:** `agent`\
**Interface:** `Agent`\
**Purpose:** Adapter for specific AI coding tools

**Available Plugins:**

<Tabs>
  <Tab title="claude-code (default)">
    **Anthropic's Claude Code**

    Features:

    * Session resume support
    * JSONL-based activity detection
    * Auto-generated summaries
    * Cost tracking
    * Workspace hooks for metadata updates

    **Configuration:**

    ```yaml theme={null}
    defaults:
      agent: claude-code

    projects:
      my-app:
        agentConfig:
          permissions: skip  # or "default"
          model: claude-sonnet-4-20250514
    ```
  </Tab>

  <Tab title="codex">
    **OpenAI Codex**

    Features:

    * Fast iteration speed
    * Strong code completion
    * Multi-language support

    **Configuration:**

    ```yaml theme={null}
    defaults:
      agent: codex

    projects:
      my-app:
        agent: codex
        agentConfig:
          model: gpt-4
    ```
  </Tab>

  <Tab title="aider">
    **Aider AI pair programmer**

    Features:

    * Git-aware editing
    * Interactive mode
    * Multiple model support

    **Configuration:**

    ```yaml theme={null}
    defaults:
      agent: aider

    projects:
      my-app:
        agent: aider
        agentConfig:
          model: gpt-4-turbo
    ```
  </Tab>

  <Tab title="opencode">
    **OpenCode agent**

    Features:

    * Open source
    * Extensible
    * Multi-modal support

    **Configuration:**

    ```yaml theme={null}
    defaults:
      agent: opencode
    ```
  </Tab>
</Tabs>

**Interface Methods:**

```typescript theme={null}
interface Agent {
  readonly name: string;
  readonly processName: string;
  readonly promptDelivery?: "inline" | "post-launch";
  
  getLaunchCommand(config: AgentLaunchConfig): string;
  getEnvironment(config: AgentLaunchConfig): Record<string, string>;
  detectActivity(terminalOutput: string): ActivityState;
  getActivityState(session: Session, readyThresholdMs?: number): Promise<ActivityDetection | null>;
  isProcessRunning(handle: RuntimeHandle): Promise<boolean>;
  getSessionInfo(session: Session): Promise<AgentSessionInfo | null>;
  getRestoreCommand?(session: Session, project: ProjectConfig): Promise<string | null>;
  postLaunchSetup?(session: Session): Promise<void>;
  setupWorkspaceHooks?(workspacePath: string, config: WorkspaceHooksConfig): Promise<void>;
}
```

<Warning>
  **Critical for Dashboard:** The `setupWorkspaceHooks()` method configures agents to automatically update session metadata when they run git/gh commands. Without this, PRs created by agents never show up in the dashboard.
</Warning>

### 3. Workspace Plugin

**Slot:** `workspace`\
**Interface:** `Workspace`\
**Purpose:** Code isolation mechanism

**Available Plugins:**

<Tabs>
  <Tab title="worktree (default)">
    **Git worktrees**

    Pros:

    * Shares git history (fast)
    * Minimal disk usage
    * Instant branch switching
    * Multiple sessions see each other's commits

    Cons:

    * Requires Git 2.25+
    * All worktrees share hooks
    * Can't delete parent repo while worktrees exist

    **Configuration:**

    ```yaml theme={null}
    defaults:
      workspace: worktree

    projects:
      my-app:
        workspace: worktree
        symlinks:
          - node_modules
          - .env
        postCreate:
          - pnpm install
    ```
  </Tab>

  <Tab title="clone">
    **Full repository clones**

    Pros:

    * Complete isolation
    * Independent git state
    * No shared hooks
    * Works with any Git version

    Cons:

    * Higher disk usage
    * Slower to create
    * Must push/pull to share changes

    **Configuration:**

    ```yaml theme={null}
    defaults:
      workspace: clone

    projects:
      my-app:
        workspace: clone
        postCreate:
          - npm install
    ```
  </Tab>
</Tabs>

**Interface Methods:**

```typescript theme={null}
interface Workspace {
  create(config: WorkspaceCreateConfig): Promise<WorkspaceInfo>;
  destroy(workspacePath: string): Promise<void>;
  list(projectId: string): Promise<WorkspaceInfo[]>;
  postCreate?(info: WorkspaceInfo, project: ProjectConfig): Promise<void>;
  exists?(workspacePath: string): Promise<boolean>;
  restore?(config: WorkspaceCreateConfig, workspacePath: string): Promise<WorkspaceInfo>;
}
```

### 4. Tracker Plugin

**Slot:** `tracker`\
**Interface:** `Tracker`\
**Purpose:** Issue/task tracking integration

**Available Plugins:**

<Tabs>
  <Tab title="github (default)">
    **GitHub Issues**

    Features:

    * Fetch issue details
    * Generate branch names
    * Create prompts from issues
    * Check completion status
    * Extract labels

    **Configuration:**

    ```yaml theme={null}
    projects:
      my-app:
        repo: owner/my-app
        tracker:
          plugin: github
    ```

    **Usage:**

    ```bash theme={null}
    ao spawn my-app 42          # GitHub issue #42
    ao spawn my-app "#42"       # Also works
    ```
  </Tab>

  <Tab title="linear">
    **Linear issue tracker**

    Features:

    * Fetch Linear issues
    * Team-aware queries
    * Status tracking
    * Priority handling

    **Configuration:**

    ```yaml theme={null}
    projects:
      my-app:
        tracker:
          plugin: linear
          teamId: TEAM-ID
          apiKey: ${LINEAR_API_KEY}
    ```

    **Usage:**

    ```bash theme={null}
    ao spawn my-app INT-100     # Linear issue INT-100
    ```
  </Tab>
</Tabs>

**Interface Methods:**

```typescript theme={null}
interface Tracker {
  getIssue(identifier: string, project: ProjectConfig): Promise<Issue>;
  isCompleted(identifier: string, project: ProjectConfig): Promise<boolean>;
  issueUrl(identifier: string, project: ProjectConfig): string;
  issueLabel?(url: string, project: ProjectConfig): string;
  branchName(identifier: string, project: ProjectConfig): string;
  generatePrompt(identifier: string, project: ProjectConfig): Promise<string>;
  listIssues?(filters: IssueFilters, project: ProjectConfig): Promise<Issue[]>;
  updateIssue?(identifier: string, update: IssueUpdate, project: ProjectConfig): Promise<void>;
  createIssue?(input: CreateIssueInput, project: ProjectConfig): Promise<Issue>;
}
```

### 5. SCM Plugin

**Slot:** `scm`\
**Interface:** `SCM`\
**Purpose:** Source control + PR/CI/review management

**Available Plugins:**

<Tabs>
  <Tab title="github (default)">
    **GitHub**

    Features:

    * Auto-detect PRs by branch
    * Track PR state (open/merged/closed)
    * Monitor CI checks
    * Fetch code reviews
    * Get review comments
    * Check merge readiness
    * Merge PRs

    **Configuration:**

    ```yaml theme={null}
    projects:
      my-app:
        repo: owner/my-app
        scm:
          plugin: github
    ```

    **Automatic PR Detection:**
    The github-scm plugin automatically detects PRs created by agents, even if the agent doesn't write the PR URL to metadata.
  </Tab>
</Tabs>

**Interface Methods:**

```typescript theme={null}
interface SCM {
  detectPR(session: Session, project: ProjectConfig): Promise<PRInfo | null>;
  getPRState(pr: PRInfo): Promise<PRState>;
  getPRSummary?(pr: PRInfo): Promise<{state: PRState; title: string; additions: number; deletions: number}>;
  mergePR(pr: PRInfo, method?: MergeMethod): Promise<void>;
  closePR(pr: PRInfo): Promise<void>;
  getCIChecks(pr: PRInfo): Promise<CICheck[]>;
  getCISummary(pr: PRInfo): Promise<CIStatus>;
  getReviews(pr: PRInfo): Promise<Review[]>;
  getReviewDecision(pr: PRInfo): Promise<ReviewDecision>;
  getPendingComments(pr: PRInfo): Promise<ReviewComment[]>;
  getAutomatedComments(pr: PRInfo): Promise<AutomatedComment[]>;
  getMergeability(pr: PRInfo): Promise<MergeReadiness>;
}
```

### 6. Notifier Plugin

**Slot:** `notifier`\
**Interface:** `Notifier`\
**Purpose:** Push notifications to humans

<Note>
  **Primary Human Interface:** The Notifier is how the orchestrator communicates with you. The dashboard is for monitoring; notifications are for action.
</Note>

**Available Plugins:**

<Tabs>
  <Tab title="desktop (default)">
    **Native OS notifications**

    Features:

    * System notification center
    * Works on macOS/Linux/Windows
    * No external dependencies
    * Immediate delivery

    **Configuration:**

    ```yaml theme={null}
    notifiers:
      desktop:
        plugin: desktop

    notificationRouting:
      urgent: [desktop]
      action: [desktop]
      warning: [desktop]
      info: []
    ```
  </Tab>

  <Tab title="slack">
    **Slack messages**

    Features:

    * Team-visible notifications
    * Rich formatting
    * Actionable buttons
    * Thread support

    **Configuration:**

    ```yaml theme={null}
    notifiers:
      slack:
        plugin: slack
        token: ${SLACK_BOT_TOKEN}
        channel: "#agent-updates"

    notificationRouting:
      urgent: [desktop, slack]
      action: [slack]
      warning: [slack]
      info: []
    ```
  </Tab>

  <Tab title="webhook">
    **Custom HTTP webhooks**

    Features:

    * Send to any HTTP endpoint
    * Custom payloads
    * Integration with any service

    **Configuration:**

    ```yaml theme={null}
    notifiers:
      webhook:
        plugin: webhook
        url: https://your-service.com/webhook
        headers:
          Authorization: Bearer ${WEBHOOK_TOKEN}

    notificationRouting:
      urgent: [desktop, webhook]
      action: [webhook]
    ```
  </Tab>

  <Tab title="composio">
    **Composio platform**

    Features:

    * Integrated with Composio ecosystem
    * Multi-channel routing
    * Analytics and tracking

    **Configuration:**

    ```yaml theme={null}
    notifiers:
      composio:
        plugin: composio
        apiKey: ${COMPOSIO_API_KEY}
    ```
  </Tab>
</Tabs>

**Interface Methods:**

```typescript theme={null}
interface Notifier {
  notify(event: OrchestratorEvent): Promise<void>;
  notifyWithActions?(event: OrchestratorEvent, actions: NotifyAction[]): Promise<void>;
  post?(message: string, context?: NotifyContext): Promise<string | null>;
}
```

### 7. Terminal Plugin

**Slot:** `terminal`\
**Interface:** `Terminal`\
**Purpose:** Human interaction with running sessions

**Available Plugins:**

<Tabs>
  <Tab title="iterm2 (default)">
    **iTerm2 integration (macOS)**

    Features:

    * Open sessions in new tabs
    * Native terminal experience
    * Keyboard shortcuts
    * Split panes

    **Configuration:**

    ```yaml theme={null}
    defaults:
      terminal: iterm2
    ```

    **Usage:**

    ```bash theme={null}
    ao attach session-1         # Opens in iTerm2 tab
    ao open my-app              # Opens all sessions
    ```
  </Tab>

  <Tab title="web">
    **Browser-based terminal**

    Features:

    * Works anywhere
    * No native terminal required
    * Copy/paste friendly
    * Mobile-compatible

    **Configuration:**

    ```yaml theme={null}
    defaults:
      terminal: web

    terminalPort: 3001          # WebSocket port
    directTerminalPort: 3003    # Direct terminal port
    ```

    **Usage:**
    Open dashboard, click session to view terminal.
  </Tab>
</Tabs>

**Interface Methods:**

```typescript theme={null}
interface Terminal {
  openSession(session: Session): Promise<void>;
  openAll(sessions: Session[]): Promise<void>;
  isSessionOpen?(session: Session): Promise<boolean>;
}
```

### 8. Lifecycle Manager

**Not a plugin slot** — this is core functionality built into the orchestrator.

**Responsibilities:**

* Poll all sessions periodically (default: every 30 seconds)
* Detect state transitions (working → pr\_open → ci\_failed → etc.)
* Emit events on transitions
* Trigger automatic reactions
* Track reaction attempts and escalation
* Notify humans when auto-handling fails

**State Machine Logic:**

<Steps>
  ### Check Runtime

  Is the session's runtime environment alive?

  ### Check Agent Activity

  What is the agent currently doing? (active/ready/idle/waiting/exited)

  ### Detect PR

  If no PR in metadata, query SCM by branch name.

  ### Check PR State

  If PR exists: Is it open, merged, or closed?

  ### Check CI

  Are CI checks passing or failing?

  ### Check Reviews

  What's the review decision? (approved/changes\_requested/pending)

  ### Check Merge Readiness

  Is the PR mergeable? (approved + green CI + no conflicts)

  ### Determine Status

  Compute new session status from all checks.

  ### Emit Events

  If status changed, emit event and trigger reactions.
</Steps>

**Configuration:**

```yaml theme={null}
readyThresholdMs: 300000        # 5 minutes before ready → idle
```

## Plugin Configuration

### Global Defaults

Set defaults for all projects:

```yaml theme={null}
defaults:
  runtime: tmux
  agent: claude-code
  workspace: worktree
  notifiers: [desktop]
```

### Per-Project Overrides

Override defaults for specific projects:

```yaml theme={null}
projects:
  my-app:
    repo: owner/my-app
    path: ~/my-app
    defaultBranch: main
    
    # Override runtime
    runtime: docker
    
    # Override agent
    agent: codex
    
    # Override workspace
    workspace: clone
    
    # Agent-specific config
    agentConfig:
      permissions: skip
      model: gpt-4-turbo
```

### Per-Session Overrides

Specify agent at spawn time:

```bash theme={null}
ao spawn my-app 123 --agent aider
```

The agent name is persisted in metadata so the same agent is used throughout the session lifecycle (including restores).

## Plugin Discovery

Plugins are discovered in this order:

1. **Built-in plugins** — Shipped with Agent Orchestrator
2. **npm packages** — Installed via `pnpm install`
3. **Local paths** — Custom plugins in your project

### Using Custom Plugins

Create a plugin in your project:

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

export const manifest = {
  name: "my-runtime",
  slot: "runtime" as const,
  description: "My custom runtime",
  version: "1.0.0",
};

export function create(): Runtime {
  return {
    // Implement interface
  };
}

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

Register in config:

```yaml theme={null}
plugins:
  - path: ./plugins/my-runtime.ts

defaults:
  runtime: my-runtime
```

## Best Practices

### Choosing Plugins

* **Runtime:** Use `tmux` for local work, `docker` for isolation, `k8s` for scale
* **Agent:** Start with `claude-code`, try others for specific needs
* **Workspace:** Use `worktree` unless you need complete isolation
* **Tracker:** Match your existing issue tracker
* **Notifier:** Use `desktop` for personal work, `slack` for team visibility

### Plugin Configuration

* Set sensible defaults in global config
* Override per-project for special cases
* Use environment variables for secrets: `${SLACK_TOKEN}`
* Test plugin changes with a single session first

### Notification Routing

Route notifications by priority:

```yaml theme={null}
notificationRouting:
  urgent: [desktop, slack]      # Agent stuck/errored
  action: [desktop]             # Human decision needed
  warning: [slack]              # Auto-fixable issues
  info: []                      # Don't notify for FYI events
```

## Next Steps

<Card title="Architecture" icon="sitemap" href="/concepts/architecture">
  See how plugins interact in the overall architecture
</Card>

<Card title="Workflows" icon="workflow" href="/concepts/workflows">
  Learn how plugins work together in end-to-end workflows
</Card>

<Card title="Plugin Development" icon="code" href="/guides/plugin-development">
  Build your own custom plugins
</Card>


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