Spawn Session — Claude Code Session Launcher
Runs independent Claude Code sessions in new terminal windows. Supports Ghostty (default), iTerm2, and macOS Terminal.app.
Workflow
Step 1: Gather Information from User
Collect the following two pieces of information interactively:
- Session name — A name to identify the session (e.g.,
backend-refactor,test-writer,docs-update) - Project directory — The directory path where Claude Code will work
How to collect:
- If the user has already provided the information in the conversation, use it as-is
- If any information is missing, ask the user
- You can suggest directory candidates using
lsorfind - If the directory doesn't exist, confirm whether to create it
Step 2: Detect OS and Execute Spawn
Run the scripts/spawn.sh script from this skill:
bash <this skill's path>/scripts/spawn.sh --name "<session-name>" --dir "<project-directory>" [options...]
Step 3: Verify Execution and Report
- Check the script's exit code and stdout
- On success: Briefly summarize the session name, directory, and execution mode
- On failure: Analyze the error cause and suggest a resolution
spawn.sh Options
| Option | Description | Default |
|---|---|---|
--name, -n | Session name (required) | — |
--dir, -d | Project directory (required) | — |
--terminal, -t | Terminal to use (ghostty, iterm, terminal) | ghostty |
--prompt, -p | Initial prompt (non-interactive mode) | None (interactive) |
--resume, -r | Resume existing session | false |
--model, -m | Specify model | Default model |
--print | Non-interactive + stdout only | false |
--dangerously-skip-permissions | Skip all permission prompts | false |
Usage Scenarios
Single session spawn:
User: "Open a new session"
→ Ask for session name and directory, then spawn
Information already provided:
User: "Launch Claude as backend-worker in ~/projects/my-app"
→ Spawn immediately
Parallel multi-spawn:
User: "Spawn 3 sessions in parallel - API, DB, Test"
→ Call spawn.sh 3 times (each with & for background)
With a prompt:
User: "Tell it to write tests in ~/projects/game"
→ Pass instructions via --prompt option
Tips
- Suggest the user name their main session with
/rename mainfor easy identification among spawned sessions - Recommend enabling Remote Control (
/config→ Enable Remote Control for all sessions →true) so all sessions can be monitored from phone or browser via claude.ai/code
Notes
- Each terminal window is a completely independent process — inter-session communication is handled via shared filesystem
- When using
--prompt, the terminal window closes automatically after task completion - When using
--resume, it continues an existing session with the same name - Use
--terminalto select the terminal (default: ghostty) - Only ghostty is supported on Linux