| name | spawn-remote |
| description | Spawn a remote-control Claude Code instance from inside the current Codex session via detached tmux, and return its /remote-control URL. Use when the user wants to fire off a sibling Claude Code session they can drive in parallel from a browser (e.g. delegate a long task to CC while keeping the current Codex session free). Only works on the local host. Codex itself does not have a /remote-control equivalent, so this is a cross-tool helper (Codex → Claude Code), not a Codex-to-Codex spawner. |
Spawn a sibling Claude Code instance in a detached tmux session and return its /remote-control URL. Everything goes through the shell — Codex talks to tmux, which talks to the spawned claude TUI.
When to use
All of the following must hold:
- User is on a remote machine (typically via SSH).
- User wants a Claude Code session they can open at
https://claude.ai/code/session_<id> and drive in parallel from a browser — e.g. delegate a long task to CC while the current Codex session keeps going.
Do not use this for: starting claude in the foreground (use the shell directly), spawning on a different host (this skill assumes localhost), or attaching to an already-running tmux session (use tmux a directly). There is currently no Codex /remote-control equivalent, so this skill is one-way (Codex → Claude Code).
Argument
The user's message may name a desired tmux session. If absent, auto-pick the first free c<N> with N≥2.
Prerequisites (one-shot check)
Run this first; abort and report to the user if anything prints MISSING:. Installing tmux / claude or doing first-run setup is on the user.
command -v tmux >/dev/null || echo "MISSING: tmux"
command -v claude >/dev/null || echo "MISSING: claude"
[ -f "$HOME/.claude.json" ] || echo "MISSING: ~/.claude.json (run claude once interactively first)"
[ -d "$HOME/.claude" ] || echo "MISSING: ~/.claude"
Step 1 — Pick a non-conflicting tmux session name
The user's request may contain a desired session name. If empty, auto-pick the first free c<N> with N≥2:
SESSION="<user-provided-or-empty>"
if [ -z "$SESSION" ]; then
for i in 2 3 4 5 6 7 8 9; do
if ! tmux has-session -t "c$i" 2>/dev/null; then SESSION="c$i"; break; fi
done
fi
[ -z "$SESSION" ] && { echo "ERROR: c2-c9 all taken; pass an explicit name"; exit 1; }
echo "Using session: $SESSION"
If the user supplied a name and it is already taken, abort with a clear message — do not silently rename, and do not kill the old one (it may be a sibling the user is actively driving).
Persist $SESSION between shell calls by exporting it or by re-deriving it; do not assume the variable survives across separate shell invocations.
Step 2 — Start claude detached in tmux
tmux new -d -s "$SESSION" -x 200 -y 50 claude
sleep 5
tmux capture-pane -t "$SESSION" -p | tail -30
-x 200 -y 50 is not optional: narrower panes wrap the session URL across two lines and the Step 5 regex won't match.sleep 5 is also not optional — claude needs ~5 s to render its first prompt. Shorter sleeps race the next step.
Step 3 — Handle the trust dialog (if it appears)
If the Step 2 capture contains Is this a project you created or one you trust?, claude is waiting for confirmation. Send Enter (default selection = "Yes, I trust"), then re-capture:
tmux send-keys -t "$SESSION" Enter
sleep 3
tmux capture-pane -t "$SESSION" -p | tail -20
Verify the input prompt ❯ is visible before continuing. The trust dialog appears the first time claude is started in a working directory; subsequent spawns from the same directory skip it.
If the capture from Step 2 already shows ❯ and no trust prompt, skip this step.
Step 4 — Send /remote-control
tmux send-keys -t "$SESSION" '/remote-control' Enter
sleep 6
tmux capture-pane -t "$SESSION" -p | tail -20
sleep 6 is the slowest of the three — /remote-control takes 3-6 s to print the URL on first call.
Step 5 — Extract the URL
tmux capture-pane -t "$SESSION" -p | grep -oE 'https://claude\.ai/code/session_[A-Za-z0-9]+' | head -1
If empty, the URL hasn't rendered yet (or got wrapped because the pane is too narrow). sleep 4 and retry the grep once. If still empty, capture the full pane (tmux capture-pane -t "$SESSION" -p) and report what you see — do not retry indefinitely.
Report to the user
✅ Spawned `<name>` → https://claude.ai/code/session_<id>
Kill when done: tmux kill-session -t <name>
Cleanup helpers
| What | Command |
|---|
| Kill this spawned instance | tmux kill-session -t <name> |
| Peek at live screen | tmux capture-pane -t <name> -p |
| Attach (if user has a TTY) | tmux a -t <name> |
| List all sessions | tmux ls |
The spawned claude is fully detached from the SSH session: dropping the SSH connection does not kill it.
Common pitfalls
- Don't shorten the
sleeps. The 5 s / 3 s / 6 s waits correspond to real startup phases (cold-start render, dialog dismiss, /remote-control URL render). Faster sleeps capture half-rendered TUI; the regex then misses and you waste a retry round.
- Always check for the trust dialog before Step 4. Even if the user thinks the directory was trusted before, a fresh
~/.claude/projects/<dir> entry on a different host can re-trigger it.
- Don't reuse a live session name.
tmux new -d -s c2 errors if c2 exists. Do not pass -A or kill the old one — it may be a sibling the user is actively using.
- Pane width matters.
-x 80 (the typical default) wraps the URL onto two lines and the regex misses. Always pass -x 200 -y 50.
- The spawned claude inherits the current cwd. If the user wants the new instance to start somewhere else, do that change yourself —
cd first, or wrap the launch as tmux new -d -s "$SESSION" -x 200 -y 50 -c <path> claude.
