ao init

Interactive setup wizard for creating agent-orchestrator.yaml configuration

The init command walks you through creating a configuration file for Agent Orchestrator. It detects your environment (Git repository, GitHub CLI, tmux) and generates a working configuration.

Syntax

ao init [options]

Options

-o, --output · string · default: "agent-orchestrator.yaml"

Output file path for the configuration

--auto · flag

Auto-generate config with sensible defaults (no prompts)

--smart · flag

Analyze project and generate custom rules (requires --auto)

Interactive Mode

Default behavior — prompts for all configuration values:

ao init

The wizard will:

1. Detect Environment - Check for Git repository, tmux, GitHub CLI
2. Basic Configuration - Set data directory, worktree directory, dashboard port
3. Default Plugins - Choose runtime, agent, workspace, and notifiers
4. First Project - Configure your initial project
5. Issue Tracker - Set up GitHub or Linear integration
6. Validation - Verify all prerequisites are met

Environment Detection

The wizard automatically detects:

• Git repository and remote URL
• Current and default branch
• tmux availability
• GitHub CLI installation and authentication
• Environment variables (LINEAR_API_KEY, SLACK_WEBHOOK_URL)

Example Interactive Session

$ ao init

  Agent Orchestrator — Setup Wizard

  Detecting environment...

  ✓ Git repository detected
    Remote: composio/agent-orchestrator
    Branch: main
  ✓ tmux available
  ✓ GitHub CLI authenticated

  Configuration

Data directory (session metadata) (~/.agent-orchestrator): 
Worktree directory (~/.worktrees): 
Dashboard port (3000): 

  Default Plugins

Runtime (tmux, process) (tmux): 
Agent (claude-code, codex, aider) (claude-code): 
Workspace (worktree, clone) (worktree): 
Notifiers (comma-separated: desktop, slack) (desktop): 

  First Project

Project ID (short name, e.g. my-app) (agent-orchestrator): 
GitHub repo (owner/repo) (composio/agent-orchestrator): 
Local path to repo (/Users/user/agent-orchestrator): 
Default branch (main): 

  Issue Tracker

Tracker (github, linear, none) (github): 

  Validating Setup...

  ✓ Git
  ✓ tmux
  ✓ GitHub CLI
  ✓ Repo path exists

✓ Config written to agent-orchestrator.yaml

Next steps:

  1. Review the config (optional):
     nano agent-orchestrator.yaml

  2. Start orchestrator + dashboard:
     ao start

  3. Spawn agent sessions:
     ao spawn agent-orchestrator ISSUE-123

Auto Mode

Generate configuration without prompts:

ao init --auto

Auto mode:

• Uses sensible defaults for all values
• Detects project type (languages, frameworks)
• Finds free port for dashboard
• Creates configuration immediately

Auto mode is useful for scripting or when you want to manually edit the config afterward.

Auto Mode Output

$ ao init --auto

  Agent Orchestrator — Auto Setup

  🚀 Auto-generating config with smart defaults...

  ✓ Git repository detected
    Remote: composio/agent-orchestrator
    Branch: main
  ✓ Project type detected
    Languages: TypeScript, JavaScript
    Frameworks: Next.js

✓ Config written to agent-orchestrator.yaml

Next steps:

  1. Review the config (optional):
     nano agent-orchestrator.yaml

  2. Start orchestrator + dashboard:
     ao start

  3. Spawn agent sessions:
     ao spawn agent-orchestrator ISSUE-123

Smart Mode

Analyze project and generate custom agent rules:

ao init --auto --smart

Smart mode requires --auto. It cannot be used with interactive mode.

Smart mode:

• Detects project type (TypeScript, React, Next.js, etc.)
• Generates project-specific agent rules
• Adds rules to the configuration

Generated Rules Example

projects:
  my-app:
    name: my-app
    sessionPrefix: ma
    repo: owner/my-app
    path: ~/my-app
    defaultBranch: main
    agentRules: |
      # TypeScript Project Rules
      - Always run `pnpm typecheck` before committing
      - Use strict TypeScript configuration
      - Follow existing import patterns
      
      # Next.js Rules
      - Use App Router conventions
      - Place client components in /components
      - Follow Next.js 15 best practices

Custom Output Path

Write configuration to a custom location:

ao init --output ~/projects/my-config.yaml

If the output file already exists, ao init will exit with an error. Delete the existing file first or specify a different path.

Port Selection

The wizard automatically finds a free port:

• Default port: 3000
• If busy, scans up to 10 ports (3000-3009)
• Prompts for manual entry if all are busy

⚠ Port 3000 is busy — suggesting 3001 instead.
  Press Enter to accept, or type a different port.

Dashboard port (3001): 

Validation

The wizard validates your setup:

  Validating Setup...

  ✓ Git
  ✓ tmux
  ✓ GitHub CLI
  ✓ Repo path exists

Missing prerequisites show as warnings but don’t prevent config creation. Install them before running ao start.

Common Issues

Config Already Exists

Config already exists: agent-orchestrator.yaml
Delete it first or specify a different path with --output.

Solution: Delete the existing file or use --output with a different path.

Invalid Port

Invalid port number. Must be 1-65535.

Solution: Enter a valid port number between 1 and 65535.

tmux Not Found

  ⚠ tmux not found
    Install with: brew install tmux

Solution: Install tmux before starting the orchestrator:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt-get install tmux

GitHub CLI Not Authenticated

  ⚠ GitHub CLI not authenticated
    Run: gh auth login

Solution: Authenticate GitHub CLI:

gh auth login

Examples

Basic Setup

# Interactive setup with prompts
ao init

Quick Setup

# Auto-generate config with defaults
ao init --auto

Project Analysis

# Auto-generate with smart rules
ao init --auto --smart

Custom Location

# Write to custom path
ao init --output ~/.config/ao.yaml

Exit Codes

• 0 - Config created successfully
• 1 - Error (file exists, invalid input, missing prerequisites)

Next Steps

Start Orchestrator

Launch the orchestrator and dashboard

Configuration

Learn about all configuration options