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:

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

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

Spawning with Issue IDs

GitHub Issues

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

projects:
  my-app:
    tracker:
      plugin: linear
      teamId: "your-team-id"

Then spawn:

ao spawn my-app INT-1234

Ad-hoc Tasks (No Issue)

Spawn without an issue ID for exploratory work:

ao spawn my-app

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

ao send my-app-1 "Refactor the authentication module to use async/await"

Batch Spawning

Spawn multiple agents in parallel with duplicate detection:

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

Example: Batch spawn 5 issues

ao batch-spawn frontend #101 #102 #103 #104 #105

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:

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

Claude Code

ao spawn my-app 123 --agent claude-code

Uses Claude’s native coding mode. Best for complex reasoning and multi-file changes.

Codex

ao spawn my-app 123 --agent codex

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

projects:
  my-app:
    agent: codex
    agentConfig:
      model: gpt-4

Aider

ao spawn my-app 123 --agent aider

Uses Aider for structured code edits. Good for focused refactors.

Custom Prompts

Using Ad-hoc Sessions

For work without a tracked issue:

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

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:

projects:
  my-app:
    agentRulesFile: .agent-rules.md

Example .agent-rules.md:

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

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:

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:

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:

1. Runtime availability

   If using tmux runtime, checks that tmux is installed:

   tmux -V
   
2. Tracker authentication

   For GitHub tracker, validates gh CLI authentication:

   gh auth status
   
3. Project configuration

   Ensures the project exists in agent-orchestrator.yaml:

   projects:
     my-app:
       repo: owner/my-app
       path: ~/my-app
       defaultBranch: main
   

Common errors:

“tmux not found”

Install tmux:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

“gh auth failed”

Authenticate the GitHub CLI:

gh auth login

Advanced: Session Prefixes

Control session naming with prefixes:

projects:
  frontend:
    sessionPrefix: fe
  backend:
    sessionPrefix: api
  mobile:
    sessionPrefix: mob

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

This helps when managing multiple projects:

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

Managing Sessions

List, attach, send messages, and kill sessions

Auto-Reactions

Configure automatic CI failure and review handling