A TypeScript/Deno tool to remove Claude artifacts from Git repositories.

• Overview
• Features
• What Gets Cleaned
• Installation
• Quick Start
• Usage
• How It Works
• Safety Features
• Troubleshooting
• Frequently Asked Questions
• Development
• Contributing
• Acknowledgments

Claude Cleaner removes Claude-related files, commit trailers, and other artifacts from Git repository history. It rewrites history using git filter-branch driven by the tool's own self-invoked filters, so Git is the only external dependency — no Java, BFG, or sd runtime is required.

• 🔒 Safe: Dry-run mode, automatic backups, and rollback capabilities
• 🌍 Cross-platform: Works on Windows, macOS, and Linux
• 📦 Self-contained: Compiles to a single binary that needs only Git at runtime
• 🎯 Flexible: Files-only, commits-only, or full cleaning modes

Claude Cleaner targets specific files and commit patterns created by Claude Code. Your regular project files and commit messages remain untouched.

The tool uses exact basename matching for safety. For example:

• .claude/ matches only directories named exactly .claude (not .claude2 or my.claude)
• .vscode/claude.json matches the exact path .vscode/claude.json only

Standard patterns (CLAUDE.md files are preserved by default):

• .claude/ directories - Claude workspace configurations
• claudedocs/ directories - Claude documentation (MCP server)
• .serena/ directories - Serena MCP server data
• .vscode/claude.json - VSCode Claude extension settings
• Temporary Claude files - Auto-generated temporary files

Preserved by default:

• CLAUDE.md - Project instruction files (use --include-instruction-files to remove)

This flag enables comprehensive cleanup by matching many more Claude-related file patterns across multiple categories:

• Configuration files - Settings, workspace, environment configs
• Session & state - Session data, cache, history files
• Temporary files - Working files, drafts, backups
• Process files - Lock files, PIDs, sockets
• Debug files - Debug logs, traces, profiles
• Export files - Archives, dumps, snapshots
• IDE integration - IDE-specific Claude configs
• Documentation - Notes, docs, instructions
• Scripts - Shell scripts, utilities, helpers
• Hidden files - Dotfiles like .clauderc
• Versioned files - Numbered or versioned variants

See PATTERNS.md for the complete pattern reference with examples and detailed explanations.

• 🤖 Generated with [Claude Code](...) - Claude attribution trailers
• Co-Authored-By: Claude <noreply@anthropic.com> - Co-authorship attributions
• Other Claude attribution lines - Additional Claude-generated metadata

The tool requires Git at runtime — that is the only external dependency. There is nothing to auto-install; verify Git is available with claude-cleaner check-deps.

The --auto-install flag is deprecated and is now an accepted no-op (it prints a warning and does nothing). It remains only for backward compatibility.

# Option 1: Install from JSR (recommended)
deno install -A jsr:@tylerbu/claude-cleaner

# Option 2: Download pre-built binary
# Download from GitHub releases page

# Option 3: Build from source (requires Deno)
git clone https://github.com/yourusername/claude-cleaner  # Replace with actual repository URL
cd claude-cleaner
deno compile --allow-all --output claude-cleaner src/main.ts

# 1. Check that Git is available
claude-cleaner check-deps

# 2. Preview changes without modifying anything (dry-run is the default)
claude-cleaner

# 3. Execute cleaning (only after reviewing dry-run output)
claude-cleaner --execute

Usage: claude-cleaner [options] [path]

Options:
  -h, --help                        Show help
  -V, --version                     Show version
  -x, --execute                     Execute changes (default: dry-run mode shows what would be changed)
  -v, --verbose                     Enable verbose output
  --auto-install                    (Deprecated, no-op) Formerly installed external tools; only Git is required now
  --files-only                      Only remove Claude files (skip commit cleaning)
  --commits-only                    Only clean commit messages (skip file removal)
  --branch <branch>                 Specify branch to clean (default: HEAD)
  --include-all-common-patterns     Include ALL known common Claude patterns (for complete cleanup)
  --include-instruction-files       Include CLAUDE.md instruction files for removal (preserved by default)
  --include-dirs <name>             Add directory name to remove (matches directories with this name anywhere)
  --include-dirs-file <file>        Read directory names from file (one pattern per line)
  --no-defaults                     Don't include default Claude patterns (use only explicit patterns)

Arguments:
  <repo-path>                       Path to Git repository (REQUIRED)

Commands:
  check-deps                        Check if all required dependencies are available

# Preview changes (default behavior)
claude-cleaner .

# Execute cleaning after reviewing dry-run
claude-cleaner . --execute

# Clean specific repository
claude-cleaner /path/to/repo --execute

# Preview with verbose output
claude-cleaner . --verbose

# Check what dependencies are needed
claude-cleaner check-deps

# Preview file removal only
claude-cleaner . --files-only

# Execute file removal only
claude-cleaner . --files-only --execute

# Preview commit message cleaning only
claude-cleaner . --commits-only

# Execute commit cleaning on specific branch
claude-cleaner . --commits-only --execute --branch feature/my-branch

Use --include-all-common-patterns for complete Claude artifact removal, especially for long-running projects or when preparing repositories for distribution.

# Preview comprehensive cleanup (recommended first)
claude-cleaner --include-all-common-patterns --verbose

# Execute complete cleanup - find ALL known/possible Claude patterns
claude-cleaner --include-all-common-patterns --execute

# Preview comprehensive file-only cleanup
claude-cleaner --include-all-common-patterns --files-only --verbose

# Execute comprehensive file-only cleanup
claude-cleaner --include-all-common-patterns --files-only --execute

By default, CLAUDE.md instruction files are preserved to keep project documentation intact. To remove them:

# Remove CLAUDE.md files along with other Claude artifacts
claude-cleaner --include-instruction-files --execute

# Or use comprehensive mode (automatically includes instruction files)
claude-cleaner --include-all-common-patterns --execute

These examples show advanced usage patterns for power users and troubleshooting scenarios.

# Verbose dry-run output for troubleshooting
claude-cleaner --verbose

# Check that Git is available
claude-cleaner check-deps

# Execute with verbose output
claude-cleaner --execute --verbose

# Custom directory patterns (can be specified multiple times)
claude-cleaner --include-dirs "claude-backup" --include-dirs "claude-workspace"

# Read directory patterns from file
echo "claude-backup" > dirs.txt
echo "claude-workspace" >> dirs.txt
claude-cleaner --include-dirs-file dirs.txt

# Use only custom patterns (exclude defaults)
claude-cleaner --no-defaults --include-dirs "my-claude-files"

Claude Cleaner follows a systematic, safety-first approach to ensure your repository integrity while removing Claude artifacts.

1. 🔍 Dependency Check - Verifies Git is available
2. ✅ Repository Validation - Ensures you're in a valid Git repository with a clean tracked working tree
3. 🧭 Preflight - In full mode, validates the repository, working tree, target branch, and both the file and commit plans before any backup or history rewrite, so a predictable failure can't occur after files have already been rewritten
4. 💾 Backup Creation - Creates backups before making any changes
5. 📁 File Removal - Uses git filter-branch with a self-invoked --index-filter to remove Claude files from Git history
6. ✏️ Commit Cleaning - Uses git filter-branch with a self-invoked --msg-filter to clean commit messages and trailers
7. 🔎 Verification - Validates all changes were applied correctly

• Scans repository for Claude files (CLAUDE.md, .claude/, .vscode/claude.json, etc.)
• Removes files from entire Git history using git filter-branch (repository-wide, all refs)
• Creates backup before any modifications
• Preserves commit messages unchanged

• Analyzes commit messages for Claude trailers and attributions
• Rewrites commit history (scoped to the target ref) using git filter-branch
• Uses a shared, Unicode-safe attribution parser for exact, line-anchored trailer removal
• Preserves file content unchanged

Claude Cleaner prioritizes safety with multiple protection mechanisms. However, always ensure your repository is backed up before running any cleaning operations.

Claude Cleaner uses two different backup strategies depending on the operation, both designed to protect against history rewriting:

When removing files (--files-only or the file phase of full mode):

• Strategy: Creates a complete bare clone in a separate directory
• Location: ../claude-cleaner-backup-<timestamp> (outside your repository)
• Protection: Since file cleaning rewrites commits and updates all refs in the target repository, the bare clone remains completely untouched as a separate physical repository
• Recovery: git clone the backup directory to restore

# Example backup location
/path/to/your-repo/.../claude-cleaner-backup-2024-01-15T10-30-00-000Z

When cleaning commit messages with git filter-branch:

• Strategy: Creates a branch in the same repository
• Naming format: backup/pre-claude-clean-YYYY-MM-DDTHH-MM-SS-sssZ
• Protection: filter-bra