The spawn command creates new agent sessions with isolated workspaces, issue tracking integration, and automatic branch creation.
ao spawn Spawn a single agent session.
Syntax ao spawn < projec t > [issue] [options]
Arguments Project ID from your configuration
Issue identifier (e.g., INT-1234, #42) — must exist in your tracker
The issue must exist in your configured issue tracker (GitHub or Linear) before spawning.
Options Open the session in a new terminal tab automatically
Override the agent plugin (e.g., codex, claude-code, aider)
Basic Usage # Spawn session for an issue ao spawn my-project INT-1234 # Spawn session and open terminal ao spawn my-project INT-1234 --open # Spawn with custom agent ao spawn my-project INT-1234 --agent codex # Spawn without issue (exploratory session) ao spawn my-project
What Happens During Spawn
Pre-flight Checks
Validates project exists
Checks tmux is available (if using tmux runtime)
Verifies GitHub CLI authentication (if using GitHub tracker)
Workspace Setup
Creates git worktree (or clones repo, depending on workspace plugin)
Checks out new branch (e.g., int-1234-issue-title)
Isolates work from other sessions
Issue Fetch (if issue provided)
Fetches issue details from tracker
Extracts title and description
Passes context to agent
Agent Launch
Starts agent in tmux session (or process, depending on runtime)
Provides system prompt with orchestrator context
Gives agent the issue details and project rules
Session Registration
Creates session metadata file
Tracks session ID, project, issue, branch, and workspace path
Makes session visible in ao status and dashboard
Output Example $ ao spawn my-project INT-1234 --open ✓ Session ma-int-1234 created Worktree: ~/.worktrees/my-project-int-1234 Branch: int-1234-fix-type-errors Attach: tmux attach -t ma-int-1234 SESSION = ma-int-1234
The last line (SESSION=ma-int-1234) is for scripting — you can capture it:
SESSION = $( ao spawn my-project INT-1234 | grep SESSION= | cut -d= -f2 ) echo "Created session: $SESSION "
Session Naming Session IDs follow the pattern:
< sessionPrefix > - < issue-number >
For example:
Project sessionPrefix: ma
Issue: INT-1234
Session ID: ma-int-1234
The session prefix is defined in your project configuration. It keeps session names short and predictable.
Branch Naming Branches are automatically created using the issue title:
The CLI:
Converts issue title to lowercase kebab-case
Prepends the issue number
Ensures branch name is Git-safe
ao batch-spawn Spawn sessions for multiple issues with duplicate detection.
Syntax ao batch-spawn < projec t > < issues.. . > [options]
Arguments Project ID from configuration
Space-separated list of issue identifiers
Options Open all sessions in terminal tabs
Basic Usage # Spawn sessions for multiple issues ao batch-spawn my-project INT-1234 INT-1235 INT-1236 # Spawn and open all in terminal ao batch-spawn my-project INT-1234 INT-1235 --open
Duplicate Detection The command prevents creating duplicate sessions:
Existing Sessions - Skips if a session already exists for the issueSame Batch - Skips duplicate issues within the same commandCase-Insensitive - Treats INT-1234 and int-1234 as duplicates
Dead sessions (killed, done, exited) are ignored — you can respawn for those issues.
Output Example $ ao batch-spawn my-project INT-1234 INT-1235 INT-1234 INT-1236 ╔════════════════════════════════════════╗ ║ BATCH SESSION SPAWNER ║ ╚════════════════════════════════════════╝ Project: my-project Issues: INT-1234, INT-1235, INT-1234, INT-1236 ✓ Session ma-int-1234 created Worktree: ~/.worktrees/my-project-int-1234 Branch: int-1234-fix-type-errors Attach: tmux attach -t ma-int-1234 SESSION = ma-int-1234 ✓ Session ma-int-1235 created Worktree: ~/.worktrees/my-project-int-1235 Branch: int-1235-add-validation Attach: tmux attach -t ma-int-1235 SESSION = ma-int-1235 Skip INT-1234 — duplicate in this batch ✓ Session ma-int-1236 created Worktree: ~/.worktrees/my-project-int-1236 Branch: int-1236-refactor-api Attach: tmux attach -t ma-int-1236 SESSION = ma-int-1236 Summary: Created: 3 sessions Skipped: 1 (duplicate) Failed: 0 Created sessions: ma-int-1234 - > INT-1234 ma-int-1235 - > INT-1235 ma-int-1236 - > INT-1236 Skipped (duplicate): INT-1234 - > (this batch )
Error Handling If some spawns fail, the command continues and reports errors at the end:
Summary: Created: 2 sessions Skipped: 0 (duplicate) Failed: 1 2 failed: - INT-9999: Issue not found in tracker
Agent Override Use a different agent for a specific session:
# Use Codex instead of default claude-code ao spawn my-project INT-1234 --agent codex # Use Aider ao spawn my-project INT-1234 --agent aider
The agent must be installed and available in your PATH. The orchestrator only handles session creation and routing.
Common Issues Unknown Project Unknown project: my-project Available: project-a, project-b
Solution : Use a valid project ID from your config:ao spawn project-a INT-1234
tmux Not Found Error: tmux not found. Install it first: brew install tmux
Solution : Install tmux:# macOS brew install tmux # Ubuntu/Debian sudo apt-get install tmux
GitHub CLI Not Authenticated Error: GitHub CLI not authenticated. Run: gh auth login
Solution : Authenticate GitHub CLI:Issue Not Found ✗ Failed to create session Error: Issue INT-9999 not found in tracker
Solution : Verify the issue exists in GitHub or Linear:# Check GitHub gh issue view 9999 # Check Linear # Verify at linear.app
Worktree Already Exists Error: Worktree already exists at ~/.worktrees/my-project-int-1234
Solution : Remove the old worktree:git worktree remove ~/.worktrees/my-project-int-1234
Examples Basic Spawn # Spawn session for a GitHub issue ao spawn my-project 123 # Spawn for a Linear issue ao spawn my-project INT-1234
Open in Terminal # Spawn and open in iTerm2 tab ao spawn my-project INT-1234 --open
Custom Agent # Use Codex for this session ao spawn my-project INT-1234 --agent codex
Batch Workflow # Get issues from Linear/GitHub ISSUES = "INT-1234 INT-1235 INT-1236" # Spawn sessions for all ao batch-spawn my-project $ISSUES # Check status ao status
Scripted Spawn #!/bin/bash # spawn-issues.sh PROJECT = "my-project" ISSUES = $( gh issue list --json number --jq '.[].number' ) for issue in $ISSUES ; do SESSION = $( ao spawn $PROJECT $issue | grep SESSION= | cut -d= -f2 ) echo "Created: $SESSION " done
Exit Codes
0 - Session created successfully1 - Error (project not found, tmux missing, issue not found)
Next Steps
Status Monitor your spawned sessions
Send Messages Interact with running sessions
Session Management List, kill, and cleanup sessions
