Skip to main content

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

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

# 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

# Initialize config interactively
ao init

# Auto-generate config
ao init --auto

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

​
Troubleshooting

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
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
Install tmux for the default runtime:
# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Fedora/RHEL
sudo dnf install tmux
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

Build docs developers (and LLMs) love

Get started for freeTalk to us