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

# Spawning Agents

> Learn how to spawn AI coding agents for issues, configure custom prompts, and select different agent types

Spawning agents is the core workflow in Agent Orchestrator. Each agent gets an isolated workspace, its own git branch, and autonomously works on code changes.

## Basic Spawning

Spawn a single agent for an issue:

```bash theme={null}
ao spawn my-project 123
```

This command:

1. Creates an isolated git worktree from your default branch
2. Creates a feature branch (e.g., `feat/123`)
3. Starts a tmux session for the agent
4. Launches the AI agent with issue context from your tracker
5. Writes session metadata for tracking

<Note>
  The issue identifier format depends on your tracker:

  * **GitHub**: `#123` or just `123`
  * **Linear**: `INT-1234` (team prefix + number)
  * **Ad-hoc**: Any string becomes the branch name
</Note>

## Spawning with Issue IDs

### GitHub Issues

```bash theme={null}
# With hash symbol
ao spawn my-app #42

# Without hash (also works)
ao spawn my-app 42
```

The agent fetches issue details via the GitHub CLI (`gh`) and uses the title and description as context.

### Linear Issues

Configure Linear in your project:

```yaml theme={null}
projects:
  my-app:
    tracker:
      plugin: linear
      teamId: "your-team-id"
```

Then spawn:

```bash theme={null}
ao spawn my-app INT-1234
```

### Ad-hoc Tasks (No Issue)

Spawn without an issue ID for exploratory work:

```bash theme={null}
ao spawn my-app
```

The agent starts with a generic prompt. Send it instructions:

```bash theme={null}
ao send my-app-1 "Refactor the authentication module to use async/await"
```

## Batch Spawning

Spawn multiple agents in parallel with duplicate detection:

```bash theme={null}
ao batch-spawn my-project 101 102 103 104 105
```

**Features:**

* **Duplicate detection**: Skips issues that already have active sessions
* **Same-batch deduplication**: Won't spawn duplicates within the batch
* **Parallel execution**: Creates sessions with 500ms delay between each
* **Summary report**: Shows created, skipped, and failed sessions

<CodeGroup>
  ```bash Example: Batch spawn 5 issues theme={null}
  ao batch-spawn frontend #101 #102 #103 #104 #105
  ```

  ```bash Example: Linear batch theme={null}
  ao batch-spawn backend INT-1 INT-2 INT-3
  ```
</CodeGroup>

**Output:**

```
BATCH SESSION SPAWNER

  Project: frontend
  Issues:  101, 102, 103, 104, 105

✓ Session fe-101 created
✓ Session fe-102 created
⊘ Skip 103 — already has session: fe-103
✓ Session fe-104 created
✗ 105 — Issue not found in tracker

Summary:
  Created: 3 sessions
  Skipped: 1 (duplicate)
  Failed:  1
```

## Agent Selection

Override the default agent per-session:

```bash theme={null}
ao spawn my-project 123 --agent codex
```

**Available agents:**

* `claude-code` (default) — Anthropic Claude with Code mode
* `codex` — OpenAI Codex
* `aider` — Aider coding assistant
* `opencode` — OpenCode agent

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    ao spawn my-app 123 --agent claude-code
    ```

    Uses Claude's native coding mode. Best for complex reasoning and multi-file changes.
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    ao spawn my-app 123 --agent codex
    ```

    Uses OpenAI's Codex. Configure model in project settings:

    ```yaml theme={null}
    projects:
      my-app:
        agent: codex
        agentConfig:
          model: gpt-4
    ```
  </Tab>

  <Tab title="Aider">
    ```bash theme={null}
    ao spawn my-app 123 --agent aider
    ```

    Uses Aider for structured code edits. Good for focused refactors.
  </Tab>
</Tabs>

## Custom Prompts

### Using Ad-hoc Sessions

For work without a tracked issue:

```bash theme={null}
# Spawn without issue
ao spawn my-app

# Send custom prompt
ao send my-app-1 "Add error handling to all API routes. Use try/catch and return proper HTTP status codes."
```

### Agent Rules (Per-Project)

Define rules that apply to all agents in a project:

```yaml theme={null}
projects:
  my-app:
    agentRules: |
      Always run tests before pushing.
      Use conventional commits (feat:, fix:, chore:).
      Link issue numbers in commit messages.
      Follow TypeScript strict mode.
```

Or reference an external file:

```yaml theme={null}
projects:
  my-app:
    agentRulesFile: .agent-rules.md
```

**Example `.agent-rules.md`:**

```markdown theme={null}
# Agent Rules for My App

## Code Style
- Use 2-space indentation
- Prefer `const` over `let`
- Always add JSDoc comments for exported functions

## Testing
- Write tests for new features
- Run `pnpm test` before pushing
- Aim for >80% coverage

## Commits
- Use conventional commits: `feat:`, `fix:`, `chore:`
- Reference issue numbers: `feat: add login (#123)`
```

## Opening Sessions in Terminal

Automatically open spawned sessions in terminal tabs:

```bash theme={null}
ao spawn my-project 123 --open
```

This uses the Terminal plugin (default: `iterm2`) to create a new tab and attach to the tmux session.

**Manual attachment:**

```bash theme={null}
tmux attach -t my-app-1
```

## Session Output

When a session is created, you'll see:

```
✓ Session my-app-1 created
  Worktree: /Users/you/.worktrees/my-app-1
  Branch:   feat/123
  Attach:   tmux attach -t my-app-1

SESSION=my-app-1
```

The `SESSION=` line is for scripting:

```bash theme={null}
SESSION=$(ao spawn my-app 123 | grep SESSION | cut -d= -f2)
ao send $SESSION "Start implementing the feature"
```

## Pre-flight Checks

Before spawning, the CLI validates:

<Steps>
  <Step title="Runtime availability">
    If using `tmux` runtime, checks that tmux is installed:

    ```bash theme={null}
    tmux -V
    ```
  </Step>

  <Step title="Tracker authentication">
    For GitHub tracker, validates `gh` CLI authentication:

    ```bash theme={null}
    gh auth status
    ```
  </Step>

  <Step title="Project configuration">
    Ensures the project exists in `agent-orchestrator.yaml`:

    ```yaml theme={null}
    projects:
      my-app:
        repo: owner/my-app
        path: ~/my-app
        defaultBranch: main
    ```
  </Step>
</Steps>

**Common errors:**

<Warning>
  **"tmux not found"**

  Install tmux:

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

  # Ubuntu/Debian
  sudo apt install tmux
  ```
</Warning>

<Warning>
  **"gh auth failed"**

  Authenticate the GitHub CLI:

  ```bash theme={null}
  gh auth login
  ```
</Warning>

## Advanced: Session Prefixes

Control session naming with prefixes:

```yaml theme={null}
projects:
  frontend:
    sessionPrefix: fe
  backend:
    sessionPrefix: api
  mobile:
    sessionPrefix: mob
```

Resulting sessions: `fe-1`, `api-1`, `mob-1`

This helps when managing multiple projects:

```bash theme={null}
ao session ls -p frontend  # Shows fe-1, fe-2, fe-3...
ao session ls -p backend   # Shows api-1, api-2, api-3...
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Managing Sessions" icon="terminal" href="/guides/managing-sessions">
    List, attach, send messages, and kill sessions
  </Card>

  <Card title="Auto-Reactions" icon="robot" href="/guides/auto-reactions">
    Configure automatic CI failure and review handling
  </Card>
</CardGroup>


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