> ## 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. # 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 ```bash theme={null} ao spawn [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 ```bash theme={null} # 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 ```bash theme={null} $ 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: ```bash theme={null} SESSION=$(ao spawn my-project INT-1234 | grep SESSION= | cut -d= -f2) echo "Created session: $SESSION" ``` ### Session Naming Session IDs follow the pattern: ```bash theme={null} - ``` 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: ```bash theme={null} 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 ```bash theme={null} ao batch-spawn [options] ``` ### Arguments Project ID from configuration Space-separated list of issue identifiers ### Options Open all sessions in terminal tabs ### Basic Usage ```bash theme={null} # 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 ```bash theme={null} $ 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: ```bash theme={null} 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: ```bash theme={null} # 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 ```bash theme={null} Unknown project: my-project Available: project-a, project-b ``` **Solution**: Use a valid project ID from your config: ```bash theme={null} ao spawn project-a INT-1234 ``` ### tmux Not Found ```bash theme={null} Error: tmux not found. Install it first: brew install tmux ``` **Solution**: Install tmux: ```bash theme={null} # macOS brew install tmux # Ubuntu/Debian sudo apt-get install tmux ``` ### GitHub CLI Not Authenticated ```bash theme={null} Error: GitHub CLI not authenticated. Run: gh auth login ``` **Solution**: Authenticate GitHub CLI: ```bash theme={null} gh auth login ``` ### Issue Not Found ```bash theme={null} ✗ Failed to create session Error: Issue INT-9999 not found in tracker ``` **Solution**: Verify the issue exists in GitHub or Linear: ```bash theme={null} # Check GitHub gh issue view 9999 # Check Linear # Verify at linear.app ``` ### Worktree Already Exists ```bash theme={null} Error: Worktree already exists at ~/.worktrees/my-project-int-1234 ``` **Solution**: Remove the old worktree: ```bash theme={null} git worktree remove ~/.worktrees/my-project-int-1234 ``` ## Examples ### Basic Spawn ```bash theme={null} # 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 ```bash theme={null} # Spawn and open in iTerm2 tab ao spawn my-project INT-1234 --open ``` ### Custom Agent ```bash theme={null} # Use Codex for this session ao spawn my-project INT-1234 --agent codex ``` ### Batch Workflow ```bash theme={null} # 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 ```bash theme={null} #!/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 Monitor your spawned sessions Interact with running sessions List, kill, and cleanup sessions This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.