Remote Control Handbook

Claude Remote Control Sessions

A Remote Control session is a Claude Code process running on your machine that has registered itself with the Anthropic API so other devices can view and steer it. The session is the process. Understanding that one fact explains almost every session question: naming, resuming, running several at once, and why they end.

Sessions appear in the list at claude.ai/code and under Code in the Claude mobile app. An active one shows a computer icon with a green status dot.

Starting a new session

Three routes, depending on where you are:

CommandCreates
claude remote-controlA server that hosts sessions, up to 32 concurrently by default
claude --remote-controlOne interactive session you can also type into locally
/remote-control inside a sessionConverts the session you are in, carrying its history across

If the environment already has an active session, Claude Code asks whether to continue that one or start a new one rather than silently creating a duplicate.

Naming sessions

Names matter more than they look, because the session list is how you find your way back. Claude Code picks the title in this order:

  1. The name you passed to --name, --remote-control, or /remote-control
  2. A title you set with /rename
  3. The last meaningful message in the existing conversation
  4. An auto-generated name such as myhost-graceful-unicorn

Set one explicitly if you run more than one session:

claude remote-control --name "api refactor"
claude --remote-control "docs cleanup"
/remote-control billing bugfix

Without an explicit name the title updates to reflect your prompt once you send one. From v2.1.176 auto-generated titles match the language of your conversation, or your language setting. Renaming from claude.ai or the mobile app also updates the local title you see in claude --resume.

In server mode, --remote-control-session-name-prefix changes the auto-name prefix, which defaults to your machine hostname. The CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX variable does the same thing.

Resuming a session

From v2.1.200, server mode can pick up where it left off instead of always creating something new:

FlagBehaviour
-c, --continueResumes the most recent Remote Control session started from this directory
--session-id <id>Resumes one specific session by its ID

Neither can be combined with the other, nor with --spawn, --capacity, or --create-session-in-dir. On builds older than 2.1.200 both are rejected as unknown arguments, which is a common source of confusion. See version compatibility.

Separately, when you resume a conversation with claude --resume or claude --continue, Claude Code tries to reconnect to the Remote Control session recorded in that conversation. If that fails it tells you, and your local session keeps running without Remote Control. Run /remote-control to retry.

Before v2.1.200 a failed reconnection silently created a new session instead of reporting the failure, which is why some people find duplicate entries stacking up in their session list. Upgrading stops it.

Running several sessions at once

Outside server mode, each Claude Code process supports exactly one remote session. So there are two shapes:

ApproachHowTrade-off
One process per sessionRun claude --remote-control in several terminal windowsSimple, but every session needs its own window open
Server modeRun claude remote-control onceOne process hosts many. Default capacity 32, set with --capacity

Keeping parallel sessions out of each other’s way

This is the part people get wrong. In server mode, --spawn decides whether sessions share a working directory:

  • same-dir (default): every session shares the current directory, so two sessions editing the same file will conflict.
  • worktree: each on-demand session gets its own git worktree. Requires a git repository. This is what you want for genuine parallel work.
  • session: single-session mode. Serves exactly one and rejects further connections. Set at startup only.

Press w at runtime to toggle between same-dir and worktree. --capacity cannot be combined with --spawn=session.

claude remote-control --spawn worktree --capacity 6

Why sessions end

  • The process stopped. Close the terminal, quit VS Code, or kill claude and the session ends. It is a local process, not a service.
  • Extended network loss. If your machine is awake but cannot reach the network for more than roughly ten minutes, the session times out and the process exits.

Short interruptions are fine. A sleeping laptop or a brief Wi-Fi drop reconnects automatically, and from v2.1.207 status updates queued during the outage are delivered once it recovers.

If you need a session to outlive your SSH connection, see running Remote Control on an always-on machine.