How do `claude remote-control`, `claude --remote-control` and `/remote-control` differ in Claude Code, and what makes a Remote Control session go offline?
answer
- server, flag, or slash command
- a local prompt or none
- spawn modes and capacity
- auto-connect setting
- the process must stay alive
basics
~20 sclaude remote-control runs a server with no local prompt that can serve many sessions; claude --remote-control starts one interactive session also reachable remotely; /remote-control connects the session you are in. Each goes offline when the machine sleeps or the claude process stops.
solid answer
~50 s**Server mode**, `claude remote-control`, waits for connections without a local prompt, shows a URL and QR code, and can serve several sessions: `--spawn same-dir` (default) shares the directory, `--spawn worktree` gives each on-demand session its own git worktree, `--spawn session` serves exactly one, and `--capacity` caps concurrency at 32 by default. **`claude --remote-control`** (`--rc`) is a normal interactive session you can also type into locally, one remote session per process. **`/remote-control`** (`/rc`) connects the session you are already in, carrying its history; it is also how Desktop and the VS Code extension turn it on. Auto-connect for every interactive session is a `/config` toggle or `remoteControlAtStartup` in user or managed settings; a project file can turn it off but not on. In every form execution is local, so closing the terminal, quitting the app or a sleeping laptop takes the session offline until the process returns.
go deeper
Recall the three forms: a server with no prompt, a flag on a normal session, and a slash command for the session you are already in.
Explain server mode's spawn modes and capacity, how auto-connect is set and why a project file cannot turn it on, and why every form goes offline with the local process.
Run it reliably on a remote box: tmux or screen, worktree spawning to avoid file clashes, bringing sessions back after a restart, and reading eligibility errors from the message and claude doctor.
Decide whether to allow it at all: execution stays local, but transcripts are stored remotely while connected and access hinges on account security, which Trusted Devices and the admin toggle address.
## Three ways in **Remote Control** connects claude.ai/code or the Claude mobile app to a Claude Code session running on your machine. There are three ways to start it, and they differ mainly in whether you also have a local prompt and how many sessions one process serves. | Invocation | Local prompt | Sessions per process | Typical use | | :- | :- | :- | :- | | `claude remote-control` | None (server mode) | Many, up to `--capacity` | A machine you mostly drive from elsewhere | | `claude --remote-control` / `--rc` | Yes | One | Work at the desk that you may continue from a phone | | `/remote-control` / `/rc` | Yes, the current session | One | You are mid-task and about to leave | `/remote-control` carries the current conversation over; it is also the command the Desktop app's Code tab and the VS Code extension use. A name can be passed to the flag, the slash command or server mode's `--name`. ## Server mode options `claude remote-control` stays in the terminal waiting for connections, prints a session URL and shows a QR code when you press the spacebar. Its flags shape how sessions are created: - **`--spawn same-dir`** (default): all sessions share the current directory, so two can edit the same files. - **`--spawn worktree`**: each on-demand session gets its own git worktree; this needs a git repository, and `w` toggles between the two at runtime. - **`--spawn session`**: single-session mode; extra connections are rejected. - **`--capacity <N>`**: the concurrency cap, 32 by default. - **`--permission-mode <mode>`**: the starting permission mode for the server's sessions. - **`--chrome` / `--no-chrome`**: whether those sessions get the browser integration; without the flag, sessions you start remotely begin with it off. Global flags placed before `remote-control` are not carried into the sessions it creates; for flags that would change what those sessions can do, such as `--settings`, the server refuses to start and names the flag. After you stop the server with Ctrl+C, running `claude remote-control` (all sessions), `--continue` or `--session-id <id>` in the same directory brings sessions back for about four hours. ## Turning it on everywhere Remote Control only starts when asked, unless **auto-connect** is on: 1. In the CLI, `/config` and **Enable Remote Control for all sessions** (`true`, `false` or `default`). 2. In Desktop, **Connect new sessions to Remote Control**; in VS Code, the same toggle in the command menu. 3. In a file, `remoteControlAtStartup: true` in user `~/.claude/settings.json` or managed settings. A project or local settings file can set it to `false` for that repository, but its `true` is ignored, so a checked-in file cannot switch Remote Control on for everyone who opens the repository. Auto-connect registers one remote session per interactive process, under your own account only. ## What takes it offline Remote Control is a local process with a remote window, so its failure modes are local: - **The process stops**: closing the terminal, quitting Desktop or VS Code, or killing `claude` takes the session offline. On an SSH box, run it inside `tmux` or `screen`. - **The machine sleeps or loses network**: it reconnects when the machine is back. In an extended outage, server mode gives up after roughly ten minutes and exits, while an interactive session keeps retrying. - **Another device takes over**, or the session is archived elsewhere: the indicator says so, and `/remote-control` takes it back. - **Policy changes**: if the organization turns Remote Control off mid-session, it disconnects and does not reconnect on its own. ## What a connected device can do The phone or browser drives the same conversation, but not every command crosses over: - Text-output commands such as `/compact`, `/context` and `/usage` work from mobile and web. - `/model`, `/effort` and `/rename` take their value as an argument there, for example `/model sonnet`, instead of opening a picker. - Commands that only run in the terminal interface, such as `/plugin` or `/resume`, work only from the local CLI. - With **Push when Claude decides** or **Push when actions required** turned on in `/config`, the Claude app receives a notification when a long task finishes or a permission prompt is waiting. ## Eligibility, briefly Remote Control needs a claude.ai subscription login (Pro, Max, Team or Enterprise); API keys and the model-only token from `claude setup-token` are refused. It is unavailable on Bedrock, Agent Platform or Foundry, or when `ANTHROPIC_BASE_URL` points at a gateway. On Team and Enterprise an Owner must enable it first. Which credential is in force, and why, is part of authentication rather than of this surface; `claude doctor` reports which Remote Control eligibility check failed.
- Why might `claude remote-control` refuse to start on a machine where ordinary `claude` sessions work fine?The usual causes are an API key, `ANTHROPIC_AUTH_TOKEN` or `apiKeyHelper` taking precedence over the claude.ai login; a model-only token from `claude setup-token`; a Bedrock, Agent Platform or Foundry setup or a gateway `ANTHROPIC_BASE_URL`; the Team or Enterprise toggle being off; or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` disabling feature-flag evaluation. The error names the cause, and `claude doctor` shows which check failed.
- Can a teammate commit `remoteControlAtStartup: true` to `.claude/settings.json` to turn it on for the whole team?No. In project or local settings Claude Code honours `false`, which turns auto-connect off for that repository, but ignores `true`. It can be turned on from user settings, the `/config` toggle, or managed settings. Auto-connect always signs in with each developer's own account, so it never grants anyone else access.
- claude remote-control and claude --remote-control both give you a local prompt.
- A committed remoteControlAtStartup true turns it on for everyone in the repo.
- Server mode's default spawn gives each session its own git worktree.
- Remote Control works with the long-lived token from claude setup-token.
- Remote Control opens an inbound port that the phone connects to.