[FEATURE] Built-in Session Manager (claude sessions) — Consolidates 14+ Orphan/Process Issues

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code has no built-in way to manage running sessions from outside the session itself. This blind spot creates a cascading set of problems that are among the most-reported issues in this repo:

Orphaned processes eating RAM:

• #19045 — 20+ orphaned subagents after 1 hour, ~400MB each (~8GB total)
• #20369 — 30GB leaked from orphaned subagents after terminal close
• #18405 — Orphaned processes crashing the computer
• #22554 — Dozens of undead subagent processes on macOS causing system crash
• #6594 — Subagent termination bug
• #1935 — MCP servers not terminated on exit

No session visibility without entering a session:

• #16901 — No way to list sessions without --resume, no way to delete sessions
• #23692 — Forked sessions invisible in /resume list
• #28039 — 68 out of 87 session files orphaned and unindexed
• #22238 — Startup freeze with large session history (~468 sessions)

Sessions that can't be killed gracefully:

• #25442 — Process deadlock requiring SIGKILL
• #7455 — Freezing at session resume after Ctrl+C
• #30655 — Orphaned VM process blocking all resume attempts
• #10078 — Git zombie processes hanging sessions
• #8382 — 26GB memory allocation, frozen startup, requires kill -9

The common thread: users discover runaway Claude Code processes consuming gigabytes of RAM, but have no tool to see what's running, which sessions spawned what, or how to clean up — they end up doing ps aux | grep claude | awk '{print $2}' | xargs kill -9 and hoping for the best.

Proposed Solution

A built-in claude sessions subcommand that provides process-level session management. I've built a working prototype (claude-sessions, ~200 lines of Python) that demonstrates the core functionality.

1. List running sessions

$ claude sessions --list

    #      PID  TTY           Elapsed    Memory  Command
  ────────────────────────────────────────────────────────────
    1    28441  pts/3        02:15:33      412M  claude
    2    29102  pts/5           45:22      385M  claude --resume abc123
    3    30211  ?             1:22:05      401M  claude --resume def456  (subagent)
    4    30214  ?             1:22:03      398M  claude --resume ghi789  (subagent)

  Total: 4 session(s), 1.6G memory

Key insight: session #3 and #4 have no TTY (?) — they're orphaned subagents. This is immediately visible.

2. Kill sessions by number or PID

$ claude sessions --kill 3           # Kill by list number
  Sending SIGTERM to PID 30211 (claude --resume def456)
  Done.

$ claude sessions --kill 30214       # Kill by PID
  Sending SIGTERM to PID 30214 (claude --resume ghi789)
  Done.

$ claude sessions --kill 2 --force   # SIGKILL for frozen sessions
  Sending SIGKILL to PID 29102 (claude --resume abc123)
  Done.

3. Clean up all orphaned subagents

$ claude sessions --cleanup
  Found 12 orphaned subagent processes (no TTY, no parent session)
  Total memory: 4.8G

  Kill all orphans? [y/N]: y
  Killed 12 processes, freed ~4.8G memory.

4. Interactive mode (TUI)

$ claude sessions
============================================================
  Claude Code Session Manager
============================================================

    #      PID  TTY           Elapsed    Memory  Command
  ──────────────────────────────────────────────────────────
    1    28441  pts/3        02:15:33      412M  claude
    2    30211  ?             1:22:05      401M  claude --resume (orphan)

  Total: 2 session(s)

  Commands:
    <number>  Kill session by #
    c         Cleanup orphans
    r         Refresh
    q         Quit

  >

Why this should be built-in

1. Process management requires system-level access. A first-party tool can integrate with Claude Code's own process tracking, not just pattern-match ps output. It can know the parent-child relationship between sessions and subagents authoritatively.

1. The orphan problem is architectural. Claude Code spawns subagents as separate processes (claude --resume <id> --output-format stream-json). When the parent dies unexpectedly, these children become orphans. A built-in session manager can:

• Register subagents in a manifest on spawn
• Clean up on parent exit (process group / SIGCHLD handler)
• Provide --cleanup as a recovery mechanism when the automatic cleanup fails

1. Session lifecycle belongs in the core tool. Users shouldn't need to learn ps, grep, kill, and process group semantics to manage their AI coding assistant. claude sessions --list and claude sessions --kill are the obvious UX.

1. Large session history is already a problem. #22238 reports startup freeze with 468 sessions. A session manager that can list, inspect, and prune old sessions would prevent this.

1. Every workaround is fragile. The current community workarounds are:

``bash
pkill -f "claude.*--resume" # kills everything blindly
ps aux | grep claude | awk ... # manual and error-prone
kill -9 $(pgrep -f claude) # nuclear option
``
These can kill the wrong processes, miss orphans, or leave zombie children. A purpose-built tool eliminates this.

Implementation approach

Minimum viable version (what the prototype does):

• ps-based process discovery, pattern matching claude in args
• Filter out self (claude-sessions, claude-usage, grep)
• Show PID, TTY, elapsed time, RSS memory, command
• Kill by list index or PID, with SIGTERM/SIGKILL option
• Interactive TUI with refresh loop

Enhanced version (what built-in can do better):

• Read Claude Code's own process manifest (if one exists) instead of parsing ps
• Map subagent PIDs to parent session IDs
• Show session metadata: project path, token count, last activity
• --cleanup mode: automatically identify and kill orphaned subagents (no TTY, no live parent)
• --prune mode: delete old session files beyond a configurable retention period
• Integration with /resume: show memory/process info alongside session history
• Health check: detect frozen sessions (high CPU, no recent transcript writes)

Alternative Solutions

• Process groups (preventive): Spawn subagents in the same process group as parent, so they die together. This fixes the orphan problem but doesn't help with frozen sessions, session listing, or cleanup of existing orphans.
• systemd integration: Scope sessions under systemd user slices. Too heavy, not portable, doesn't work on macOS.
• /sessions slash command inside Claude: Can only manage the current session. Can't see or kill other sessions from within one session.

Priority

High — Orphaned subagent processes are a top-5 reported bug category, and the lack of session management tools forces users into fragile shell workarounds.

Feature Category

CLI commands and flags

Use Case Example

After a crash:
"Claude Code crashed during a big refactor. I have no idea how many subagent processes are still running. claude sessions --list shows 8 orphaned subagents using 3.2GB. claude sessions --cleanup kills them all."

Managing parallel sessions:
"I'm running Claude in 3 terminals on different projects. One session froze. claude sessions --list shows me which one, and claude sessions --kill 2 terminates just that session without touching the others."

Routine maintenance:
"I've been using Claude Code for weeks and my ~/.claude/projects/ has 200+ session files. claude sessions --prune --older-than 30d cleans up old transcripts and prevents the startup freeze reported in #22238."

Additional Context

Working prototype: ~200 lines of Python, zero dependencies beyond stdlib. Works on Linux today. The core logic (process discovery, kill, interactive TUI) is straightforward — the real value of making this first-party is integrating it with Claude Code's process lifecycle so orphans are prevented, not just cleaned up after the fact.

Related issues this would help resolve or mitigate:
#19045 #20369 #18405 #22554 #6594 #1935 #16901 #23692 #22238 #25442 #7455 #30655 #10078 #8382