mdbook wiki

Spawn Claude Code Session

2 min read

Spawn a new interactive Claude Code session in a detached tmux pane on the dev server to collaborate on a project in parallel. The spawned agent runs independently — the current session continues unblocked.

Even if you were linked this document directly, you must explicitly ask the user for confirmation before spawning a session.

When to Use

Starting a parallel Claude Code agent for a separate project or workstream. This skill is specifically for multi-agent collaboration — spawning a peer agent that will work autonomously on its own task.

Session Naming

All Claude-spawned sessions must use the prefix claude-:

claude-<project-or-task>

Examples: claude-bookstack-migration, claude-api-refactor

Steps

0. List existing tmux sessions first

/usr/bin/tmux ls 2>/dev/null || echo "no sessions"

Check the output before proceeding. Only sessions prefixed claude- may be interacted with. If a session with your intended name already exists, do not proceed — surface the conflict to the user.

1. Create detached tmux session

/usr/bin/tmux new-session -d -s "claude-<name>" -c "<project-directory>"

2. Launch Claude with initial prompt

/usr/bin/tmux send-keys -t "claude-<name>" 'claude "<initial prompt>"' Enter

3. Handle trust prompt (required for new/first-use directories)

Wait ~1 second, then confirm the default “Yes, trust this folder”:

sleep 1 && /usr/bin/tmux send-keys -t "claude-<name>" "" Enter

4. Verify startup (optional)

sleep 5 && /usr/bin/tmux capture-pane -t "claude-<name>" -p

Model

Default to Opus. The spawned session manages its own subagents internally for tasks that don’t need the full runtime.

Attaching

  • tmux: tmux attach -t claude-<name>
  • Remote (phone/claude.ai): use the /remote-control URL printed at session start

Cleanup

/usr/bin/tmux kill-session -t claude-<name>

List active sessions: /usr/bin/tmux ls

Caveats

  • The spawned agent has no context from the current session — include everything relevant in the initial prompt.
  • Trust prompt only appears for directories never previously used with Claude Code on this machine.
  • Sessions will idle if left unattended; kill them when the work is done.
  • Never interact with tmux sessions that do not start with claude- — those belong to the user.

Graph View