Skip to main content

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