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

# 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

```bash theme={null}
ao init [options]
```

## Options

<ParamField path="-o, --output" type="string" default="agent-orchestrator.yaml">
  Output file path for the configuration
</ParamField>

<ParamField path="--auto" type="flag">
  Auto-generate config with sensible defaults (no prompts)
</ParamField>

<ParamField path="--smart" type="flag">
  Analyze project and generate custom rules (requires `--auto`)
</ParamField>

## Interactive Mode

Default behavior — prompts for all configuration values:

```bash theme={null}
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

```bash theme={null}
$ 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:

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

Auto mode:

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

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

### Auto Mode Output

```bash theme={null}
$ 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:

```bash theme={null}
ao init --auto --smart
```

<Warning>
  Smart mode requires `--auto`. It cannot be used with interactive mode.
</Warning>

Smart mode:

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

### Generated Rules Example

```yaml theme={null}
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:

```bash theme={null}
ao init --output ~/projects/my-config.yaml
```

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

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

```bash theme={null}
⚠ 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:

```bash theme={null}
  Validating Setup...

  ✓ Git
  ✓ tmux
  ✓ GitHub CLI
  ✓ Repo path exists
```

<Warning>
  Missing prerequisites show as warnings but don't prevent config creation. Install them before running `ao start`.
</Warning>

## Common Issues

### Config Already Exists

```bash theme={null}
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

```bash theme={null}
Invalid port number. Must be 1-65535.
```

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

### tmux Not Found

```bash theme={null}
  ⚠ tmux not found
    Install with: brew install tmux
```

**Solution**: Install tmux before starting the orchestrator:

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

# Ubuntu/Debian
sudo apt-get install tmux
```

### GitHub CLI Not Authenticated

```bash theme={null}
  ⚠ GitHub CLI not authenticated
    Run: gh auth login
```

**Solution**: Authenticate GitHub CLI:

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

## Examples

### Basic Setup

```bash theme={null}
# Interactive setup with prompts
ao init
```

### Quick Setup

```bash theme={null}
# Auto-generate config with defaults
ao init --auto
```

### Project Analysis

```bash theme={null}
# Auto-generate with smart rules
ao init --auto --smart
```

### Custom Location

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Start Orchestrator" icon="play" href="/cli/start-stop">
    Launch the orchestrator and dashboard
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Learn about all configuration options
  </Card>
</CardGroup>


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