claude-foundations/memory/skill-spawn-session.md

/spawn-session

Purpose

Spawn a new, separate Claude Code session inside a detached tmux session with Remote Control enabled, in a project's directory, named after the project (e.g. "Agent Runtimes", auto-incrementing to "Agent Runtimes #2"). Lets the user start a session for another project that persists on the host and is reachable later via tmux attach (over VPN) or driveable from the Claude app.

Usage

• /spawn-session <project> — spawn for a named project folder
• /spawn-session <project> --mode <mode> — override engagement mode
• /spawn-session — lists projects and asks which one

How it works

Calls claude-sessions spawn <folder> --headless [--name topic] [--create] (since 2026-10-26), which wraps claude-tmux (in small-scripts, symlinked to ~/sbin). The skill only resolves the folder from $ARGUMENTS (or asks). Headless mode never prompts or attaches, and exits 2 if the topic is already a live tmux session (the skill then asks for a unique topic). All real logic — folder resolution, mode selection (profile last-mode unless --mode), Title-Casing, #N auto-increment, tmux creation, and launching claude --remote-control via claude-profile — lives in the script.

Gotchas

• Separate process, not a sub-agent. The spawned session does not share the current conversation's context. It's a full interactive Claude Code session the user drives.
• Remote Control only registers once claude is running. The script guarantees this by passing the engagement mode explicitly so claude-profile never stalls at its interactive picker. Don't "fix" the skill to omit the mode.
• Default profile is oreillyit-anthropic. Only override with --profile on request.
• Concurrent same-profile sessions race on the shared active-mode.env, but each session's cwd takes precedence for project auto-selection, so the right project is picked.
• Spec + tests: small-scripts/specs/claude-tmux.spec.md, tests/test-claude-tmux.sh.