--- name: spawn-session description: Spawn a new Claude Code tmux session as a subagent worker --- # Spawn Session Create a new Claude Code tmux session with `ai-*` prefix to act as a subagent worker. ## Arguments `$ARGUMENTS` format: `[type] [name-suffix] [-- initial prompt]` - `type` - Session type: `worker` (default), `brainstorm`, `auditor` - `name-suffix` - Optional custom suffix (auto-generated if omitted) - `-- initial prompt` - Optional prompt to send after session starts Examples: - `\/session-tools:spawn-session` → `ai-worker-001` - `\/session-tools:spawn-session worker api` → `ai-worker-api` - `\/session-tools:spawn-session brainstorm design` → `ai-brainstorm-design` - `\/session-tools:spawn-session worker task1 -- Implement the login feature` → spawns and sends prompt ## Instructions 1. **Parse arguments:** ``` type = "worker" (default) suffix = auto-generated or provided prompt = text after "--" if present ``` 2. **Generate session name:** If no suffix provided, find next available number: ```bash "$PLUGIN_DIR\/bin\/next-session-name" "" ``` Returns: `ai--` (e.g., `ai-worker-003`) If suffix provided: `ai--` 3. **Validate session doesn't exist:** ```bash tmux has-session -t "" 2>\/dev\/null && echo "exists" ``` If exists, error: ``` Session '' already exists. Choose a different name. ``` 4. **Get working directory:** Use current working directory for the new session: ```bash pwd ``` 5. **Spawn the session:** ```bash "$PLUGIN_DIR\/bin\/spawn-session" "" "" [""] ``` The script: - Creates tmux session in detached mode - Starts `claude` in the session - Optionally sends initial prompt 6. **Verify session started:** ```bash sleep 2 "$PLUGIN_DIR\/bin\/detect-state" "" ``` 7. **Output result:** ``` Spawned session: Working directory: Status: To monitor: \/session-tools:summarize-session To attach: tmux attach -t ``` ## Session Types | Type | Prefix | Purpose | |------|--------|---------| | `worker` | `ai-worker-*` | Task execution | | `brainstorm` | `ai-brainstorm-*` | Ideation and exploration | | `auditor` | `ai-auditor-*` | Code review and verification | ## Example Usage **Spawn default worker:** ``` \/session-tools:spawn-session Spawned session: ai-worker-001 Working directory: \/Users\/you\/project Status: idle - At prompt To monitor: \/session-tools:summarize-session ai-worker-001 To attach: tmux attach -t ai-worker-001 ``` **Spawn with task:** ``` \/session-tools:spawn-session worker api -- Implement the REST API endpoints for user authentication Spawned session: ai-worker-api Working directory: \/Users\/you\/project Status: working - Processing prompt To monitor: \/session-tools:summarize-session ai-worker-api To attach: tmux attach -t ai-worker-api ``` **Spawn brainstorm session:** ``` \/session-tools:spawn-session brainstorm arch -- What are the best approaches for implementing caching in this codebase? Spawned session: ai-brainstorm-arch Working directory: \/Users\/you\/project Status: working - Analyzing ``` ## Workflow: Using as Subagents 1. **Spawn workers for parallel tasks:** ``` \/session-tools:spawn-session worker auth -- Implement authentication \/session-tools:spawn-session worker api -- Implement API routes \/session-tools:spawn-session worker tests -- Write integration tests ``` 2. **Monitor progress:** ``` \/session-tools:list-sessions ``` 3. **Check specific worker:** ``` \/session-tools:summarize-session ai-worker-auth ``` 4. **Handle blockers:** ``` \/session-tools:approve-action ai-worker-auth approve \/session-tools:unstick-session ai-worker-api auto ```