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

# Quickstart

> Get Agent Orchestrator up and running in 5 minutes

# Quickstart Guide

This guide will get you from zero to your first running agent in under 5 minutes.

## Prerequisites

Before you begin, ensure you have:

* **Node.js 20+** installed ([nodejs.org](https://nodejs.org))
* **Git 2.25+** installed
* **tmux** installed (for default runtime)
* **GitHub CLI (`gh`)** installed and authenticated

<Info>
  Quick check: Run `node --version`, `git --version`, `tmux -V`, and `gh auth status` to verify.
</Info>

## Installation

<Steps>
  <Step title="Clone and setup">
    Clone the repository and run the setup script:

    ```bash theme={null}
    git clone https://github.com/ComposioHQ/agent-orchestrator.git
    cd agent-orchestrator
    bash scripts/setup.sh
    ```

    The setup script will:

    * Validate prerequisites (Node.js 20+, Git 2.25+)
    * Optionally install tmux if using Homebrew
    * Optionally authenticate GitHub CLI
    * Install pnpm (via corepack or npm)
    * Install dependencies and build all packages
    * Link the `ao` CLI globally

    <Warning>
      If `ao` is not in your PATH after setup, add npm's global bin directory to your shell profile:

      ```bash theme={null}
      export PATH="$(npm config get prefix)/bin:$PATH"
      ```

      Then restart your terminal or run `source ~/.zshrc` (or `~/.bashrc`).
    </Warning>
  </Step>

  <Step title="Verify installation">
    Confirm the CLI is available:

    ```bash theme={null}
    ao --version
    ```

    You should see the version number printed.
  </Step>
</Steps>

## Two Ways to Start

### Option A: Start from a Repository URL (Fastest)

The quickest way to get started—provide a GitHub URL and the orchestrator auto-configures everything:

```bash theme={null}
ao start https://github.com/your-org/your-repo
```

This single command will:

1. Clone the repository (or reuse an existing clone)
2. Auto-detect language, package manager, SCM platform, and default branch
3. Generate `agent-orchestrator.yaml` with smart defaults
4. Start the dashboard and orchestrator

<Info>
  Supports GitHub, GitLab, and Bitbucket URLs (HTTPS and SSH format).
</Info>

### Option B: Initialize from an Existing Local Repo

If you already have a repository checked out locally:

```bash theme={null}
cd ~/your-project
ao init --auto
```

The `--auto` flag generates configuration with smart defaults based on your repository. For interactive configuration (step-by-step prompts), omit the `--auto` flag:

```bash theme={null}
ao init
```

The interactive wizard will prompt you for:

* Data directory (default: `~/.agent-orchestrator`)
* Worktree directory (default: `~/.worktrees`)
* Dashboard port (default: `3000`)
* Runtime plugin (default: `tmux`)
* Agent plugin (default: `claude-code`)
* Project details (repo, path, default branch)
* Issue tracker (GitHub or Linear)

## Start the Orchestrator

Once you have a configuration file (`agent-orchestrator.yaml`), start the orchestrator and dashboard:

```bash theme={null}
ao start
```

The dashboard will open at `http://localhost:3000` (or your configured port).

<Note>
  The `ao start` command runs both the Next.js dashboard server and the orchestrator agent. Keep this terminal running, or use a process manager like PM2 for production.
</Note>

## Spawn Your First Agent

Now that the orchestrator is running, spawn an agent session to work on an issue:

```bash theme={null}
ao spawn my-project 123
```

Replace `my-project` with your project ID (from `agent-orchestrator.yaml`) and `123` with a GitHub issue number or Linear ticket ID.

<Steps>
  <Step title="Workspace Creation">
    The orchestrator creates an isolated git worktree with a feature branch.
  </Step>

  <Step title="Runtime Launch">
    A tmux session starts (visible in `tmux ls`).
  </Step>

  <Step title="Agent Spawn">
    The AI agent (Claude Code by default) launches with issue context loaded.
  </Step>

  <Step title="Autonomous Work">
    The agent begins working: reading code, writing changes, running tests.
  </Step>
</Steps>

## Monitor Progress

You can monitor agent progress in three ways:

### 1. Web Dashboard

Open your browser to `http://localhost:3000` to see:

* All active sessions
* Status and activity indicators
* Branch and PR links
* Real-time event logs

### 2. CLI Status

Run the status command for a terminal-based view:

```bash theme={null}
ao status
```

This displays all sessions with their current state:

```
SESSION         STATUS      BRANCH              PR    ACTIVITY
my-project-1    working     feat/add-feature    -     active
my-project-2    pr_open     fix/bug-123         #45   ready
```

### 3. Attach to Session

To watch an agent work in real-time, attach directly to its tmux session:

```bash theme={null}
ao open my-project-1
```

This opens the agent's terminal. Press `Ctrl+B` then `D` to detach without stopping the agent.

## Example Workflow

Here's a complete example from start to finish:

<CodeGroup>
  ```bash GitHub Issues theme={null}
  # Start orchestrator
  ao start

  # Spawn agent for GitHub issue #42
  ao spawn my-app 42

  # Monitor status
  ao status

  # View dashboard
  open http://localhost:3000

  # Send a message to the agent
  ao send my-app-1 "Don't forget to add tests"

  # Attach to watch progress
  ao open my-app-1
  ```

  ```bash Linear Tickets theme={null}
  # Start orchestrator
  ao start

  # Spawn agent for Linear ticket ABC-123
  ao spawn my-app ABC-123

  # Check all active sessions
  ao session ls

  # Kill a session if needed
  ao session kill my-app-1
  ```
</CodeGroup>

## What Happens Next?

Once the agent is working:

1. **Agent works autonomously**: Reads code, makes changes, writes tests
2. **Commits and pushes**: Creates commits and pushes to a feature branch
3. **Opens PR**: Creates a pull request with the changes
4. **Handles CI failures**: If CI fails, the agent receives logs and attempts fixes (if `ci-failed` reaction is enabled)
5. **Addresses review comments**: When reviewers request changes, the agent responds (if `changes-requested` reaction is enabled)
6. **Notifies you**: You get a desktop notification when the PR is ready to merge or needs human judgment

<Info>
  Reactions are configured in `agent-orchestrator.yaml`. See the [Configuration Reference](/configuration/overview) for details.
</Info>

## Common Commands

<Accordion title="Spawning and Managing Sessions">
  ```bash theme={null}
  # Spawn agent for a specific issue
  ao spawn <project> <issue>

  # Spawn with custom prompt
  ao spawn <project> --prompt "Refactor the auth module"

  # List all sessions
  ao session ls

  # Kill a session
  ao session kill <session-id>

  # Restore a crashed session
  ao session restore <session-id>
  ```
</Accordion>

<Accordion title="Monitoring and Interaction">
  ```bash theme={null}
  # View status of all sessions
  ao status

  # Send message to agent
  ao send <session-id> "Add unit tests"

  # Open agent terminal
  ao open <session-id>

  # Open dashboard
  ao dashboard
  ```
</Accordion>

<Accordion title="Configuration">
  ```bash theme={null}
  # Initialize config interactively
  ao init

  # Auto-generate config
  ao init --auto

  # Auto-generate with AI-powered rules (coming soon)
  ao init --auto --smart
  ```
</Accordion>

## Troubleshooting

<AccordionGroup>
  <Accordion title="'ao' command not found">
    The CLI is not in your PATH. Add npm's global bin to your shell profile:

    ```bash theme={null}
    export PATH="$(npm config get prefix)/bin:$PATH"
    source ~/.zshrc  # or ~/.bashrc
    ```
  </Accordion>

  <Accordion title="Port 3000 already in use">
    Another service is using port 3000. Either:

    1. Change the port in `agent-orchestrator.yaml`:
       ```yaml theme={null}
       port: 3001
       ```

    2. Or kill the process using port 3000:
       ```bash theme={null}
       lsof -ti:3000 | xargs kill
       ```
  </Accordion>

  <Accordion title="tmux not found">
    Install tmux for the default runtime:

    ```bash theme={null}
    # macOS
    brew install tmux

    # Ubuntu/Debian
    sudo apt install tmux

    # Fedora/RHEL
    sudo dnf install tmux
    ```
  </Accordion>

  <Accordion title="GitHub CLI not authenticated">
    Authenticate with GitHub:

    ```bash theme={null}
    gh auth login
    ```

    Follow the prompts to authenticate via browser.
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you have Agent Orchestrator running:

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Customize reactions, plugins, and notification routing
  </Card>

  <Card title="Installation" icon="download" href="/installation">
    Detailed installation guide and prerequisites
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Complete list of all `ao` commands
  </Card>

  <Card title="Plugin Development" icon="puzzle-piece" href="/plugins/overview">
    Build custom plugins for runtimes, agents, and trackers
  </Card>
</CardGroup>


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