custom-claude-skills/skills/spawn-session/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
spawn-session	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. Uses the claude-sessions script's headless mode so the session is tracked like every other session.	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 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

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 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.
   • The topic is the session name. It defaults to the Title-Cased folder name. Pass --name "<topic>" only if the user gave one.
   • Other flags to pass straight through: --mode <name>, --profile <name>.
   • 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-sessions spawn <folder> --headless [--name "<topic>"] [--create] [flags]
   

   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.

   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.

   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 "<name>"), 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

• 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, run claude-tmux <folder> --dryrun instead.