---
name: spawn-session
description: >
  Spawn a new detached tmux session running Claude Code with Remote Control enabled,
  in a project's directory, named after the project (e.g. "Agent Runtimes #2"). Use when
  the user wants to start a separate Claude Code session for another project that they can
  attach to over VPN/tmux later or drive from the Claude app. Wraps the claude-tmux script.
allowed-tools: Bash(claude-tmux *), Bash(ls *), Bash(tmux ls), Bash(tmux list-sessions *)
---

# Spawn Session Skill

Spawn a new, independent Claude Code session inside a detached `tmux` session with
Remote Control enabled, so the user can attach to it later (`tmux attach`) or control it
from the Claude app. This wraps the `claude-tmux` script — you do not reimplement its logic.

## Pre-gathered context

### Available projects (folders under ~/dev/claude and ~/dev/claude/projects)
!`ls -d "$HOME"/dev/claude/*/ "$HOME"/dev/claude/projects/*/ 2>/dev/null`

### Existing tmux sessions
!`tmux list-sessions -F '#{session_name}' 2>/dev/null || echo "(no tmux server running)"`

## Instructions

1. **Determine the project.** The user's argument is: `$ARGUMENTS`.
   - If it names a project (a folder basename from the list above, e.g. `agent-runtimes`
     or `cluster-bootstrap`), use it.
   - If it is empty, ask the user which project to spawn a session for, offering the list
     above. Do not guess.
   - Flags the user may include and you should pass straight through: `--mode <name>`,
     `--profile <name>`, `--name "<display>"`, `--attach`, `--dryrun`.

2. **Spawn it.** Run:
   ```
   claude-tmux <project> [flags]
   ```
   The script resolves the folder, picks the engagement mode (the profile's `last-mode`
   unless `--mode` is given), Title-Cases the project into a session name, auto-increments
   with a ` #N` suffix if that name is already taken, creates the detached tmux session in
   the project's directory, and launches Claude Code with `--remote-control` under it.

   Do **not** pass `--attach` unless the user explicitly asked to attach — the point is
   usually to leave it running detached for later. The default profile is
   `oreillyit-anthropic`; only override with `--profile` if the user asks.

3. **Report back** exactly what the script prints: the session name, how to attach
   (`tmux attach -t "<name>"`), and the Remote-Control name to look for in the Claude app.
   If the user is on a machine without power (the common reason for this), remind them the
   session persists on the host and is reachable over the VPN via `tmux attach` whenever
   they reconnect.

## Notes

- This starts a **new, separate** Claude Code process — it is not a sub-agent and does not
  share this conversation's context. It is a full interactive session the user drives.
- Remote Control registers in the Claude app only once `claude` is actually running inside
  the tmux session; `claude-tmux` guarantees this by passing the mode explicitly (never
  leaving the launcher stalled at an interactive picker).
- To preview without creating anything, pass `--dryrun`.