ao spawn

Create new agent sessions for issues with automatic workspace setup

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 <project> [issue] [options]

Arguments

project · string · required

Project ID from your configuration

issue · string

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

Open the session in a new terminal tab automatically

--agent · string

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

1. Pre-flight Checks

   • Validates project exists
   • Checks tmux is available (if using tmux runtime)
   • Verifies GitHub CLI authentication (if using GitHub tracker)

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

3. Issue Fetch (if issue provided)

   • Fetches issue details from tracker
   • Extracts title and description
   • Passes context to agent

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

5. 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:

int-1234-fix-type-errors

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 <project> <issues...> [options]

Arguments

project · string · required

Project ID from configuration

issues · string[] · required

Space-separated list of issue identifiers

Options

--open · flag

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:

1. Existing Sessions - Skips if a session already exists for the issue
2. Same Batch - Skips duplicate issues within the same command
3. Case-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:

gh auth login

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 successfully
• 1 - 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