diff --git a/skills/spawn-session/SKILL.md b/skills/spawn-session/SKILL.md index 8ffc770..760fcee 100644 --- a/skills/spawn-session/SKILL.md +++ b/skills/spawn-session/SKILL.md @@ -4,15 +4,18 @@ 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 *) + attach to over VPN/tmux later or drive from the Claude app. Uses the claude-sessions + script's headless mode so the session is tracked like every other session. +allowed-tools: Bash(claude-sessions spawn *), 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. +from the Claude app. This calls `claude-sessions spawn --headless` (which wraps `claude-tmux`) — you do not reimplement its logic. +Sessions started this way appear in the `claude-sessions` menu with the same name and +location as ones started from it. ## Pre-gathered context @@ -24,32 +27,35 @@ from the Claude app. This wraps the `claude-tmux` script — you do not reimplem ## 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 +1. **Determine the folder and topic.** The user's argument is: `$ARGUMENTS`. + - If it names a project (a folder basename from the list above, e.g. `agent-runtimes`) + or gives a folder path, use it. + - If it is empty, ask the user which folder to spawn a session for, offering the list above. Do not guess. - - Flags the user may include and you should pass straight through: `--mode `, - `--profile `, `--name ""`, `--attach`, `--dryrun`. + - The **topic** is the session name. It defaults to the Title-Cased folder name. Pass + `--name ""` only if the user gave one. + - Other flags to pass straight through: `--mode `, `--profile `. + - If the user names a folder that does not exist and wants it made, use an absolute path + and add `--create`. Otherwise do not create folders. 2. **Spawn it.** Run: ``` - claude-tmux [flags] + claude-sessions spawn --headless [--name ""] [--create] [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. + Headless mode never prompts and never attaches. It resolves the folder, creates the + detached tmux session there, and launches Claude Code with `--remote-control` under it. + The engagement mode is the profile's `last-mode` unless `--mode` is given. - 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. + **If it exits with code 2**, the topic is already in use. Ask the user for a different + topic and re-run with `--name`. Do not invent a suffix such as `#2`. -3. **Report back** exactly what the script prints: the session name, how to attach - (`tmux attach -t ""`), 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. + Do **not** pass `--attach`. 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, the folder, how to + attach (`tmux attach -t ""`), and the Remote-Control name to look for in the + Claude app. The session persists on the host and is reachable over the VPN via + `tmux attach` whenever the user reconnects. ## Notes @@ -58,4 +64,4 @@ from the Claude app. This wraps the `claude-tmux` script — you do not reimplem - 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`. +- To preview without creating anything, run `claude-tmux --dryrun` instead.