Skip to main content
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
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
ao spawn my-app 123 --agent claude-code
Uses Claude’s native coding mode. Best for complex reasoning and multi-file changes.

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us