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)
• Git 2.25+ installed
• tmux installed (for default runtime)
• GitHub CLI (gh) installed and authenticated

Quick check: Run node --version, git --version, tmux -V, and gh auth status to verify.

Installation

1. Clone and setup

   Clone the repository and run the setup script:

   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

   If ao is not in your PATH after setup, add npm’s global bin directory to your shell profile:

   export PATH="$(npm config get prefix)/bin:$PATH"
   

   Then restart your terminal or run source ~/.zshrc (or ~/.bashrc).

2. Verify installation

   Confirm the CLI is available:

   ao --version
   

   You should see the version number printed.

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:

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

Supports GitHub, GitLab, and Bitbucket URLs (HTTPS and SSH format).

Option B: Initialize from an Existing Local Repo

If you already have a repository checked out locally:

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:

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:

ao start

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

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.

Spawn Your First Agent

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

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.

1. Workspace Creation

   The orchestrator creates an isolated git worktree with a feature branch.

2. Runtime Launch

   A tmux session starts (visible in tmux ls).

3. Agent Spawn

   The AI agent (Claude Code by default) launches with issue context loaded.

4. Autonomous Work

   The agent begins working: reading code, writing changes, running tests.

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:

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:

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:

GitHub Issues

# 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

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

Reactions are configured in agent-orchestrator.yaml. See the Configuration Reference for details.

Common Commands

Spawning and Managing Sessions

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

Monitoring and Interaction

# 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

Configuration

# Initialize config interactively
ao init

# Auto-generate config
ao init --auto

# Auto-generate with AI-powered rules (coming soon)
ao init --auto --smart

Troubleshooting

'ao' command not found

The CLI is not in your PATH. Add npm’s global bin to your shell profile:

export PATH="$(npm config get prefix)/bin:$PATH"
source ~/.zshrc  # or ~/.bashrc

Port 3000 already in use

Another service is using port 3000. Either:

1. Change the port in agent-orchestrator.yaml:

   port: 3001
   

2. Or kill the process using port 3000:

   lsof -ti:3000 | xargs kill
   

tmux not found

Install tmux for the default runtime:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Fedora/RHEL
sudo dnf install tmux

GitHub CLI not authenticated

Authenticate with GitHub:

gh auth login

Follow the prompts to authenticate via browser.

Next Steps

Now that you have Agent Orchestrator running:

Configuration

Customize reactions, plugins, and notification routing

Installation

Detailed installation guide and prerequisites

CLI Reference

Complete list of all ao commands

Plugin Development

Build custom plugins for runtimes, agents, and trackers