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 and anonymousId)
• 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, opus1mMergeNoticeSeenCount, voiceNoticeSeenCount, skillUsage, toolUsage, firstStartTime, 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
• metricsStatusCache
• clientDataCache
• 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

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, firstStartTime, claudeCodeFirstTokenDate)
• Clearing usage statistics (skillUsage, toolUsage)
• Regenerating userID
• Regenerating anonymousId

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.)
• Authentication data
• 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)
  [q] Quit

Enter selection (number/a/c/g/f/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 numStartups, btwUseCount, promptQueueUseCount, tipsHistory, opus1mMergeNoticeSeenCount, voiceNoticeSeenCount, firstStartTime, claudeCodeFirstTokenDate, skillUsage, and toolUsage
[SUCCESS] Regenerated userID and anonymousId
[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!