vault: session notes 2026-07-09

claude-code-remote-control-connection-behavior.md

@@ -0,0 +1,52 @@
+---
+type: reference
+subtype: api-integration
+title: Claude Code /remote-control connection behavior and keep-alive
+summary: Why Claude Code Remote Control sessions drop (host suspend, ~25-min server-side WebSocket limit, broken auto-reconnect) and how to keep or resume them.
+tags:
+  - type/reference
+  - tool/claude-code
+  - domain/devops
+scope: global
+last_updated: 2026-07-08
+date: 2026-07-08
+last_reviewed: 2026-07-08
+source: servers/desktop
+---
+
+# Claude Code /remote-control connection behavior
+
+How Remote Control (phone → local CLI session via claude.ai) stays connected, what kills it, and how to recover. Verified against docs + GitHub issues as of Claude Code ~v2.1.203 (2026-07).
+
+## Connection model
+
+- WebSocket to an Anthropic relay (`wss://api.anthropic.com/v1/session_ingress/ws/`); no inbound ports on the host.
+- Client sends keep-alive frames every ~5 min.
+
+## What kills the connection
+
+| Cause | Behavior |
+|---|---|
+| **Host suspend/sleep** | Most common killer. If the host is unreachable >~10 min the session times out and the process exits. Desktop power management counts only *local* input as activity — remote-driven sessions look idle. |
+| Server-side max lifetime | Server force-closes the WebSocket ~every 25 min (code 1006), regardless of keep-alives — GH issue #34868, open. |
+| Repeated drops | Auto-reconnect works once (~1s); after ~3 disconnects the session dies permanently with code 1002 — #31853, #34255, open. |
+| SIGHUP | Closing the terminal kills the process (tmux prevents this; tmux does NOT survive host suspend). |
+| Phone network handoff | WiFi↔cellular switch causes a pong timeout; usually reconnects unless it stacks with the above. |
+
+No `CLAUDE_REMOTE_CONTROL_*` env vars exist to tune reconnect/backoff as of v2.1.203.
+
+## Keeping it alive (Linux host)
+
+```bash
+systemd-inhibit --what=sleep:idle --why="Claude Code Remote Control" \
+  tmux new-session -s claude-remote 'claude'
+```
+- `systemd-inhibit` blocks idle suspend for the wrapped process's lifetime.
+- Or disable idle suspend outright (GNOME: `gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-type 'nothing'`).
+- Keep the phone app foregrounded; avoid network handoffs mid-session.
+
+## Recovery after a drop
+
+- Process still alive: run `/remote-control` again in the session — manual re-bridge works even when auto-reconnect has given up.
+- Process dead: `claude --continue` (or `claude --session-id <id>`) to resume the conversation, then `/remote-control` for a fresh link.
+- No built-in auto-restart after a permanent (1002) failure.

journal/2026-07-09.md

@@ -0,0 +1,11 @@
+---
+summary: Daily session log
+tags: [scope/global, type/log]
+---
+
+## Session — 2026-07-09T11:58:44Z
+
+**Project:** /home/jared/servers/desktop
+**Reason:** prompt_input_exit
+**Vault notes touched:**
+/home/jared/Documents/SecondBrain/claude-code-remote-control-connection-behavior.md