Claude Code Remote Control: how to use it, and why it fails to connect

Claude Code Remote Control connects a session running on your machine to claude.ai/code or the Claude app, so you can carry on from a phone or another browser. Start it with /remote-control inside a session. It needs a claude.ai login on Pro, Max, Team or Enterprise, talking to api.anthropic.com directly.

How Remote Control connects

Claude keeps running on your machine; the phone or browser is a window into that session. Your files, MCP servers and project configuration stay where they are, so the computer has to stay on and claude has to keep running.

• Outbound only. The local session makes outbound HTTPS requests and never opens an inbound port. It registers with the Anthropic API and polls for work.
• Routed through Anthropic. Messages between the device and your session pass through the Anthropic API over TLS, on several short-lived credentials, each scoped to one purpose.
• The transcript is stored. While connected, your messages, Claude's replies and tool activity are kept on Anthropic's servers. Organizations with Zero Data Retention or the HIPAA configuration cannot enable it.
• An off switch. The disableRemoteControl setting turns it off entirely; an IT department can set it in managed settings.

What Remote Control needs

• A claude.ai login on a paid plan. Pro, Max, Team or Enterprise, signed in with /login. "API keys are not supported", and a long-lived token from claude setup-token or CLAUDE_CODE_OAUTH_TOKEN cannot start it either.
• The Anthropic API, directly. Not on Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry; not with ANTHROPIC_BASE_URL pointing anywhere but api.anthropic.com; not through an enterprise Claude apps gateway sign-in.
• Feature flags on. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or DISABLE_GROWTHBOOK makes it unavailable. DISABLE_TELEMETRY and DO_NOT_TRACK are fine from Claude Code v2.1.283, unless your organization requires Trusted Devices.
• An Owner's yes on Team and Enterprise. It is off by default there.
• A trusted folder. Server mode asks Trust <directory>? [y/N] in a folder you have not trusted. Trust is never saved for your home directory, so run it from a project folder.

How to use Claude Code Remote Control

Three commands, one for each situation:

The first time, Claude Code asks you to confirm: Enable Remote Control? (y/n) in server mode, an Enable Remote Control button in a session. In the Claude Desktop app's Code tab and the VS Code extension, type /remote-control in the prompt box; VS Code shows no QR code and takes no name.

While connected, a session shows /rc active, linked to it on claude.ai. Run /remote-control again for the URL, the QR code and a button to disconnect while the local session keeps running.

Server mode flags worth knowing:

• --spawn worktree gives each session started from the phone its own git worktree. The default, same-dir, shares the folder, so two sessions can edit the same files. Press w to switch while it runs.
• --capacity <N> caps concurrent sessions; the default is 32.
• --permission-mode acceptEdits sets the starting mode for its sessions.
• --name "My Project" titles the session in the list.

Every session, automatically: /config → Enable Remote Control for all sessions, or "remoteControlAtStartup": true in ~/.claude/settings.json. A true in a project's .claude/settings.json is ignored, so a checked-in file cannot turn it on for everyone who opens the repository; a false there turns it off.

Connect from your phone or a browser

• Scan the QR code to open the session in the Claude app. In server mode, press the spacebar to show it.
• Open the session URL in any browser.
• Find it in the list at claude.ai/code, or under Code in the Claude app. A computer icon with a green dot means it is online.

No Claude app yet? /mobile shows a QR code for the app store. From the device you send messages, attach photos and files, answer prompts, change the model or effort, see the diff of your changes and stop a background subagent. Working from the phone itself — commands, push notifications — is in Claude Code on your phone.

Limits and timeouts

Claude Code Remote Control not working: the message and the fix

Run claude doctor first: it names the eligibility check that failed. Then match what Claude Code printed:

• "Remote Control requires a claude.ai subscription" — you are signed out, or another credential wins over your login. If it names ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or apiKeyHelper, remove it from your shell or the env block of your settings, then run claude auth login and choose claude.ai.
• "Remote Control requires a full-scope login token" — you are on a claude setup-token token or CLAUDE_CODE_OAUTH_TOKEN, which can only make model requests. Run claude auth login.
• "Remote Control is only available when using Claude via api.anthropic.com" — Bedrock, Google Cloud, Foundry or a custom ANTHROPIC_BASE_URL. The message names the variable; unset it and restart the session.
• "Remote Control isn't enabled for this account" (before v2.1.239: "Remote Control is not yet enabled for your account") — usually entitlements cached from before a plan change. Run claude auth logout, then claude auth login, and update Claude Code.
• "Remote Control requires feature-flag evaluation" — the message names the variable. Unset CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or DISABLE_GROWTHBOOK; for DISABLE_TELEMETRY or DO_NOT_TRACK, update to v2.1.283 or later.
• "Unable to determine your organization for Remote Control eligibility" — a stale account cache. Run claude auth login.
• "Couldn't verify Remote Control eligibility" or "Couldn't verify your organization's policy for remote control" — offline, a VPN not connected yet, or a proxy in the way. Restore the network and run the command again.
• "Remote credentials fetch failed" — run claude remote-control --verbose. Usually not signed in, or a firewall blocking outbound HTTPS on port 443.
• "Remote Control got an unexpected server response" — this version cannot read the reply. Run claude update, then /remote-control.
• "Error: Workspace not trusted" — server mode could not ask whether to trust the folder, because its input or output is piped or the terminal is too small. Run claude rc in the project from a normal terminal and answer y, or run claude there once and accept. In your home directory trust is never saved, so start it from a project folder.

Remote Control failed to connect: run /login

Remote Control runs on short-lived credentials renewed from your claude.ai login. When that login expires or is rejected, or you sign out in another terminal, the session keeps running locally and the transcript shows a line such as:

Remote Control disconnected — Claude.ai login expired — run /login, then /remote-control

Run /login, then /remote-control. A message ending "run /login to restore Remote Control" reconnects on its own once you sign in. If you switched account or organization somewhere else, /remote-control starts a new session under the current one; to go back, /login to the old account, then /remote-control. After claude --resume, "Couldn't reconnect to your Remote Control session" may be temporary: run /remote-control again.

Enable Remote Control on Team and Enterprise

An Owner turns on the Remote Control toggle at claude.ai/admin-settings/claude-code. If you still see "Remote Control is disabled by your organization's policy", check in this order:

• It mentions disableRemoteControl: your IT department turned it off on this device in managed settings.
• Your plan is Pro or Max: Claude Code is still signed in under an earlier Team or Enterprise organization. /status shows which; run claude auth logout, then claude auth login.
• It does not say to contact your admin: a HIPAA configuration. The toggle is greyed out; an Owner can take it up with your Anthropic account team.
• Otherwise: the Owner has not turned it on yet. After they do, an open session fetches the policy about once an hour.

Trusted Devices, in beta at Anthropic, adds a second gate: each phone, browser or desktop app enrolls once after a full sign-in, and a sign-in older than 18 hours needs Face ID, Touch ID, Windows Hello or a passkey. An Owner turns it on under Organization settings → Capabilities → Remote sessions; on Pro and Max you turn on Require trusted devices yourself. "This device is not enrolled" and "session expired for trusted-device check" are both fixed with /login.

Remote Control vs Dispatch, Channels and cloud sessions

Anthropic's ways to work away from the terminal differ in where Claude runs and what starts the work:

• Remote Control steers a session already running on your machine. Use it to keep going on local work from another device.
• Dispatch is a conversation in the Claude Desktop app's Cowork tab that you message from the Claude app. For development work it starts a Code session on your machine, badged Dispatch, and pushes to your phone when it finishes or needs approval. Pro and Max only, not Team or Enterprise. Use it to hand off a new task with little setup.
• Channels push messages from Telegram, Discord, iMessage or your own server into a running CLI session. A research preview; it also works on a Console API key. Use it when Claude should react to chat or CI. More in Claude Code notifications.
• Cloud sessions (Claude Code on the web) run on infrastructure Anthropic manages by default, with nothing running on your machine. Use them for a repo you have not cloned, or several tasks at once.

What Remote Control does not reach: Caprock

Remote Control covers one kind of session: a claude.ai login, talking to api.anthropic.com, that you connected. A session on an API key, Bedrock, Google Cloud's Agent Platform (Vertex AI) or a company gateway has none, and neither does Codex or OpenCode.

Remote Control is Anthropic's free remote for one Claude Code session on a claude.ai plan. Caprock, a free desktop app, keeps the record of every agent on the machine — the sessions it did not start included, how close each subscription is to its limit, each pull request's CI state and what it cost — and the phone is how you carry that record, with no account:

• From anywhere, end to end encrypted. Pair the phone by scanning a QR code; it reaches your machine through a relay that carries only ciphertext, Caprock's or one you run.
• You choose what it may do. It can control sessions, ticked by default when you connect a phone, lets it start sessions and type; untick it and the phone only reads until you press Allow control beside it on the computer.
• Your shell profile's settings. A session Caprock starts gets the environment your login shell sets up, so an API key, Bedrock or Google Cloud's Agent Platform (Vertex AI) setting, or a gateway in ANTHROPIC_BASE_URL, that your profile exports reaches it, as it reaches claude in a new terminal; settings in ~/.claude/settings.json apply as usual. A variable you set by hand in one terminal window does not.
• Six agents. Start Claude Code, Codex, OpenCode, Gemini CLI, Grok Build or Hermes Agent, whichever is installed, in any folder under your home directory, type into it, attach a photo, stop it. In Claude Code sessions it started, a permission prompt gets Yes, Claude Code's second option and No as buttons.
• Every session, watched. It reads every Claude Code session on the machine, including ones started in your own terminal, and types only into the ones it started.
• Alerts. Settings → Telegram sends a message through your own bot when a Claude Code session waits for approval or finishes.

Pairing, granting control and the phone screens, step by step: Claude Code on your phone. To type into a session you started in your own terminal on a claude.ai plan, use Remote Control.

Caprock is free and open source, and nothing leaves your machine unless you switch it on. Install Caprock.