claude project purge: Full Project State Cleanup in One Command
Claude CodeClaude Code v2.1.126 introduces claude project purge [path], a new subcommand that deletes all Claude Code state associated with a project in a single operation — transcripts, tasks, file history, and the config entry. The command ships with --dry-run, -y/--yes, -i/--interactive, and --all flags, giving developers full control over how aggressively the cleanup runs. This fills a long-standing gap: before this command, clearing project state required manually editing files in ~/.claude/, an error-prone process that spawned third-party community workarounds like the claude-clean PyPI package.
Sources & Mentions
3 external resources covering this update
A Dedicated Command for Project State Cleanup
Claude Code has historically offered no native way to wipe the accumulated state it builds up for a project. Transcripts, task history, file modification records, and configuration entries persist indefinitely — useful when actively working on a project, but increasingly burdensome when a project is archived, handed off, or simply needs a clean slate.
Version 2.1.126 addresses this directly with claude project purge [path], a new CLI subcommand that removes all Claude Code state for a given project directory in one operation.
What Gets Deleted
Running claude project purge on a project path removes:
- Transcripts — the full conversation history Claude Code stored for that project
- Tasks — any scheduled or pending task records
- File history — the log of file reads and writes Claude Code tracked
- Config entry — the project's registration in Claude Code's project registry
This is a complete teardown. After purging, the project directory is treated as if Claude Code had never seen it before.
Flexible Control with Four Flags
The command ships with a thoughtful set of flags to cover different operational needs:
--dry-run— preview what would be deleted without actually removing anything, useful for auditing before committing-y/--yes— skip all confirmation prompts and purge immediately, designed for scripted environments and CI workflows-i/--interactive— step through each item to delete, giving granular control over what gets removed--all— purge state for every registered project at once, useful when resetting a development machine or clearing a fresh environment
When to Use It
Practical scenarios where claude project purge is the right tool:
- Archiving a completed project and reclaiming disk space from accumulated transcripts
- Troubleshooting a corrupted Claude Code state for a specific project without affecting other projects
- Handing off a project to another developer with a clean Claude Code slate
- Resetting a development environment using
--allto clear everything at once
Relationship to Previous Workarounds
Before this command, developers who needed to clear Claude Code state had to manually locate and delete files in ~/.claude/ — an error-prone process that risked deleting too much or too little. Third-party tools like claude-clean on PyPI emerged specifically to fill this gap. The claude project purge command supersedes these workarounds with an officially supported, flag-rich alternative built directly into the CLI.