diff --git a/README.md b/README.md index 585aec0..2d068ff 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ The install script creates symlinks from `~/.claude/skills/` to this repo, makin | housekeeping | `/housekeeping` | Cross-project health check: git status, unreflected logs, skill validation, pipeline recommendations | | decompose | `/decompose ` | Break a task into subtasks with dependency graph. Writes `.agent-tasks.json` for container agent orchestration. | | orchestrate | `/orchestrate` | Check task state, launch container agents in git worktrees. Use `/loop 2m /orchestrate` for auto-polling. | +| spawn-session | `/spawn-session ` | Spawn a new detached tmux Claude Code session with Remote Control, named after the project (wraps `claude-tmux`). Attach later via `tmux attach` over VPN or drive from the Claude app. | ## Adding a New Skill diff --git a/skills/spawn-session/SKILL.md b/skills/spawn-session/SKILL.md new file mode 100644 index 0000000..8ffc770 --- /dev/null +++ b/skills/spawn-session/SKILL.md @@ -0,0 +1,61 @@ +--- +name: spawn-session +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 *) +--- + +# 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 + +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 + above. Do not guess. + - Flags the user may include and you should pass straight through: `--mode `, + `--profile `, `--name ""`, `--attach`, `--dryrun`. + +2. **Spawn it.** Run: + ``` + claude-tmux [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. + +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. + +## 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`.