Files

Paul O'Reilly 562be1faf1 feat(spawn-session): skill wrapping claude-tmux to spawn Remote-Control sessions

Thin /spawn-session skill that resolves a project name and shells out to the
claude-tmux script to launch a new detached tmux Claude Code session with
Remote Control. Installed into the active profile; README catalogue updated.

Claude-Session: https://claude.ai/code/session_014oa7T7z1h5n34vu8vX9zGT

2026-07-25 16:29:46 +12:00

3.0 KiB

Raw Blame History

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. Wraps the claude-tmux script.	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

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.
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.
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.

3.0 KiB Raw Blame History