claude-rc-keep: keep Remote Control sessions online

The problem

Claude Code Remote Control lets you continue a session that runs on a server from claude.ai/code or the Claude mobile app. When the server reboots or the session process is killed, the web session shows "Can't reach . It may be asleep or offline." and stays that way. claude remote-control comes back as a systemd service, but it does not reliably re-adopt the sessions that were running before.

All of these issues are open (reaction counts as of 2026-10-21):

anthropics/claude-code#30447, "claude remote-control --headless, daemonizable remote control without TTY dependency", 48 reactions.
anthropics/claude-code#33041, "Remote Control disconnects frequently", 30 reactions.
#98310 (3), #98504 (2), #101190 (2), #91592 (1) and #94049 (0) describe related cases of sessions that are lost or not reattached.

How it works

Claude Code writes ~/.claude/sessions/<pid>.json for every running session, with the local session ID, the folder and, when Remote Control is on, the web session ID (bridgeSessionId). The file is deleted when the process ends. claude-rc-keep runs every minute from a systemd user timer and copies these entries into its own registry under ~/.local/state/claude-rc-keep/. A recorded session that is no longer running is restarted as claude --resume <id> --remote-control in a detached tmux, in its original folder. An interactive session reattaches to the same web session, so the open tab on the phone or in the browser reconnects with the full conversation.

Sessions spawned by the claude remote-control server are handled differently. After a restart the server sometimes re-adopts an old web session on its own, and its worker overwrites the local transcript with the copy from the server. The README records one case where the transcript went from 77 MB to 14 MB and everything before the last /compact was gone from the file. claude-rc-keep therefore restores a server session once with --fork-session: a copy with a new local ID and a new web URL, which leaves the original transcript alone. From then on the copy is an interactive session and keeps its URL.

A session without a new message for more than 3 days is stopped and forgotten. Its transcript stays, so claude --resume still works. CLAUDE_RC_KEEP_MAX_IDLE_DAYS changes the limit, and 0 turns it off. claude-rc-keep rm stops a session for good.

This is the output of claude-rc-keep ls for a registry with three example entries:

$ claude-rc-keep ls
4f1c09ab  running           10-21 16:42  ~/projects/app  https://claude.ai/code/session_01EXAMPLEA
9b72d4e0  stopped           10-21 16:42  ~/projects/app  https://claude.ai/code/session_01EXAMPLEB
c35e8a17  running (server)  10-21 16:42  ~/projects/app  https://claude.ai/code/session_01EXAMPLEC

Testing

The tests run against temporary configuration and state directories and use short-lived real processes as sessions. They check that dead PIDs are ignored and that a PID reused by another process is rejected by comparing the process start time in /proc. The restart logic is tested with an injected launcher: a missing session is started with the expected command and not again within a 300-second grace period, a server session is forked only once, and sessions with an empty transcript or a deleted folder are skipped. Further tests stop and forget an idle session after 3 days, keep it when the limit is 0, and ignore the entries Claude Code writes on restart when computing the last activity. One test starts real tmux windows and checks that restarting a session replaces its existing window.

CI runs the tests on Python 3.10 to 3.13, runs ruff, and runs tick and ls against an empty profile. The README states that the tool was tested with Claude Code 2.1.306.

Limitations

It needs Linux with systemd user services and tmux.
The session files are undocumented and may change with any Claude Code release.
Each restarted session is a full Claude Code process of about 270 MB of memory.
A restored server session gets a new web URL. The old tab stays offline, or shows the server's copy if the server re-adopted it.
A session ended with /exit in its tmux window is restarted within a minute. claude-rc-keep rm is the way to stop one.
A session that is interrupted in the middle of a task is restored, but it continues only after a new message.

The code and installation instructions are at github.com/Jwrede/claude-rc-keep.