Claude Code Remote Control keeps disconnecting? Causes and fixes

Short answer

Claude Code Remote Control and Codex remote in the ChatGPT mobile app are both built the same way: your phone talks to the vendor's servers, which talk to a process on your computer. When they drop or never connect, the cause is almost always on the computer side: it went to sleep, the process exited, a proxy blocked the outbound connection, or your login or workspace policy doesn't meet the requirements. Most of these you can fix with the checklist below. If you keep hitting the same wall because your laptop sleeps, your network needs a proxy, or you sign in a way the official remote doesn't support, it's worth looking at a different architecture.

Everything below about the official products was checked on October 31, 2026 against the Claude Code docs, OpenAI's help docs for remote connections, and public issues in both GitHub repositories. Both change quickly, so trust the current docs over this post.

First, figure out which link broke

Every remote setup has three links: phone to server, server to computer, and the agent process itself. A "disconnected" badge on your phone doesn't mean the work stopped. The Claude Code docs say this directly: "Remote Control disconnected" or "Can't reach" in the browser or desktop app means that surface lost contact with your computer, and it doesn't tell you whether Claude or a subagent is still working.

So step one is always the computer. Is the process still running? Did the terminal print an error? Did the machine sleep? Re-opening the app on your phone ten times won't tell you any of that.

Why Claude Code Remote Control disconnects

The process is gone

Remote Control is a window into a local process. Per the docs, closing the terminal, quitting the desktop app or VS Code that hosts the session, or otherwise stopping claude takes the session offline. If you run claude over SSH on another machine, the docs recommend tmux or screen so the process survives when SSH drops.

To get back in, resume the conversation with claude --continue or claude --resume. If you see "Couldn't reconnect to your Remote Control session", run /remote-control in that session to retry, or start fresh with claude --remote-control.

Sleep and network outages

The docs say Claude Code reconnects automatically after the laptop sleeps or the network drops, once the machine is back online. The two modes behave differently when the machine is awake but offline:

• Server mode (claude remote-control) gives up after roughly 10 minutes and exits. You have to start it again.
• Interactive sessions (claude --remote-control or /remote-control inside a session) keep retrying for as long as the outage lasts and reconnect by themselves.

On flaky Wi-Fi, an interactive session is the more forgiving choice. Two more cases from the docs: if the disconnect reason says could not reach the Remote Control server for about 30 minutes, run /remote-control to reconnect; after a VPN or network change, Claude Code retries HTTP 403 refusals for up to three minutes, then disconnects and names what refused, either a network edge or a proxy, VPN or firewall on your side.

Keeping the machine awake is its own topic; see keep your Mac awake while Claude Code or Codex runs.

Login and policy problems

These show up as "never connects", not "connects then drops". Typical messages in the docs:

• Remote Control requires a claude.ai subscription, or requires claude.ai subscription auth when ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or an apiKeyHelper puts the session on API-key auth.
• The session isn't talking to the Anthropic API directly: Amazon Bedrock, Google Cloud, Microsoft Foundry, or ANTHROPIC_BASE_URL pointing at a gateway or proxy, even if you signed in with claude.ai.
• Your organization disabled it, the policy couldn't be fetched (often because Claude Code started offline or before the VPN came up), or Trusted Devices is required and this device isn't enrolled.

Run claude doctor to see which check failed. If you run Claude Code on an API key or a proxy on purpose, there's nothing to fix here; the official remote just doesn't cover you. We wrote about that case in using Claude Code with an API key or proxy from your phone.

Open issues

As of the check date, anthropics/claude-code issue #95001 is still open: a device's auth token lacked a newer scope, and even after signing in again, a session created earlier stayed "Disconnected" with no reconnect button. If every session shows disconnected while one is clearly running, sign out and back in, then run /remote-control in the running session; if that fails, start a new Remote Control session.

Codex mobile stuck on "Waiting for desktop"

First, the entry point moved. Older guides send you to a separate Codex desktop app; OpenAI's help docs now say setup happens in the ChatGPT desktop app on macOS or Windows, under Settings › Connections › Control this Mac or PC. You can't start it from the Codex CLI or the IDE extension, each phone pairs with each computer separately, and remote access stops whenever the computer sleeps, loses network or closes the app.

A practical order, based on the docs and public openai/codex issues:

1. Same account and workspace. Both devices must use the same account and workspace, the desktop app must be running, and "Allow other devices to connect" must be on. Workspace users may need an admin to enable remote access.
2. Multi-factor authentication. In issue #27167 the phone sat on "Waiting for computer response" while the local log showed the server returning Multi-factor authentication required. Turn on MFA in ChatGPT security settings and retry.
3. Proxy. Issue #22851 (still open) describes a Mac that needs a local proxy: the background remote-control process didn't use it, couldn't reach OpenAI, and the desktop app still showed a QR code, so it looked like a pairing problem. Make sure that process can reach chatgpt.com.
4. Pair again. Per the docs, connections used since June 8, 2026 stay paired; older ones need both apps updated and a fresh pairing. Leave the waiting screen on the phone, generate a new QR code on the computer, and scan again.
5. One host process. Users running a separate codex remote-control while the desktop app was open saw 409 Remote app server already online. Keep one.
6. Restart and read the logs. The docs' fix for an error right after choosing Add is to restart the desktop app. A report of Android phones waiting forever on a Windows host (#22733) was still open on the check date.

If it connects and then drops, the docs list three things to check: sleep, network, and whether the app closed. There is a "Keep this Mac awake" option for when the computer is plugged in with remote access on, but choosing Sleep still disconnects, and a closed-lid Mac also needs an external display.

When to stop tweaking and switch

The checklist fixes most cases. If you keep coming back to it, the problem is structural:

• The session lives inside one foreground process, so closing a terminal or app ends it.
• Some failures need you at the keyboard: server mode exits after a long outage, and a session hit by a token problem doesn't recover by itself.
• Your login or model provider isn't supported at all.
• You run more than one agent and debug two remote stacks.

The free fallback still works: tmux plus SSH over a mesh VPN like Tailscale keeps sessions alive across drops and works with any agent. The cost is driving a terminal on a phone keyboard, with no approve button and no push notifications.

How BotBus handles drops

BotBus is a resident app on your computer (a menu bar app on Mac, a background program on Linux and Windows) that syncs tasks from local agents like Codex and Claude Code to iPhone, Apple Watch and Android. On disconnects specifically, it differs in a few concrete ways:

• No terminal window to keep open. You still start Claude Code with claude; hooks that BotBus installs sync its status and approvals. When you start or continue a task from your phone, BotBus launches the process itself and owns that turn. Codex connects through codex app-server; when it's shared with the Codex desktop app, a BotBus disconnect doesn't kill the desktop side, and on reconnect BotBus picks up in-flight turns and unanswered approvals.
• Automatic reconnect. The computer holds a WebSocket to the relay with a ping every 30 seconds. When it drops, it reconnects with backoff starting at one second and capped at 60. Short drops don't interrupt tasks running on the computer.
• Offline computers stay visible. The relay keeps the last task list for each computer, and the phone shows it as offline and read-only rather than empty.
• Commands queue without running twice. If the computer is briefly offline, approvals and follow-ups wait in the relay for up to 10 minutes and are delivered on reconnect. They count as delivered only when the computer acknowledges them, and the computer de-duplicates by command ID. Past 10 minutes the phone shows a failure instead of spinning forever.
• The agent isn't stuck when BotBus is. If BotBus isn't running, its Claude Code hook stays out of the way and Claude Code shows its normal permission prompt in the terminal.
• Any login. It runs the claude and codex you already configured, whether that's a subscription, an API key or a proxy.

Content is end-to-end encrypted on your devices before it leaves; the relay sees ciphertext plus device IDs, online status, update times and data sizes, and dev previews are outside the end-to-end encryption. Details are on the security page.

Limits

BotBus fixes where the session lives and who reconnects it. It can't fix a computer that is actually offline:

• The computer must be awake and online. BotBus doesn't prevent sleep. Approving, continuing, starting and stopping tasks all need the target computer online, and depend on the connector and task state.
• There is still a relay in the middle. If it has an outage, your phone can't reach the computer either; the computer just keeps retrying on its own.
• The queue has limits: 50 commands per computer, 10 minutes each.
• One BotBus per computer. A second instance takes over and the first one stops.
• Stop only works on processes BotBus launched. Sessions you started in a terminal are stopped in that terminal.
• It's a different experience. You get a task list and on-demand transcripts, not the same conversation live in terminal, browser and phone at once.

If you only use Claude Code on a subscription and your machine rarely sleeps, a working Remote Control is still the least effort; the same goes for Codex users and the ChatGPT app. They also run fine alongside BotBus. Desktop and phone apps are in the download section.

FAQ

Remote Control says disconnected. Is my task still running?

Maybe. The docs say the message only means the browser or app lost contact with your computer. Check the process and terminal output on the computer.

Which is more reliable, claude remote-control or claude --remote-control?

On an unreliable network, the interactive session. It retries for the whole outage and reconnects on its own, while server mode exits after about 10 minutes offline.

What should I check first when Codex mobile says "Waiting for desktop"?

Same account and workspace, MFA turned on, and a proxy or firewall that lets the host reach chatgpt.com. Then generate a new QR code and pair again. If the desktop app shows no error, the local log often contains the real one.

Do I need to scan the QR code again after BotBus loses connection?

No. After a network drop or a reboot, BotBus reconnects with the existing pairing. You only pair again after unpairing on the computer or removing that phone from it.

Can BotBus keep managing agents with the lid closed?

No. A closed lid puts the Mac to sleep by default, and BotBus stops along with the agents. Your phone shows the task list from before the computer went offline.