Auto-cleanup for temporary session files

Preflight Checklist

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

Problem Statement

• Temporary session files are left behind after Claude Code exits
• Users must manually delete or ignore these files
• No clear distinction between essential project files and temporary session artifacts
• These files shouldn't be version-controlled but require manual .gitignore management

Proposed Solution

Add an automatic cleanup mechanism that:

1. Auto-cleanup on exit: Automatically remove all temporary session files when Claude Code terminates
2. Configurable cleanup: Allow users to enable/disable this behavior via configuration (.claude/config.json or CLI

flag)

1. Cleanup on demand: Provide a CLI command like claude cleanup or claude --cleanup-temps to manually remove

orphaned temporary files

1. Whitelist mechanism: Protect essential files while cleaning up session artifacts

Alternative Solutions

• Provide a default .gitignore template that excludes common Claude Code temporary files
• Clearly document which files are temporary vs. essential

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

Claude Code creates various temporary files during sessions to manage configuration and state (e.g., .claude.json,
.claude.json.backup, and potentially other session-related files). While these files are necessary during
runtime, they accumulate in project directories and clutter the workspace after sessions end.

• Cleaner, more organized project directories
• Reduced friction for developers
• Better developer experience without manual housekeeping
• Easier integration with CI/CD pipelines and version control