feat: add session-manager plugin for listing, deleting, and cleaning up sessions

plugins/README.md

@@ -25,6 +25,7 @@ Learn more in the [official plugins documentation](https://docs.claude.com/en/do
 | [pr-review-toolkit](./pr-review-toolkit/) | Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification | **Command:** `/pr-review-toolkit:review-pr` - Run with optional review aspects (comments, tests, errors, types, code, simplify, all)<br>**Agents:** `comment-analyzer`, `pr-test-analyzer`, `silent-failure-hunter`, `type-design-analyzer`, `code-reviewer`, `code-simplifier` |
 | [ralph-wiggum](./ralph-wiggum/) | Interactive self-referential AI loops for iterative development. Claude works on the same task repeatedly until completion | **Commands:** `/ralph-loop`, `/cancel-ralph` - Start/stop autonomous iteration loops<br>**Hook:** Stop - Intercepts exit attempts to continue iteration |
 | [security-guidance](./security-guidance/) | Security reminder hook that warns about potential security issues when editing files | **Hook:** PreToolUse - Monitors 9 security patterns including command injection, XSS, eval usage, dangerous HTML, pickle deserialization, and os.system calls |
+| [session-manager](./session-manager/) | List, delete, and bulk-clean sessions across all projects without leaving the CLI | **Commands:** `/delete` - Remove sessions interactively or by ID, `/list` - Cross-project session overview, `/cleanup` - Bulk-remove old or tiny sessions with filters |
 
 ## Installation
 

plugins/session-manager/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "session-manager",
+  "description": "List, delete, and clean up Claude Code sessions across all projects without leaving the CLI",
+  "version": "1.0.0",
+  "author": {
+    "name": "Alexander Kropiunig"
+  }
+}

plugins/session-manager/README.md

@@ -0,0 +1,104 @@
+# Session Manager
+
+List, delete, and bulk-clean Claude Code sessions without leaving the CLI.
+
+Claude Code sessions accumulate quickly — every `claude` invocation creates a new `.jsonl` file under `~/.claude/projects/`. Over time this grows into hundreds of orphaned sessions with no built-in way to review or remove them. The `/resume` picker shows sessions for the current project, but there is no cross-project overview, no deletion, and no cleanup tooling.
+
+This plugin fills that gap with three commands that cover the full session lifecycle.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/session-manager:delete` | Delete a specific session by name, ID prefix, or interactive selection |
+| `/session-manager:list` | List all sessions across projects with timestamps, sizes, and previews |
+| `/session-manager:cleanup` | Bulk-remove old or tiny sessions with age/size filters |
+
+### `/session-manager:delete [session-name-or-id]`
+
+Delete a single session. Without arguments, shows a numbered list of sessions in the current project to pick from. With an argument, matches against session names or UUID prefixes.
+
+Always asks for confirmation before deleting.
+
+```
+> /session-manager:delete
+Sessions in myproject (5 sessions):
+  1  [2026-02-15]  "Fix auth bug in login flow..."          abc12345
+  2  [2026-02-14]  "Add dark mode support..."               def67890
+  3  [2026-02-13]  "Refactor database queries..."           ghi24680
+
+Which session to delete? 2
+
+Delete session "Add dark mode support..." (def67890)?
+> y
+Deleted session def67890.
+```
+
+### `/session-manager:list [project-filter]`
+
+Cross-project session overview. Shows every session grouped by project with modification date, file size, and a preview of the first prompt. Optionally filter by project name.
+
+```
+> /session-manager:list
+
+myproject (3 sessions)
+  #  Date        Size    First prompt                               ID
+  1  2026-02-15  245 KB  Fix the auth bug in login flow...          abc12345
+  2  2026-02-14   89 KB  Add dark mode support...                   def67890
+  3  2026-02-10   12 KB  Quick question about generics...           ghi24680
+
+api-service (1 session)
+  #  Date        Size    First prompt                               ID
+  1  2026-02-12  530 KB  Implement payment processing pipeline...   jkl13579
+
+Total: 4 sessions across 2 projects (876 KB)
+```
+
+### `/session-manager:cleanup [options]`
+
+Bulk cleanup with filters. Supports `--older-than`, `--smaller-than`, and `--dry-run`.
+
+```
+> /session-manager:cleanup --older-than=30d --dry-run
+
+Sessions matching criteria (older than 30 days):
+  - [2025-12-01]   3 KB  "Quick test of the API..."       (abc12345)
+  - [2025-11-15]   1 KB  "Hello, can you help..."         (def67890)
+
+Dry run complete. 2 sessions (4 KB) would be deleted.
+
+> /session-manager:cleanup --older-than=30d
+
+[same preview]
+Delete these 2 sessions (4 KB)? This cannot be undone.
+> y
+Cleaned up 2 sessions (4 KB freed).
+```
+
+## Installation
+
+Install via the plugin marketplace or manually:
+
+```bash
+claude plugin install session-manager
+```
+
+Or clone into your plugins directory:
+
+```bash
+git clone https://github.com/anthropics/claude-code.git
+# Plugin is at plugins/session-manager/
+```
+
+## How It Works
+
+Sessions are stored as `.jsonl` files in `~/.claude/projects/<encoded-project-path>/`. Each file contains the full conversation history as newline-delimited JSON. Some sessions also have a companion directory (same UUID) containing tool results and subagent data.
+
+The plugin reads these files to extract metadata (timestamps, first prompt, file size) and uses standard filesystem operations to delete them when requested. All operations are local — no data leaves your machine.
+
+## Safety
+
+- **Confirmation required** — every delete operation requires explicit user approval
+- **No active session deletion** — cleanup skips the currently running session
+- **Dry-run mode** — preview what would be deleted before committing
+- **Companion data included** — deleting a session also removes its associated tool-result directory

plugins/session-manager/commands/cleanup.md

@@ -0,0 +1,104 @@
+---
+description: Bulk-remove old or tiny sessions across all projects
+allowed-tools: Bash(ls:*), Bash(head:*), Bash(wc:*), Bash(stat:*), Bash(du:*), Bash(cat:*), Bash(find:*), Bash(rm:*), Bash(rmdir:*), Bash(date:*)
+argument-hint: [--older-than=30d] [--smaller-than=5KB] [--dry-run]
+---
+
+<!--
+COMMAND: cleanup
+VERSION: 1.0.0
+
+PURPOSE:
+Bulk cleanup of stale sessions that clutter the session history.
+Targets sessions by age, size, or both. Always shows a preview
+before deleting anything.
+
+USAGE:
+  /cleanup                            Interactive: suggest sessions to clean up
+  /cleanup --older-than=30d           Target sessions older than 30 days
+  /cleanup --smaller-than=5KB         Target sessions under 5 KB (likely abandoned)
+  /cleanup --older-than=7d --dry-run  Preview what would be deleted without deleting
+
+ARGUMENTS:
+  --older-than=<duration>:  Target sessions not modified in this period (e.g., 7d, 2w, 1m)
+  --smaller-than=<size>:    Target sessions under this file size (e.g., 5KB, 1MB)
+  --dry-run:                Show what would be deleted without actually deleting
+-->
+
+# Cleanup Sessions
+
+You are helping the user bulk-clean their Claude Code session history.
+
+## Step 1: Parse arguments
+
+Read the user's arguments (`$ARGUMENTS`) and determine the cleanup criteria:
+
+- `--older-than=<duration>`: Convert to days. Supported units: `d` (days), `w` (weeks), `m` (months, 30 days each).
+- `--smaller-than=<size>`: Convert to bytes. Supported units: `KB`, `MB`.
+- `--dry-run`: If present, only preview — do not delete.
+
+If no arguments are provided, default to suggesting sessions older than 30 days or smaller than 5 KB.
+
+## Step 2: Scan all sessions
+
+Walk through every project in `~/.claude/projects/` and find session files matching the criteria:
+
+```bash
+find ~/.claude/projects/ -name "*.jsonl" -type f
+```
+
+For each file, check:
+- **Modification time** — compare against `--older-than` threshold
+- **File size** — compare against `--smaller-than` threshold
+
+Extract a preview (first user message) for each matching session.
+
+## Step 3: Present candidates
+
+Show the sessions that would be deleted, grouped by project:
+
+```
+Sessions matching cleanup criteria (older than 30 days):
+
+myproject
+  - [2025-12-01]   3 KB  "Quick test of the API..."             (abc12345)
+  - [2025-11-15]   1 KB  "Hello, can you help me with..."       (def67890)
+
+old-project
+  - [2025-10-20]  45 KB  "Implement caching layer..."           (ghi24680)
+
+3 sessions, 49 KB total
+```
+
+If `--dry-run` is set, stop here and report:
+```
+Dry run complete. 3 sessions (49 KB) would be deleted. Run without --dry-run to proceed.
+```
+
+## Step 4: Confirm and delete
+
+**CRITICAL: Always ask for confirmation before bulk deletion.**
+
+```
+Delete these 3 sessions (49 KB)? This cannot be undone.
+```
+
+Wait for explicit confirmation. Once confirmed, delete each session's JSONL file and companion directory:
+
+```bash
+rm <file>.jsonl
+rm -rf <file-without-extension>/
+```
+
+Report results:
+```
+Cleaned up 3 sessions (49 KB freed) across 2 projects.
+```
+
+## Important
+
+- **Never delete without showing the full list first and getting confirmation**
+- Skip the currently active session — never delete it during cleanup
+- Show a summary even if zero sessions match the criteria
+- Handle filesystem errors gracefully (permissions, missing files)
+- If all sessions in a project directory would be deleted, note this explicitly

plugins/session-manager/commands/delete.md

@@ -0,0 +1,97 @@
+---
+description: Delete a session by name, ID, or interactively from a list
+allowed-tools: Bash(ls:*), Bash(head:*), Bash(rm:*), Bash(wc:*), Bash(stat:*), Bash(cat:*), Bash(rmdir:*)
+argument-hint: [session-name-or-id]
+---
+
+<!--
+COMMAND: delete
+VERSION: 1.0.0
+
+PURPOSE:
+Permanently delete a Claude Code session and its associated data.
+Closes the gap in the session lifecycle: Create > Work > Resume > Clear > Delete.
+
+USAGE:
+  /delete              Show numbered list of sessions in current project, pick one to delete
+  /delete <name>       Delete session matching name (fuzzy match)
+  /delete <uuid>       Delete session matching ID prefix
+
+ARGUMENTS:
+  session-name-or-id: Optional. Session name or UUID prefix to target.
+                      If omitted, shows an interactive list.
+-->
+
+# Delete Session
+
+You are helping the user delete a Claude Code session. Follow these steps carefully.
+
+## Step 1: Locate sessions
+
+The Claude Code session storage root is `~/.claude/projects/`. Each subdirectory maps to a project path (with path separators replaced by `-`).
+
+Determine which project the user is currently in by looking at the current working directory. Encode the path to match the directory naming convention (e.g., `/Users/alice/myproject` becomes `C--Users-alice-myproject` on macOS/Linux, `C--Users-alice-Desktop` on Windows).
+
+List session files in the matching project directory:
+```bash
+ls -lt ~/.claude/projects/<project-dir>/*.jsonl 2>/dev/null
+```
+
+If the user provided an argument (`$ARGUMENTS`), filter to sessions matching that name or UUID prefix.
+
+## Step 2: Show session details
+
+For each candidate session file, extract a preview by reading the first user message:
+```bash
+head -20 <file> | grep '"type":"user"' | head -1
+```
+
+Parse the JSON to extract:
+- `timestamp` — when the session started
+- `message.content` — the first user prompt (truncate to 80 chars)
+- `sessionId` — the UUID
+
+Present a numbered list to the user:
+```
+Sessions in <project-name>:
+
+  1. [2026-02-15] "Fix the auth bug in login..."  (abc12345)
+  2. [2026-02-14] "Add dark mode support..."       (def67890)
+  3. [2026-02-13] "Refactor database queries..."   (ghi24680)
+```
+
+If only one session matches the argument, skip the list and go directly to Step 3.
+
+## Step 3: Confirm deletion
+
+**CRITICAL: Always ask the user to confirm before deleting.** Show the session preview and ask:
+
+```
+Delete session "Fix the auth bug in login..." (abc12345)?
+This will permanently remove the session file and any associated data.
+```
+
+Wait for explicit user confirmation. Do NOT proceed without it.
+
+## Step 4: Delete the session
+
+Once confirmed, delete:
+1. The session JSONL file: `~/.claude/projects/<project-dir>/<uuid>.jsonl`
+2. The companion data directory if it exists: `~/.claude/projects/<project-dir>/<uuid>/`
+
+```bash
+rm ~/.claude/projects/<project-dir>/<uuid>.jsonl
+rm -rf ~/.claude/projects/<project-dir>/<uuid>/
+```
+
+Report success:
+```
+Deleted session <uuid>.
+```
+
+## Important
+
+- **Never delete without confirmation** — session data is not recoverable
+- If no sessions are found, tell the user and suggest checking `~/.claude/projects/` manually
+- Handle edge cases: permission errors, missing files, empty project directories
+- If the user asks to delete the currently active session, warn them that this will remove the history of the current conversation