[FEATURE] Add session deletion and file cleanup functionality

[dukang1996]

Preflight Checklist

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

Problem Statement

Currently, Claude Code has no way to delete conversations:

1. VS Code extension: Deleting a conversation in the plugin UI does not remove the corresponding .jsonl files in ~/.claude/projects/<hash>/. The files keep accumulating and waste disk space.

2. Terminal version: There is no command like claude conversation delete <id> to delete conversations at all.

3. No user-friendly session management: Session files are stored as UUIDs (e.g., 3aec4d13-4203-4764-88e0-22857f54de7a.jsonl), making it impossible for users to identify which file corresponds to which conversation without manually parsing the JSON content.

Proposed Solution

Short term:

• When a user deletes a conversation in the plugin or terminal, automatically clean up the associated .jsonl files and related directories at the same time.
• Add a claude conversations list command to show all sessions with human-readable info (e.g., first message preview, timestamp, size).
• Add a claude conversation delete <id> command for terminal users.

Long term (nice to have):

• Provide a session management UI in the VS Code extension showing conversation history with previews.
• Add ability to rename sessions to something meaningful.

Why this matters

• Disk space: Over months of regular use, the ~/.claude/projects/ directory can grow to several GB with old session files that serve no purpose once a conversation is deleted.
• User trust: Users expect that "deleting" something actually removes it, not just hides it from the UI.
• Usability: UUIDs are not human-readable, making manual cleanup impossible for users who want to reclaim disk space.

Environment

• Claude Code version: 2.1.78
• OS: Windows 11 (also applies to macOS/Linux)
• Installation type: VS Code extension + npm global installation

---

Thank you for considering this feature!

Alternative Solutions

No response

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

No response

Additional Context

No response

[dr5hn]

Built something for this. CCM has a ccm clean command with 9 cleanup targets - debug logs, telemetry, todos, cache, history, tmp files, orphaned processes, and a clean all option.

It also has ccm session archive --older-than 30d if you want to compress old sessions instead of deleting them. You can restore later with ccm session restore.

The ccm doctor command runs 13 health checks and flags things like log bloat, orphaned sessions, and tmp files that have piled up.

https://github.com/dr5hn/ccm

[AndyHaack]

Confirming this behavior on v2.1.108 / Windows 11 / VS Code extension.

The delete button in the VS Code sidebar calls deleteSession() which only calls hideSession() — adding the session ID to a hiddenSessionIds array in globalState. From the extension source:

async deleteSession(K) {
    return await this.settings.hideSession(K), {type: "delete_session_response"};
}

Nothing is deleted. The .jsonl file, sessions-index.json entry, and UUID subdirectory (containing subagent data) all remain on disk indefinitely.

Concrete numbers from my instance:

• 193 total sessions, 364 MB on disk
• 29 "deleted" (hidden) sessions still consuming 10 MB
• 46 entries in hiddenSessionIds (17 of which reference sessions whose files were manually removed — the list itself is never cleaned up either)

The hiddenSessionIds array in global state also grows unboundedly since entries are never removed, even when the referenced session file no longer exists.

What users expect: a Trash / recycle bin workflow

The current behavior (hide-only) is actually a reasonable first step — but it should be surfaced as a Trash rather than presented as "Delete". The ideal flow:

1. "Delete" moves to Trash — session disappears from the main sidebar list (current behavior), but the files stay on disk (also current behavior). The difference: this is now an intentional soft-delete, not a silent lie.
2. Trash view — a "Trash" or "Recently Deleted" section in the sidebar (or a claude sessions trash CLI command) where users can browse deleted sessions with their titles and dates.
3. Restore — individual sessions can be restored back to the main list (remove from hiddenSessionIds).
4. Permanent delete — individual sessions or "Empty Trash" to actually remove .jsonl files, UUID subdirectories, sessions-index.json entries, and the hiddenSessionIds references. This is the only action that reclaims disk space.
5. Auto-purge (optional) — automatically permanently delete trashed sessions after N days (e.g. 30), similar to OS trash behavior.

This gives users the best of both worlds: a clean sidebar without clutter, but with the safety net of being able to recover sessions they may need for future reference — and the ability to reclaim disk space when they choose to.