🧼squeaky-clean✨

Easy cross-system development cache cleaner/manager with terminal and Raycast surfaces

Essentially a "universal cachectl"—smart (sort of), safe (at least, I think it is...), and configurable cache cleaner/manager system with support for most common development tools. Designed as a shared core with multiple user-facing surfaces: the npm/Homebrew terminal CLI, guided TUI-style prompts, and the macOS Raycast extension.

Features • Installation • Raycast • Usage • Configuration • Supported Tools • Contributing

Features

• 🎯 Smart Detection: Automatically detects installed development tools and their cache locations
• 🎨 Interactive Wizard: Beautiful CLI interface with progress bars and colored output
• 🧭 Raycast Extension: Inspect, dry-run, and clean caches from Raycast on macOS using the same cleaner engine
• 📡 Real-Time Progress: Live parallel scanning status with animated indicators for 25+ tools simultaneously
• 🔧 Highly Configurable: Choose exactly which caches to clean and when
• 📊 Size Analytics: See how much space each cache is using before cleaning
• 🛡️ Safe by Default: Confirmation prompts are enabled by default; use --dry-run to preview without deleting files
• 🚦 Safety Tiers & Cleaning Profiles: Every cache classified safe → manual; pick a conservative, balanced, or aggressive profile
• 🔎 System-Wide App Cache Discovery: Finds non-developer app caches (Electron, GPU/shader, sandboxed/Flatpak/Snap apps, logs) guarded by a built-in safety database
• ⚡ Performance: Parallel cleaning operations for maximum speed
• 🔄 Auto-clean Mode: Get size/age/safety-based cleaning recommendations and optionally clean them
• 📱 Cross-platform: Works on macOS, Linux, and Windows
• 🧩 Multi-surface Product: Terminal CLI, guided terminal prompts, Raycast, and future platform-specific entry points share the same safety model
• 🔄 Config Migration: Automatic migration from legacy to new configuration format
• 🔌 Plugin Support: Discover and use community cleaners via npm packages
• 📋 JSON Output: Machine-readable output for scripting and automation
• 🔄 Auto-Update: Background update checking with easy self-update command

📦 Installation

Global Installation (Recommended)

npm install -g squeaky-clean

Or using other package managers:

# Yarn
yarn global add squeaky-clean

# pnpm
pnpm add -g squeaky-clean

# Bun
bun add -g squeaky-clean

Homebrew (macOS/Linux)

brew install chendrizzy/squeaky-clean/squeaky-clean

Raycast Extension (macOS)

Install the Raycast surface from the Raycast Store.

The extension is intentionally a thin UI over the published squeaky-clean engine, so Raycast actions use the same cache detection, safety tiers, cleaning profiles, dry-run behavior, and config path as the terminal tool. See the Raycast extension guide for command details.

Local Installation

npm install --save-dev squeaky-clean

Updating

Squeaky Clean includes a built-in update command:

# Check for and install updates
squeaky update

# Only check for updates without installing
squeaky update --check

By default, squeaky-clean will automatically check for updates once every 24 hours when you run any command. You can disable this with:

squeaky update --disable-auto

Usage

Interactive Mode (Recommended)

Start the guided terminal flow:

squeaky interactive

This will guide you through selecting which caches to clean and confirming the cleanup interactively.

Raycast

The Raycast extension exposes the main workflows as three top-level commands:

| Command | What it maps to | |---------|------------------| | Inspect Caches | squeaky list, squeaky sizes, per-cleaner dry runs, and category inspection | | Clean Caches | squeaky clean with profile, type, tool, age, size, priority, use-case, category, and manual-consent filters | | Quick Clean | A one-action profile-based dry run or cleanup using Raycast preferences |

That three-command shape is deliberate: the deeper controls live inside the workflows instead of becoming a noisy one-command-per-CLI-subcommand palette. If a future workflow needs its own muscle memory, it can become a dedicated command without duplicating the existing dashboard.

Command Line

Clean all caches

squeaky clean --all

Clean specific cache types

# Clean only package manager caches
squeaky clean --types package-manager

# Clean multiple types
squeaky clean --types package-manager,build-tool

# Clean specific tools
squeaky clean --include npm,yarn,webpack

Dry run mode (preview without cleaning)

squeaky clean --all --dry-run

Show cache sizes

squeaky sizes

List available caches

squeaky list
# With sizes inline
squeaky list --sizes

🎯 Granular Cache Management

# View detailed cache categories
squeaky categories --tool npm
squeaky categories --verbose  # Show all tools with details

# Clean caches older than 7 days
squeaky clean --older-than 7d

# Clean caches larger than 100MB
squeaky clean --larger-than 100MB

# Clean only low priority caches (preserve critical/important)
squeaky clean --priority low

# Clean archived/experimental caches
squeaky clean --use-case archived

# Combine multiple criteria
squeaky clean --older-than 14d --priority low --larger-than 50MB

# Clean specific categories by ID
squeaky categories --tool npm  # First, list categories to get IDs
squeaky clean --categories npm-logs,npm-metrics

# Use custom config file
squeaky clean --config my-config.json --dry-run

Available Commands

| Command | Description | Aliases | |---------|-------------|---------| | clean | Clean development caches with granular control | - | | list | List available caches and their status | ls | | sizes | Show cache sizes without clearing | - | | categories | Show detailed cache categories with usage patterns | cats | | config | Manage configuration | - | | profile | Show or set the active cleaning profile (conservative, balanced, aggressive) | - | | doctor | Check system and diagnose issues | - | | auto | Recommend and clean caches using smart heuristics | - | | update | Check for and install updates | - | | interactive | Start interactive configuration wizard | i |

Command Options

clean Options

• -a, --all - Clean all configured caches
• -t, --types <types> - Comma-separated list of cache types
• -e, --exclude <tools> - Comma-separated list of tools to exclude
• --include <tools> - Comma-separated list of tools to include (overrides --all and --exclude)
• -d, --dry-run - Show what would be cleaned without actually cleaning
• -f, --force - Skip confirmation prompts
• -s, --sizes - Show cache sizes before cleaning

🎯 Granular Selection Options:

• --older-than <age> - Clean caches older than specified age (e.g., 7d, 2w, 1m)
• --newer-than <age> - Clean caches newer than specified age
• --larger-than <size> - Clean caches larger than specified size (e.g., 100MB, 1GB)
• --smaller-than <size> - Clean caches smaller than specified size
• --use-case <case> - Target specific use cases (development, testing, production, experimental, archived)
• --priority <level> - Clean only specified priority (critical, important, normal, low)
• --categories <ids> - Clean specific category IDs (comma-separated)
• --sub-caches <cleaner:category,...> - Clean specific sub-caches within a cleaner (e.g., xcode:DerivedData,npm:logs)

🚦 Safety & Profile Options:

• --profile <name> - Cleaning profile to apply (conservative, balanced, aggressive)
• --safety <tiers> - Comma-separated safety tiers to clean (safe, probably-safe, caution, manual); overrides --profile
• --allow-manual <ids> - Comma-separated category IDs consenting to manual-tier cleaning

🧹 App-Caches Breakdown:

• --group-by <hierarchy> - Group the app-caches breakdown by a single axis or comma-list hierarchy (e.g. tier,kind,app) or none; default tier → kind → app
• --summary - Force the collapsed one-line summary (useful when display.expand is on); use --json for machine output
• By default clean --dry-run shows the collapsed summary (5.2 GB · 18 caches · 6 apps · top: …); add -v to expand the tree. Configure default grouping/expansion and per-app excludes under toolSettings.app-caches (see the Configuration Guide)

categories Options

• -t, --tool <tool> - Show categories for specific tool
• --type <type> - Filter by cache type
• -v, --verbose - Show detailed information
• --group-by <hierarchy> - Group categories by a single axis or comma-list hierarchy (e.g. tier,kind,app) or none (default tier → kind → app)

list Options

• -s, --sizes - Include cache sizes inline with the list
• -t, --type <type> - Filter by cache type

update Options

• -c, --check - Only check for updates without installing
• --auto-on - Enable automatic update checks on startup (--enable-auto/--enable-auto-update aliases)
• --auto-off - Disable automatic update checks (--disable-auto/--disable-auto-update aliases)

Global Options

• -v, --verbose - Enable verbose output
• --no-color - Disable colored output
• --config <path> - Use custom configuration file
• --json - Output supported command results as JSON
• -q, --quiet - Suppress non-essential output
• --version - Show version number
• -h, --help - Display help

🚦 Safety Tiers & Cleaning Profiles

Every cache category is classified into one of four safety tiers, and the active cleaning profile decides which tiers get cleaned:

| Tier | Meaning | |------|---------| | safe | Regenerated transparently; no observable downside to cleaning | | probably-safe | Regenerable; apps may start slower or re-download data once | | caution | May lose useful state (offline content, large re-downloads) or upset running apps | | manual | User-data adjacent; requires explicit per-item confirmation, never cleaned implicitly |

| Profile | Tiers cleaned | Description | |---------|---------------|-------------| | conservative | safe | Only caches that are definitely safe to clean | | balanced (default) | safe, probably-safe | Safe caches plus regenerable ones that may cost a slower next launch | | aggressive | safe, probably-safe, caution | Everything except manual-confirmation items |

# View the active profile (and all available profiles)
squeaky profile

# Persist a profile as the default for future runs
squeaky profile conservative

# Apply a profile for a single run
squeaky clean --all --profile aggressive

# Override with an explicit tier list (beats --profile)
squeaky clean --all --safety safe,caution

Manual tier = explicit consent. Manual-tier categories (e.g. 100GB+ ML model stores) are never cleaned implicitly—no profile includes them, and --force cannot bypass the consent gate. Consent per category interactively when prompted, or pass category IDs explicitly:

# Find category IDs first, then consent explicitly
squeaky categories --tool app-caches
squeaky clean --include app-caches --allow-manual <category-id>

🔎 System-Wide App Cache Discovery (app-caches)

The app-caches cleaner discovers non-developer application caches across the whole system:

• macOS: ~/Library/Caches, Electron Cache/GPUCache/Code Cache dirs under ~/Library/Application Support, sandboxed-app caches under ~/Library/Containers/*/Data/Library/Caches and ~/Library/Group Containers/*/Library/Caches, ~/Library/Logs, and ~/.cache
• Linux: ~/.cache (XDG), Electron caches under ~/.config/*, plus Flatpak (~/.var/app/*/cache) and Snap (~/snap/*/{current,common}/.cache) app caches
• Windows: LOCALAPPDATA/APPDATA (Electron Cache/GPUCache/Code Cache) and the user Temp directory

A built-in safety database:

• Hard-excludes dangerous lookalikes (iCloud/CloudKit sync state, Mail, Photos, device backups, Docker's VM disk, Signal, password managers)—never shown, never cleaned
• Skips paths already covered by the dedicated tool cleaners (no double counting)
• Classifies everything else by tier (GPU/shader caches = safe, chat app caches = caution, huge ML model stores = manual)

Heads-up: the full-system scan is heavier than the dev-only scan (tens of seconds on a large system, and more on Macs with many sandboxed apps). The largest caches are always surfaced even when the candidate list is capped. To keep the fast dev-only scan:

squeaky clean --all --exclude app-caches   # skip for one run
squeaky config --disable app-caches        # disable persistently

🛠️ Supported Tools

Package Managers

| Tool | Caches Cleaned | |------|----------------| | npm | ~/.npm, node_modules/.cache | | Yarn | ~/.yarn/cache, .yarn/cache | | pnpm | ~/.pnpm-store, ~/.cache/pnpm | | Bun | ~/.bun/install/cache | | pip | ~/.cache/pip | | Cargo | Cargo registry, git, and build caches | | Poetry | Poetry package caches | | Pipenv | Pipenv caches | | CocoaPods | CocoaPods caches | | SwiftPM | Swift Package Manager caches | | NuGet | NuGet package caches | | Homebrew | brew --cache, old versions | | Nix | /nix/store garbage, old generations |

Build Tools

| Tool | Caches Cleaned | |------|----------------| | Webpack | .webpack-cache, node_modules/.cache/webpack | | Vite | node_modules/.vite, .vite-cache | | Nx | node_modules/.cache/nx, .nx/cache | | Turbo | .turbo, node_modules/.cache/turbo | | Flutter | ~/.pub-cache, build/ | | node-gyp | Native addon build caches | | Go Build | Go build caches | | Maven | Maven repository and build caches | | Playwright | Browser binaries and Playwright caches | | Gradle | ~/.gradle/caches, .gradle/ |

IDEs & Editors

| Tool | Caches Cleaned | |------|----------------| | VS Code | ~/.config/Code/Cache*, Extensions cache | | Xcode | ~/Library/Developer/Xcode/DerivedData | | Android Studio | ~/.android/cache, Build cache | | JetBrains IDEs | ~/.cache/JetBrains/*/caches | | Windsurf | Windsurf editor caches, logs, extensions, and workspace data | | Cursor | Cursor editor caches, logs, extensions, and workspace data | | Zed | Zed editor caches and logs | | Antigravity | Antigravity IDE caches, logs, extensions, and workspace data |

Browsers (Development)

| Tool | Caches Cleaned | |------|----------------| | Chrome | Dev tools cache, Service workers | | Firefox | Dev tools cache, Temporary files |

System Tools

| Tool | Caches Cleaned | |------|----------------| | Docker | Unused containers, images, volumes | | Universal Binary (universal-binary) | Apple Silicon app thinning, handled by the separate squeaky ub command | | ShipIt | ShipIt and Google Keystone updater caches | | App Caches (app-caches) | System-wide discovered application caches, classified by safety tier | | Temp Files (tmp) | Abandoned user-owned temp files with active-task-aware filtering |

⚙️ Configuration

Squeaky Clean can be configured through:

1. Interactive wizard: squeaky config --interactive
2. Configuration commands: squeaky config --set, --enable, --disable, --reset
3. Configuration file: run squeaky config --path to print the exact path

Default config locations:

• macOS: ~/Library/Preferences/squeaky-clean/config.json
• Linux: ~/.config/squeaky-clean/config.json unless XDG_CONFIG_HOME is set
• Windows: %APPDATA%/squeaky-clean/config.json

Configuration Migration (v0.2.0+)

Squeaky Clean now supports automatic migration from legacy configuration format to the new schema:

# Migrate your config automatically
squeaky config doctor

# Or use the doctor command
squeaky doctor --config

# Preview migration without changing files
squeaky config doctor --dry-run

# Migrate to a different file
squeaky config doctor --input old-config.json --output new-config.json

Configuration File Examples

Current Runtime Config Shape

{
  "activeProfile": "balanced",
  "tools": {
    "npm": true,
    "yarn": true,
    "webpack": false,
    "app-caches": true,
    "tmp": true
  },
  "toolSettings": {
    "app-caches": {
      "display": {
        "expand": false,
        "groupBy": ["tier", "kind", "app"],
        "topN": 5
      },
      "exclude": []
    }
  },
  "safety": {
    "requireConfirmation": true,
    "dryRunDefault": false,
    "backupBeforeClearing": false,
    "excludeSystemCritical": true
  },
  "output": {
    "verbose": false,
    "showSizes": true,
    "useColors": true,
    "emojis": "on"
  }
}

Legacy Migration Input (still accepted by config doctor)

{
  "tools": {
    "npm": { "enabled": true },
    "yarn": { "enabled": true },
    "webpack": { "enabled": false }
  },
  "auto": {
    "enabled": true,
    "schedule": "weekly",
    "sizeThreshold": "1GB"
  },
  "output": {
    "verbose": false,
    "useColors": true
  }
}

Environment Variables

Core cleaning behavior is controlled by CLI flags and the config file, not environment variables. The current runtime only documents environment variables for developer diagnostics and presentation:

• SQUEAKY_FUN_MODE=0|1 - Disable or enable fun console styling
• SQUEAKY_PROFILE=1 - Print app-cache discovery timing details for profiling

🔄 Automatic Cleaning

squeaky auto is a smart recommendation command, not a scheduler. It scans caches, ranks candidates by size, age, and safety, then prompts before deleting unless you use --dry-run or --force.

• --dry-run previews the recommended cleanup
• --safe restricts cleanup to caches verified safe to auto-clean
• --aggressive includes more recommended caches
• --force skips the confirmation prompt

# Preview recommendations
squeaky auto --dry-run

# Clean safe recommendations without prompting
squeaky auto --safe --force

# Include more recommended cache types
squeaky auto --aggressive --dry-run

🧭 Product Surfaces & Roadmap

Squeaky Clean is a shared cache-cleaning core with multiple surfaces:

• Terminal CLI: the canonical cross-platform interface distributed through npm and Homebrew
• Guided terminal prompts: TUI-style selection flows for setup and interactive cleaning
• Raycast extension: a macOS command-palette UI for inspection, dry runs, and profile-based cleaning
• Future package-manager hubs: Python packaging is feasible as a distribution surface, but a full Python port would duplicate the TypeScript cleaner logic and safety rules. The practical path is to keep the TypeScript core authoritative and consider a small Python/pipx wrapper only if Python users need discovery from PyPI.

For the current assessment, see Raycast Extension & Platform Notes.

🦆 Mascot

Meet Squeaky, nicknamed pip squeaky: a cool, suave, but still cute duck who represents the repo in user-facing surfaces.

🏗️ Architecture

Squeaky Clean is built with a modular architecture:

src/
├── cli.ts              # CLI entry point
├── commands/           # Command implementations
│   ├── clean.ts       # Main cleaning logic
│   ├── interactive.ts # Interactive wizard
│   ├── config.ts      # Configuration management
│   └── ...
├── cleaners/          # Tool-specific cleaners
│   ├── npm.ts
│   ├── docker.ts
│   └── ...
├── config/            # Configuration system
├── utils/             # Utility functions
└── types/             # TypeScript definitions

Each cleaner module implements the CleanerModule interface:

interface CleanerModule {
  name: string;
  type: CacheType;
  description: string;
  getCacheInfo(): Promise<CacheInfo>;
  clear(dryRun?: boolean): Promise<ClearResult>;
}

🧪 Development

Prerequisites

• Node.js >= 18.0.0
• npm, yarn, pnpm, or bun

Setup

# Clone the repository
git clone https://github.com/chendrizzy/squeaky-clean.git
cd squeaky-clean

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Scripts

• npm run build - Build the TypeScript source
• npm run dev - Run in development mode with hot reload
• npm test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Generate test coverage report
• npm run lint - Lint the codebase
• npm run format - Format code with Prettier
• npm run release - Run tests/build, publish to npm, and sync the GitHub release (requires the gh CLI + GH_TOKEN or GITHUB_TOKEN to be set)

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Adding a New Cleaner

To add support for a new tool:

1. Create a new cleaner module in src/cleaners/
2. Implement the CleanerModule interface
3. Register it in src/cleaners/index.ts
4. Add tests in src/__tests__/cleaners/
5. Update the README with the new tool

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with:

• Commander.js for CLI parsing
• picocolors for puuurrrtty terminal output
• Inquirer.js for interactive prompts
• Ora for elegant terminal spinners

📮 Support

• 🐛 Report bugs
• 💡 Request features
• 📖 Read the docs
• ⭐ Star the project on GitHub!