claudeclean

Session hygiene for Claude Code.

Why

Claude Code has no way to manage your sessions. You can't list them, you can't delete them, you can't even see how much space they're eating. The /resume picker shows you a pile of unnamed conversations and that's it. No cleanup, no pruning, no nothing.

Meanwhile ~/.claude/projects/ quietly balloons to multiple gigabytes. Debug logs, file history, paste cache, shell snapshots, session transcripts that will never be opened again. It just grows. There's a 30-day auto-delete for old logs, but that's about as useful as a seatbelt in a parked car when you've got a dozen multi-gig sessions from this week alone.

People have been asking for this for a while (#13514, #15576, #16901, #25304).

What it does

Scans your ~/.claude directory, figures out which sessions are named (via /rename) and which are throwaway, then prunes accordingly. Unnamed sessions get deleted. Named sessions are kept up to a configurable max per project, newest first. History entries for deleted sessions are cleaned up too.

That's it. No daemon, no config file, no database. One bash script, one jq dependency.

Install

curl -fsSL https://raw.githubusercontent.com/procoperr/claudeclean/main/install.sh | sh

Or clone and install locally:

git clone https://github.com/procoperr/claudeclean.git
cd claudeclean
make install

Requires jq. If you don't have it: brew install jq or apt install jq.

Uninstall

curl -fsSL https://raw.githubusercontent.com/procoperr/claudeclean/main/install.sh | sh -s -- --uninstall

Or make uninstall if you cloned.

Use

claudeclean              # clean with defaults
claudeclean ls           # list all sessions
claudeclean rm 2acf51    # delete by ID prefix
claudeclean pick         # interactive picker
claudeclean -d           # dry run (trust issues)

Flags:

-n N   max named sessions per project (default: 5)
-d     dry run
-k     keep unnamed sessions
-a     also clean ephemeral data (debug logs, cache, file history, etc.)
-v     verbose

Auto-clean

Install a daily scheduled job that runs at 3 AM. Uses launchd on macOS, systemd on Linux.

claudeclean cron install
claudeclean cron remove    # undo

How it works

Sessions live in ~/.claude/projects/<encoded-path>/*.jsonl. claudeclean reads ~/.claude/history.jsonl to figure out which sessions have been /renamed (those are "named") and which haven't (those are "unnamed"). Unnamed sessions get deleted. Named sessions are sorted by last activity and capped at -n per project. Orphaned history entries are pruned to match.

With -a, it also sweeps out debug/, paste-cache/, todos/, file-history/, cache/, and shell-snapshots/.

License

MIT.