Skip to content

Claude Code Remote Control

Anthropic released Remote Control for Claude Code in February 2026. It bridges a locally-running Claude Code CLI process with Claude Mobile (iOS/Android) and claude.ai/code in any browser. The local session stays running on the host with full filesystem, environment, and MCP access; the phone or browser is just a thin front-end that attaches to it.

This article covers the setup pattern used at MajorsHouse — running Remote Control on an always-on host inside a tmux session over Tailscale SSH so the mobile connection survives client disconnects.

How Remote Control Works

  • All traffic flows through Anthropic's API over outbound HTTPS. No inbound ports on the host, no port forwarding, no reverse proxy.
  • The mobile/web client attaches to the existing session — same transcript, same context, same MCP servers, same working directory.
  • Terminal and mobile can be active at the same time; input is interchangeable and both views stay in sync.
  • Only one remote client per session is supported.
  • The session ends when the local claude process stops.
  • Must be started with claude remote-control from the beginning — a plain claude session already in flight cannot be retrofitted.
  • Requires Claude Pro or Max.

Why MajorMac Hosts the Session

Moved from MajorRig to MajorMac 2026-08-18. The vault is Obsidian-synced across MajorM5Pro, MajorMac, and MajorRig — that part hasn't changed. What changed is which of those three is the best always-on host.

MajorRig was originally the de facto primary because majorlab/majorhome (the native Linux always-on servers) have no vault sync at all — adding either would mean another Obsidian Sync device slot, an SMB/NFS mount, or git-only access to the MajorDocs subset, none of which were ever built. But MajorRig has its own reliability cost: it's WSL2, and Windows Update reboots kill the claude process (see Constraints below) — the mobile session drops and the transcript is lost every time.

MajorMac was overlooked because it used to sleep when idle, but that changed 2026-08-02: pmset -c sleep 0 disabled idle sleep on AC power, and it's held clean for weeks (zero sleep events across 6+ days at last check) — it's now functionally always-on without WSL2's reboot exposure. It already had vault sync as one of the three Obsidian Sync devices, so there was no gap to close, unlike majorlab/majorhome. It also doesn't host anything as high-value as majorlab's Vaultwarden/Forgejo, so a compromised session there has less blast radius. Full comparison (including why majorlab specifically was considered and rejected — three unexplained hard lockups in seven months, root cause unpinned) is in Personal-Tasks 2026-08-18.

WSL2's /mnt/c I/O being slow for heavy workloads no longer applies once macOS is the host — noted here only because it was the historical reason MajorRig's setup called out I/O caveats.

Setup on MajorMac

1. Enable Remote Control by default

Inside any Claude Code session:

/config

Toggle "Enable Remote Control for all sessions". This means future claude invocations automatically expose a Remote Control endpoint — no need to remember the flag.

2. Install the mobile app

Inside Claude Code:

/mobile

A QR code appears for iOS and Android download links.

3. Start a persistent session via Tailscale SSH + tmux

tmux is not installed by default on macOS — brew install tmux first.

From any fleet machine:

ssh majorlinux@100.74.124.81   # MajorMac, Tailscale only
tmux new -s claude "claude --remote-control"

The subcommand form claude remote-control (no dashes) does not exist and fails silently — tmux new -d will report the session as created, but the pane's command exits immediately and the whole tmux server dies with it (tmux ls then reports "no server running"). The correct invocation is the flag form, claude --remote-control (confirmed against claude --help 2026-08-18). This cost real time to diagnose the first time — check tmux ls right after starting, not just the tmux new exit code, to catch a silently-dead server.

Detach with Ctrl+b d. The claude process survives SSH disconnect because it's owned by the tmux server, not the SSH session.

To reattach from the host later:

ssh majorlinux@100.74.124.81
tmux attach -t claude

4. First-run trust prompt

The very first launch in a given working directory shows an interactive "Is this a project you created or one you trust?" prompt before Remote Control activates. It has to be answered (1 to trust) before the session reaches the /remote-control is active state — a tmux new -d alone will leave the pane parked on this prompt, looking alive in tmux ls but not actually serving Remote Control yet. Check tmux capture-pane -t claude -p after starting to confirm it's actually past this screen, not just that the session exists.

macOS Keychain gotcha (found 2026-08-18)

If Claude Code's OAuth session has expired, running claude login or any claude command over SSH can fail with Failed to authenticate: OAuth session expired and could not be refreshed — even while other claude processes launched from the GUI (Claude Desktop, or a Terminal.app session logged into the console) are running fine on the same machine at the same time. The credential appears to be tied to the macOS Keychain, which a non-interactive SSH session can't unlock the same way a console-logged-in process can. Fix: run claude login locally at the machine's own keyboard/screen (or a Screen Sharing session), not over SSH. Once logged in that way, subsequent SSH-invoked claude commands authenticate fine — the credential itself is shared, only the initial interactive login needs local/console access.

4. Connect from the phone

Open Claude Mobile → select the session from the list, or scan the QR code the host prints on start. The app connects over outbound HTTPS through Anthropic; no Tailscale required on the phone.

Alternatives

  • SSH + tmux directly from a mobile terminal app (Blink Shell, Termius) — works without Pro/Max, survives client drops, full shell access. UX on a phone screen is rough; no native paste/share affordances.
  • JessyTsui/Claude-Code-Remote (community) — routes Claude Code task output via email/Discord/Telegram. Not interactive; useful for notifications.

Constraints and Gotchas

  • Process death kills the session. If the claude process exits (crash, tmux kill-session, host reboot), the mobile connection drops and the transcript is lost. For true resilience, pair with a systemd user service that auto-restarts.
  • One remote per session. Phone and laptop browser cannot both attach at the same time.
  • Windows Update reboots on WSL2 — the reason this moved off MajorRig 2026-08-18. MajorRig's uptime was gated by the Windows host, and every reboot killed the session per the point above. If MajorRig is ever used for this again, a scheduled-restart-free maintenance window is worth configuring first.
  • Session must start with Remote Control. Restart claude if you realize mid-session you want phone access (unless /config toggle is already set).

Known Issues

iOS/iPadOS app 1.260618.0 — hard-crash on opening a Remote Control session

Status: Open upstream bug, fix pending in a future app build. (First hit 2026-06-23.)

The Claude mobile app build 1.260618.0 hard-crashes the instant you tap into a Remote Control (Code-tab) session. Observed at MajorsHouse on iPad Pro and iPhone 16 Pro simultaneously.

Distinguishing characteristics — this is an app-side bug, not a host/session problem:

  • Crashes on a brand-new session, so it is not transcript or tool-output size related.
  • The same session opens and works fine in a mobile browser (Safari/Chrome) — the host bridge is healthy.
  • Clean reinstall + re-login does not help. Don't waste time on it.
  • Root cause (per upstream reports) is a main-thread stack overflow in Swift KeyPath / SwiftUI metadata inside the app — nothing fixable on the host.

Workaround: use a mobile browser (claude.ai/code) instead of the app until a newer build ships.

Upstream tracking (anthropics/claude-code): - #70144 — iPad, v1.260618.0, any Code-tab session crashes (highest-traction canonical issue) - #70165 — iPhone 16 Pro Max, 1.260618.0, Remote Control hard-crash - Related: #70262, #70288, #65926

To file/confirm a report, export the crash log on each device: Settings → Privacy & Security → Analytics & Improvements → Analytics Data → Claude-<date>-*.ips, then attach it to the relevant issue above.

See Also