Claude Code Remote Disconnection Troubleshooting: Symptoms, Criteria, and Solutions for Six Types of Disconnections

Running Claude Code remotely, the most frustrating thing isn't being unable to connect, but being connected and then disconnecting, with a different reason each time.

The word "disconnection" actually covers six completely different kinds of failures. Their symptoms each have distinct characteristics, and their fixes are unrelated to each other — treating a long-lived connection failure caused by network switching as machine sleep won't help even if you disable hibernation; waiting out a half-open connection as if it were poor network will not make it heal itself by dawn.

This article reverse-engineers the cause based on what you actually see: for each type of disconnection we give symptoms, how to confirm it, and the corresponding solution. If you want to jump straight into action, skip to the troubleshooting checklist in the last section.

This article only covers disconnection troubleshooting. For setting up remote access, see Claude Code Remote Access: Control Sessions Anywhere Even with Your Local Machine Off; for using it on mobile, see Phone + Claude Code: View Sessions and Approve Tools on iOS Anytime.

Match Your Symptoms First: Which One Are You Seeing

A remote connection has two segments: the dev machine running Claude Code ←→ the viewing device in your hand. A problem on either segment shows up as "disconnected", but the symptoms differ:

What you see	Most likely cause	Jump to
The session suddenly freezes; after reconnecting, progress is still stuck at that moment	Dev machine sleep / locked screen	§1
Disconnects the moment you enter an elevator, switch to 4G, or change WiFi	Long-lived connection killed	§2
The remote drops immediately when you close the local terminal or put the local machine to sleep	Hard constraint of screen-mirroring-style solutions	§3
Shows online, but messages vanish into the void with no error	Half-open connection	§4
Can reconnect, but you end up with an empty session / messages from during the outage are gone	Reconnect didn't reattach to the original session	§5
Reconnecting hours later, the session is gone	Process was reaped, and no cold recovery	§6

The easiest to misdiagnose is the fourth one: it reports no error. The connection status is green, messages go out, but there is never a response — harder to track down than a hard disconnect, because every indicator tells you "everything is fine".

1. Dev Machine Sleep / Lock Screen / Lid Closed

Symptoms: The session completely freezes at some moment. After reconnecting, progress is still at the moment of disconnection, not a step further.

Why: Many people assume "my dev machine is always on", but system hibernation, sleep on lid close, and scheduled lock screens will suspend or directly kill the Claude Code process. What the viewing end sees is "suddenly stopped".

How to confirm: Go back to the dev machine and check whether that process is still alive and whether the system log has any hibernation records. If the process is still there but its timestamps are frozen at the disconnection time, this is almost certainly it.

Solution: Set the dev machine's power plan to "never sleep / no sleep on lid close". This is the only cure — no remote solution can save a machine that has already gone to sleep.

2. Long-Lived Connection Killed by Network Switching

Symptoms: The disconnection happens at a very specific moment — entering an elevator, WiFi switching to 4G, or your home broadband re-dialing in the middle of the night.

Why: Remote real-time sync relies on a long-lived connection (WebSocket / SSH). As soon as the IP changes, that connection dies on the spot, with no room for negotiation.

How to confirm: If the disconnection time matches your network switch time, this is it.

Solution: This type cannot be avoided; you can only cushion it with automatic reconnect + backoff (1s→2s→5s…, to avoid hammering the moment it drops). Bare SSH doesn't have this capability — if it drops, it's dropped, and you have to reconnect manually. This is a hard requirement when choosing a solution.

3. Screen-Mirroring Solutions: The Local Machine Must Stay in the Foreground

Symptoms: The moment you close the local terminal or put the local machine to sleep, the phone side immediately drops. It's not a slow timeout — it's an immediate sync failure.

Why: Anthropic's official Remote Control mirrors the session currently running on your local machine to your phone/browser. Its precondition is that the Claude Code on the local machine stays in the foreground and the local machine stays online. Once the local machine drops, the remote end has no independent lifecycle to hold on to.

How to confirm: Close the local terminal window and see whether the remote drops in the same second. If it does, you're using a screen-mirroring solution.

Solution: Switch to an architecture with a resident daemon service on the dev machine — the side running the session becomes a background service that starts on boot and lives independently of your viewing device. Whether the viewing end is closed, changed, or disconnected, it keeps running on the dev machine as usual. This is the essential difference between "mirroring" and a "resident service"; it can't be achieved by tuning parameters.

4. Half-Open Connection: The Hardest to Detect

Symptoms: Shows online, sending messages gets no response, and there are no errors. It may be stuck for minutes, or until you manually reconnect.

Why: When the network silently goes down (NAT table entries timing out, intermediate devices losing state, or signals so weak that packets are dropped but the link stays up), both ends of a TCP connection may each think they are still connected, while data can no longer get through. Without a heartbeat, both sides keep up this illusion.

How to confirm: The connection status looks normal, but sent messages get neither delivery receipts nor errors; immediately after manually disconnecting and reconnecting everything works again — that's it.

Solution: Run heartbeat (keepalive ping) over the connection: if no response is received from the peer within the agreed time, determine this is a half-open connection and proactively disconnect and reconnect, rather than waiting foolishly. The criterion must be "no response received", not "no error" — a half-open connection never reports errors.

5. Reconnect Doesn't Reattach to the Original Session / Lost Messages

Symptoms: After a disconnect you can reconnect, but you either get an empty session or all messages sent by the other side during the outage are gone.

Why: Reconnecting only creates a new connection without subscribing it back to the original session; messages during the outage are also not cached for you.

How to confirm: After reconnecting, the session ID changed, or history only starts from the moment of reconnection.

Solution: Choose a solution that can automatically resubscribe to the original session after reconnecting and replay the history from during the outage. If it can only reconnect but not reattach, the reconnect is pointless.

6. Session Process Reaped, Without Cold Recovery

Symptoms: Short disconnects and reconnects all work fine, but after coming back a few hours later, the session is gone.

Why: Long-idle session processes may be reaped, and the daemon process itself may have restarted (upgrade, crash restart). The session state in memory disappears along with it.

How to confirm: It only reproduces with long disconnections, not short ones.

Solution: You need cold recovery — session state is persisted to disk, and the context can be restored from disk even if the process is gone. Ideally, you send a message and it automatically resumes, seamlessly without your noticing.

Troubleshooting Checklist (Works with Any Solution)

Go through it in order; each step can be independently verified or ruled out:

1. Did the machine running the session sleep / lock? → Disable automatic sleep and lid-close sleep. (§1)
2. Does the disconnection time coincide with your network switch? → You need a solution with automatic reconnect + backoff; don't rely on bare SSH. (§2)
3. Does the remote drop immediately when you close the local terminal? → That's the hard constraint of screen-mirroring solutions; switch to a resident daemon architecture. (§3)
4. Stuck on "shows online but sending messages gets no response"? → That's a half-open connection; only heartbeat detection can rescue it automatically. (§4)
5. After reconnecting the session is empty / messages are missing? → You need "reattach to original session + history replay". (§5)
6. Do you only lose sessions after long disconnections → You need disk persistence + cold recovery. (§6)

Putting It Into Concrete Solutions

Of the six points above, only #1 is a setting issue on your own machine; the other five are all determined by architecture — locked in when you chose the solution, and impossible to fix by tuning parameters after a problem appears.

A remote solution that doesn't drop connections needs all of the following: a resident daemon process on the dev machine (covering the remaining §1 risk and §3), automatic reconnect + backoff (§2), heartbeat detection (§4), reconnect reattaching to the original session + history replay (§5), and disk-persisted cold recovery (§6).

The PandaNpc + pandapaw stack was designed against these six points one by one: pandapaw registers itself on the dev machine as a resident daemon process that starts on boot (not a terminal window you have to keep open manually — if it crashes, it gets automatically restarted); the viewing end automatically reconnects on disconnection with backoff; heartbeat runs over the connection, and if no response is received it judges the connection half-open and proactively reconnects; after reconnecting, it automatically resubscribes to the original session and replays the history from during the outage; and even if the session process is reaped, sending a message cold-recovers the session from disk and continues.

For specifics on installation and connection, see Claude Code Remote Access; for session viewing and tool approval on mobile, see Phone + Claude Code.

A Side Pitfall: Don't Trip into Billing When Running Remotely

When troubleshooting disconnections, it's easy to switch to claude -p (headless mode), but starting June 15, 2026, Anthropic adjusted its billing — headless no longer uses subscription quota; instead, it draws from a small monthly SDK credit, and once that's used up, it's billed via the API. Heavy usage can easily blow through it. Interactive mode (claude REPL) still uses subscription quota. When switching solutions to troubleshoot disconnections, be careful not to accidentally switch your billing mode too.