A shell script to clean history and cached data from Claude Code's ~/.claude.json file and ~/.claude/ directory.

• Clear all project histories at once
• Clear specific project history
• Delete entire projects
• Clear cached data (changelog, gates, configs)
• Clear GitHub repository paths
• Regenerate identity IDs in ~/.claude.json (userID, anonymousId, and machineID)
• Clear ~/.claude folder contents (file-history, projects, todos, shell-snapshots, statsig, debug, session-env, tasks, plans, paste-cache, telemetry, backups, stats-cache.json)
• Clear ~/.claude/history.jsonl
• Reset usage counters and usage statistics (numStartups, btwUseCount, promptQueueUseCount, tipsHistory, tipLifetimeShownCounts leaf values, firstStartTime, lastShownEmergencyTip, companion, lastOnboardingVersion, lastReleaseNotesSeen, opus1mMergeNoticeSeenCount, voiceNoticeSeenCount, slackAppInstallCount, autoPermissionsNotificationCount, remoteControlUpsellSeenCount, closedIssuesLastChecked, passesLastSeenRemaining, ideHintShownCount, opusProMigrationTimestamp, routineFiredWatermark, skillUsage, toolUsage, pluginUsage leaf values, agentLastUsed leaf values, feedbackSurveyState leaf values, claudeCodeFirstTokenDate)
• Set or remove TZ=America/Los_Angeles with dedicated commands
• Clean all option (everything at once)
• Interactive mode for easy selection
• Automatic backup creation before modifications
• Color-coded output for better readability

• jq - command-line JSON processor
  • macOS: brew install jq
  • Linux: apt-get install jq or yum install jq

Install with a single command:

curl -s https://raw.githubusercontent.com/geminiwen/cccleaner/master/install.sh | bash

Optional install-script helpers:

curl -s https://raw.githubusercontent.com/geminiwen/cccleaner/master/install.sh | bash -s -- --set-us-timezone
curl -s https://raw.githubusercontent.com/geminiwen/cccleaner/master/install.sh | bash -s -- --unset-timezone

This will:

• Install cccleaner to /usr/local/bin
• Install zsh completion to /usr/local/share/zsh/site-functions
• Set appropriate permissions

After installation, restart your shell or run exec zsh to enable zsh completion.

1. Clone the repository:

git clone https://github.com/geminiwen/cccleaner.git
cd cccleaner

2. Run the install script:

./install.sh

Or install manually:

chmod +x cccleaner
sudo cp cccleaner /usr/local/bin/
sudo mkdir -p /usr/local/share/zsh/site-functions
sudo cp _cccleaner /usr/local/share/zsh/site-functions/

To uninstall cccleaner:

curl -s https://raw.githubusercontent.com/geminiwen/cccleaner/master/uninstall.sh | bash

Or if you cloned the repository:

./uninstall.sh

Timezone management is available directly in cccleaner, and the install script also supports helper modes for shell/session timezone overrides:

• ./cccleaner --set-us-timezone sets TZ=America/Los_Angeles in common shell startup files and refreshes the current macOS login session with a LaunchAgent.

• ./cccleaner --unset-timezone removes those TZ overrides and unloads the LaunchAgent.

• bash install.sh --set-us-timezone sets TZ=America/Los_Angeles in common shell startup files and refreshes the current macOS login session with a LaunchAgent.

• bash install.sh --unset-timezone removes those TZ overrides and unloads the LaunchAgent.

These helpers do not install or uninstall cccleaner; they only manage TZ.

./cccleaner --list

./cccleaner --all

./cccleaner --project /Users/username/myproject

./cccleaner --interactive

./cccleaner --cache

./cccleaner --github-repos

./cccleaner --folders

./cccleaner --user-id

./cccleaner --set-us-timezone

./cccleaner --unset-timezone

./cccleaner --all --no-backup

By default, the script creates a backup before any modifications:

• Backups are stored in ~/.claude_backups/
• Backup filename format:
  • claude_claude.json_YYYYMMDD_HHMMSS for ~/.claude.json
  • claude_dir_YYYYMMDD_HHMMSS for ~/.claude directory
  • timezone_override_YYYYMMDD_HHMMSS/ for shell files or LaunchAgent affected by timezone commands

To restore from backup:

# Restore .claude.json
cp ~/.claude_backups/claude_claude.json_20250117_143022 ~/.claude.json

# Restore .claude directory
cp -r ~/.claude_backups/claude_dir_20250117_143022 ~/.claude

The script clears the history array in each project, which contains:

• Previous command/prompt history
• Pasted contents

When using --cache, the following keys are removed from ~/.claude.json:

• cachedChangelog
• cachedStatsigGates
• cachedDynamicConfigs
• cachedGrowthBookFeatures
• cachedGrowthBookFeaturesAt
• metricsStatusCache
• clientDataCache
• clientDataCacheSlots
• additionalModelOptionsCache
• overageCreditGrantCache
• oauthAccount
• chromeExtension
• changelogLastFetched - Reset to 0
• groveConfigCache - Reset to {}

When using --github-repos, the following key is removed from ~/.claude.json:

• githubRepoPaths - Cached GitHub repository paths

When using --user-id, the script regenerates Claude Code identity identifiers:

• userID - Replaced with a newly generated 64-character lowercase hexadecimal string
• anonymousId - Replaced with a newly generated claudecode.v1.<uuid> identifier
• machineID - Replaced with a newly generated 64-character lowercase hexadecimal string

Clears contents of the following directories:

• ~/.claude/file-history/ - File edit history
• ~/.claude/projects/ - Project-specific data
• ~/.claude/todos/ - Todo lists
• ~/.claude/shell-snapshots/ - Shell state snapshots
• ~/.claude/statsig/ - Feature flags and statistics
• ~/.claude/debug/ - Debug logs
• ~/.claude/session-env/ - Session environment snapshots
• ~/.claude/tasks/ - Task state and task logs
• ~/.claude/plans/ - Saved plans
• ~/.claude/paste-cache/ - Cached pasted content
• ~/.claude/telemetry/ - Local telemetry event files
• ~/.claude/backups/ - In-app backups under the Claude data dir
• ~/.claude/history.jsonl - Complete conversation history log

Also clears:

• ~/.claude/stats-cache.json - Local stats cache file

Performs all of the above cleaning operations at once, including:

• Clearing all project histories
• Deleting all projects
• Clearing all ~/.claude folders
• Clearing cached data
• Clearing GitHub repository paths
• Clearing history.jsonl
• Resetting usage counters (numStartups, btwUseCount, promptQueueUseCount, tipsHistory, opus1mMergeNoticeSeenCount, voiceNoticeSeenCount, slackAppInstallCount, autoPermissionsNotificationCount, remoteControlUpsellSeenCount, closedIssuesLastChecked, passesLastSeenRemaining, ideHintShownCount, opusProMigrationTimestamp, claudeCodeFirstTokenDate)
• Setting routineFiredWatermark to the current UTC timestamp
• Removing firstStartTime
• Zeroing all leaf values in tipLifetimeShownCounts
• Removing lastShownEmergencyTip
• Removing companion
• Removing lastOnboardingVersion
• Removing lastReleaseNotesSeen
• Clearing usage statistics (skillUsage, toolUsage)
• Zeroing all leaf values in pluginUsage
• Zeroing all leaf values in agentLastUsed
• Zeroing all leaf values in feedbackSurveyState
• Regenerating userID
• Regenerating anonymousId
• Regenerating machineID

Dedicated timezone commands are available separately from --all:

• ./cccleaner --set-us-timezone Sets TZ=America/Los_Angeles in common shell startup files and refreshes the current macOS login session with a LaunchAgent.
• ./cccleaner --unset-timezone Removes those TZ overrides and unloads the LaunchAgent.

The script preserves:

• Global settings (installMethod, autoUpdates, etc.)
• Project settings (allowedTools, mcpServers, etc.) - when using --folders only
• Feature flags (except cached ones)
• ~/.claude/commands/ - Custom slash commands
• ~/.claude/settings.json - User settings

$ ./cccleaner -i

[INFO] Backup created: ~/.claude_backups/claude_claude.json_20250117_143022

Interactive Mode - Select projects to clean

Projects:
  [1] /Users/john/Code/myapp (15 history items)
  [2] /Users/john/Code/webapp (8 history items)
  [3] /Users/john/Code/api (23 history items)

Options:
  [a] Clean everything
  [c] Clear cache
  [g] Clear GitHub repository paths
  [f] Clear folders (file-history, projects, todos, shell-snapshots, statsig, debug, history.jsonl)
  [u] Regenerate userID, anonymousId, and machineID
  [q] Quit

Enter selection (number/a/c/g/f/u/q): 1

What would you like to do with: /Users/john/Code/myapp
  [1] Clear history only
  [2] Delete project entirely
  [q] Cancel

Enter selection: 1

[SUCCESS] Cleared history for: /Users/john/Code/myapp
[SUCCESS] Done!

$ ./cccleaner --all

[INFO] Backup created: ~/.claude_backups/claude_claude.json_20250117_143530
[INFO] Backup created: ~/.claude_backups/claude_dir_20250117_143530

[INFO] Performing deep clean...

[SUCCESS] Cleared all project histories
[SUCCESS] Cleared all projects
[SUCCESS] Cleared file-history
[SUCCESS] Cleared projects
[SUCCESS] Cleared todos
[SUCCESS] Cleared shell-snapshots
[SUCCESS] Cleared statsig
[SUCCESS] Cleared debug
[SUCCESS] Cleared cached data
[SUCCESS] Cleared githubRepoPaths
[SUCCESS] Cleared history.jsonl
[SUCCESS] Reset counters, tipsHistory, skillUsage, toolUsage, pluginUsage leaf values, agentLastUsed leaf values, feedbackSurveyState leaf values, and tipLifetimeShownCounts leaf values; removed firstStartTime, lastShownEmergencyTip, companion, lastOnboardingVersion, and lastReleaseNotesSeen
[SUCCESS] Regenerated userID, anonymousId, and machineID
[SUCCESS] Deep clean completed!

$ ./cccleaner --list

[INFO] Projects in ~/.claude.json:

  /Users/john/Code/myapp
  /Users/john/Code/webapp
  /Users/john/Code/api

1. Automatic backups: Every operation creates a timestamped backup
2. Confirmation prompts: Destructive operations require confirmation in interactive mode
3. JSON validation: Uses jq to ensure JSON integrity
4. Error handling: Script exits safely on errors without corrupting the file

Install jq using your package manager:

• macOS: brew install jq
• Ubuntu/Debian: sudo apt-get install jq
• CentOS/RHEL: sudo yum install jq

Make sure you're using the exact project path as shown in --list

Your ~/.claude.json file might be corrupted. Try restoring from a backup.

MIT License - feel free to modify and distribute

Issues and pull requests are welcome!