Emoji Cleaner

A command-line tool to find and replace emojis in text-based files across a project. Perfect for cleaning up codebases that have accumulated emojis from AI coding agents and LLMs.

Features

• Find emojis in text files without modifying them
• Replace emojis with custom text or remove them entirely
• Interactive mode for guided emoji removal
• Support for any text-based files (no file extension restrictions)
• Multi-language support with smart ignore patterns for Python, Rust, Go, Java, C/C++, PHP, Ruby, .NET, and more
• Comprehensive emoji detection using the emoji-regex package
• Statistics and reporting on emoji usage
• Configurable file patterns and ignore rules

Supported Languages

The tool automatically ignores common build artifacts and cache directories for:

• JavaScript/TypeScript: node_modules, dist, build, .next, .nuxt
• Python: __pycache__, venv, .pytest_cache, .coverage, poetry.lock
• Rust: target, Cargo.lock, *.rlib
• Go: vendor, go.sum, *.exe, *.dll
• Java: target, build, *.class, *.jar, .gradle
• C/C++: *.o, *.obj, *.exe, *.so, *.dll
• PHP: vendor, composer.lock
• Ruby: vendor, Gemfile.lock, *.gem
• .NET: bin, obj, *.dll, *.exe
• General: .git, .vscode, .idea, *.log, *.lock

The ignore patterns are modular and can be customized by editing src/defaultIgnores.js.

Quick Start

# Find emojis in your project
npx emoji-cleaner find .

# Remove all emojis from your project
npx emoji-cleaner replace . --replacement "" --force

Customizing Ignore Patterns

You can customize the ignore patterns by editing src/defaultIgnores.js. The file exports:

• defaultIgnores: Complete list of all ignore patterns
• languageIgnores: Language-specific ignore patterns for easy customization

Example of adding custom ignore patterns:

// In src/defaultIgnores.js
export const defaultIgnores = [...defaultIgnores, 'my-custom-dir/**', '*.custom-extension'];

Installation

Local Development

npm install

Global Installation

npm install -g emoji-cleaner

Using with npx (without installation)

npx emoji-cleaner [command] [options]

Usage

Find Emojis (Read-only)

Scan for emojis without making any changes:

# Using npm start (local development)
npm start find .

# Using npx (no installation required)
npx emoji-cleaner find .

# Using global installation
emoji-cleaner find .

# Scan specific directory
npx emoji-cleaner find /path/to/project

# Custom file pattern
npx emoji-cleaner find . --pattern "**/*.py"

# Ignore specific directories
npx emoji-cleaner find . --ignore "node_modules,dist,.git"

Replace Emojis

Find and replace emojis in files:

# Replace all emojis with empty string (remove them)
npx emoji-cleaner replace .

# Replace emojis with custom text
npx emoji-cleaner replace . --replacement "[EMOJI]"

# Force replacement without confirmation
npx emoji-cleaner replace . --replacement "" --force

Interactive Mode

Run in guided interactive mode:

npx emoji-cleaner interactive

This will:

1. Ask for file patterns and ignore rules
2. Show all found emojis with context
3. Provide options to replace, show statistics, or exit
4. Guide you through the replacement process

Command Options

Global Options

• --verbose: Show detailed output
• --help: Show help information

Find Command

• --pattern <pattern>: File pattern to match (default: **/*.{js,jsx,ts,tsx,md,txt,json})
• --ignore <patterns>: Patterns to ignore (comma-separated, default: node_modules,dist,build,.git)

Replace Command

• --pattern <pattern>: File pattern to match
• --ignore <patterns>: Patterns to ignore
• --replacement <text>: Text to replace emojis with (default: empty string)
• --force: Skip confirmation prompts

Supported File Types

The tool automatically filters for text-based files with these extensions:

• .js, .jsx, .ts, .tsx (JavaScript/TypeScript)
• .md, .txt (Markdown and text files)
• .json (JSON files)
• .css, .html, .xml (Web files)
• .yaml, .yml (Configuration files)

Examples

Remove all emojis from a React project

npx emoji-cleaner replace ./my-react-app --pattern "**/*.{js,jsx,ts,tsx}" --replacement "" --force

Find emojis in documentation

npx emoji-cleaner find ./docs --pattern "**/*.md"

Replace emojis with descriptive text

npx emoji-cleaner replace . --replacement "[EMOJI_PLACEHOLDER]"

Output Examples

Find Command Output

Found 3 files with emojis:

File: /path/to/file.js
  Line 15:  - "console.log('Hello  world');"
  Line 23:  - "//  Deploy to production"

File: /path/to/README.md
  Line 5:  - "##  Features"

Total emojis found: 3

Statistics Output

Emoji Statistics:
Total files with emojis: 3
Total emojis found: 5

Most common emojis:
  : 2 times
  : 1 times
  : 1 times

Files with most emojis:
  /path/to/file.js: 2 emojis
  /path/to/README.md: 1 emojis

Development

# Install dependencies
npm install

# Run in development mode with file watching
npm run dev

# Run tests
npm test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.