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 Options -o, --output
string
default: "agent-orchestrator.yaml"
Output file path for the configuration
Auto-generate config with sensible defaults (no prompts)
Analyze project and generate custom rules (requires --auto)
Interactive Mode Default behavior — prompts for all configuration values:
The wizard will:
Detect Environment - Check for Git repository, tmux, GitHub CLIBasic Configuration - Set data directory, worktree directory, dashboard portDefault Plugins - Choose runtime, agent, workspace, and notifiersFirst Project - Configure your initial projectIssue Tracker - Set up GitHub or Linear integrationValidation - 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:
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:
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: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 successfully1 - Error (file exists, invalid input, missing prerequisites)
Next Steps
Start Orchestrator Launch the orchestrator and dashboard
Configuration Learn about all configuration options
