[FEATURE] Retention policy for the session list: auto-archive disconnected sessions instead of growing forever

Feature request

Give the Claude Code session list a retention policy, so disconnected sessions get
archived automatically instead of accumulating until a human sweeps them by hand.

Why the current behaviour is not sustainable

Measured on one machine (macOS, Claude Code 2.1.266–2.1.270, Remote Control server up
permanently, Max plan) on 2026-09-13:

• 96 active sessions in the list. 12 were actually connected to a live process;

84 were dead rows.

• New sessions are produced at 34/48/89/123/92/131/45 per day over the previous week.

Every interactive claude in a terminal, and every session created through Remote
Control, registers a permanent row. (Headless claude -p runs do not — that part is
already right.)

• Six of the live processes were Remote-Control-hosted sessions 3 days old, still

resident, because nothing ever reaps them.

• The web UI renders at most 50 rows ("Show 20 more" stops there) while the API had

96, so 46 sessions were not reachable in the UI at all.

There is also a generator I could not attribute to anything on the machine: an empty
session appears roughly every 6–20 minutes, named localhost-<random-words>, with
created_at and last_event_at within one second of each other and no second event ever.
At those timestamps there was no claude process started, no socket in /tmp/cc-socks/,
and no transcript under ~/.claude/projects/ — so they are minted on the bridge/client
side, not locally. 33 of the 96 rows were these. Whatever creates them, they are pure
noise and should either never become a persisted row or be reaped immediately.

Net effect: a full manual cleanup is undone within a day.

What I had to build instead

A LaunchAgent that sweeps every 15 minutes:
https://github.com/victorrentea/victor-macos-addons/blob/main/cc-session-reap.sh

It needs nothing that Claude Code does not already have — it reads the CLI's own OAuth
token out of the login keychain and calls the same endpoints the CLI calls:
GET /v1/code/sessions?statuses=active (paging next_cursor) and
POST /v1/code/sessions/<id>/archive on api.anthropic.com. That is the point of filing
this: the server side already has everything needed. The only missing piece is a policy.

Two things it has to do that the product should not force on anyone:

1. It refuses to refresh the OAuth token, because the refresh token may be rotated

server-side and burning it would log Claude Code out. So a sweep is skipped whenever
the ~1h access token happens to be expired.

1. It cannot trust connection_status alone to protect live sessions, so it also matches

each id against the bridgeSessionId of every live local process. That comparison is
a trap: the API returns cse_<suffix> while ~/.claude/sessions/<pid>.json stores
session_<suffix> — same session, different prefix, so the obvious literal
comparison silently matches nothing and protects no one.

Proposal

1. Server-side retention, configurable in the Code settings: "archive disconnected

sessions after N days" (with a sane default), and "do not keep sessions that were
created and never used" for the never-used case above.

1. Client-side opt-in for people who prefer it local: a settings.json key such as

cleanupDisconnectedSessionsAfterDays, applied by the CLI on startup.

1. On clean exit, archive the session the process owned — or at least offer

remoteControlArchiveOnExit: true, as suggested in #87877.

Any one of these removes the need for the script.

Related

• #87877 — same need, scoped to Remote Control "dispatcher" sessions; this issue is the

general case plus the numbers and the never-used-session generator.

• #74682 — auto-archive for scheduled-task run sessions.
• #93870 — filter the list by connection state (so a human can at least see what is dead).
• #93979 — multi-select + bulk archive (so a human can clean up without scripting).
• #91239 — the list does not show which machine a session runs on.

Environment

Claude Code 2.1.266–2.1.270 (native), macOS 15 / darwin 24.6.0, Remote Control server
running permanently, Android mobile app + claude.ai/code.