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.

When a session goes, the leftover bits Claude Code scatters around your home dir go with it: file history, env, todos, the lot. Anything still hanging around from sessions Claude already pruned itself gets swept up too, and .claude.json entries pointing to folders you've deleted get tidied away.

Live sessions and their data are never touched.

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, paste cache, cache, old shell snapshots)
-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.

Each session also litters ~/.claude with file-history/<sid>/, session-env/<sid>/, tasks/<sid>/, and todos/<sid>*.json. Those go when the session does, plus any that were already orphaned by the time claudeclean shows up. To avoid yanking a live session out from under itself, it reads ~/.claude/sessions/<pid>.json and confirms the pid is alive and still a claude process before treating anything as in use. .claude.json entries for folders you've deleted get pruned too.

With -a, it also sweeps debug/, paste-cache/, cache/, and shell-snapshots/ older than an hour.

License

MIT.