37 lines
2.0 KiB
Markdown
37 lines
2.0 KiB
Markdown
# /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`.
|