anthropics / anthropics/claude-code
[FEATURE] Retention policy for the session list: auto-archive disconnected sessions instead of growing forever
- Ngôn ngữ chính
- Python
- Star
- 145k
- Fork
- 23.1k
- Chỉ số merge pull request
- Chỉ số pull request đang chờ
Mô tả
### 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-`, 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//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.
2. 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_` while `~/.claude/sessions/.json` stores
`session_` — **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.
2. **Client-side opt-in** for people who prefer it local: a `settings.json` key such as
`cleanupDisconnectedSessionsAfterDays`, applied by the CLI on startup.
3. **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.
Hướng dẫn đóng góp
Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này
Hướng nghiên cứu
Start by reviewing the session-list API endpoints and the CLI's settings.json handling; the issue does not identify implementation files or tests. Compare the server-side retention, client-side startup cleanup, and clean-exit options, then clarify which scope is accepted. Done means an agreed retention policy handles disconnected and never-used sessions without archiving live ones.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- macos
- Lĩnh vực
- api, cli, cloud
- Loại issue
- Tính năng
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức độ hoạt động
- Sôi nổi
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 32/100