clear-plugin-cache

Clear Plugin Cache Command

Clear cached plugin copies from the plugin system cache. This is a more aggressive operation that removes the entire plugin installation, requiring reinstall afterward.

When to Use

• Plugin behaving unexpectedly after updates
• Corrupted plugin installation
• Freeing significant disk space
• Clean slate reinstallation needed

For complete plugin reset (including registry and settings): Use /user-config:reset-plugins instead. This command only clears the cache while preserving the registry.

What Gets Cleared vs Preserved

Cleared:

• ~/.claude/plugins/cache/ - All cached plugin copies

Preserved (NOT cleared):

• ~/.claude/plugins/installed_plugins.json - Plugin registry (knows what to reinstall)
• ~/.claude/plugins/known_marketplaces.json - Marketplace sources

Arguments

• No arguments: Clear ALL plugin caches (prompts for confirmation)
• plugin-name: Clear only the specified plugin's cache (e.g., claude-ecosystem)
• --force: Skip confirmation

Examples:

/clear-plugin-cache                        # Clear all plugins
/clear-plugin-cache claude-ecosystem       # Clear only claude-ecosystem
/clear-plugin-cache --force                # Clear all without confirmation
/clear-plugin-cache claude-ecosystem --force   # Clear one without confirmation

Step 1: Parse Arguments

plugin_filter = None  # or specific plugin name
force_mode = "--force" in arguments (case-insensitive)

# Parse: anything that's not --force is treated as plugin name
for arg in arguments:
    if arg.lower() == "--force":
        force_mode = True
    elif not arg.startswith("--"):
        plugin_filter = arg

Step 2: Locate Plugin Cache

The plugin cache is at: ~/.claude/plugins/cache/

Structure:

~/.claude/plugins/
  cache/
    {marketplace}/
      {plugin-name}/
        {version}/
          ... (full plugin copy)

Step 3: Inventory Cache Contents

List what will be cleared:

# List all marketplace directories
ls -la ~/.claude/plugins/cache/

# For each marketplace, list plugins
ls -la ~/.claude/plugins/cache/{marketplace}/

# Get total size
du -sh ~/.claude/plugins/cache/

If plugin_filter is set, only inventory that specific plugin.

Step 4: Confirmation (unless --force)

If NOT force_mode, present the cache clear plan:

For ALL plugins

## Plugin Cache Clear Plan

**Target:** ALL cached plugin copies

| Marketplace | Plugins | Size |
| --- | --- | --- |
| claude-code-plugins | 10 | 120 MB |

**Total:** 120 MB across 10 plugins

> **WARNING:** This will remove all installed plugins.
> You will need to reinstall them using `/plugin install {name}@{marketplace}`.
> The plugin registry (installed_plugins.json) is preserved, so Claude Code
> knows what to reinstall.

**Proceed?** Reply "yes" to continue, or use `--force` to skip this confirmation.

For SINGLE plugin

## Plugin Cache Clear Plan

**Target:** claude-ecosystem plugin cache only

| Plugin | Version | Size |
| --- | --- | --- |
| claude-ecosystem | 3.0.0 | 106 MB |

> **Note:** After clearing, reinstall with:
> `/plugin install claude-ecosystem@claude-code-plugins`

**Proceed?** Reply "yes" to continue, or use `--force` to skip this confirmation.

Step 5: Clear Cache

For ALL plugins

rm -rf ~/.claude/plugins/cache/*

For SINGLE plugin

# Find and remove specific plugin across all marketplaces
rm -rf ~/.claude/plugins/cache/*/{plugin-name}

Step 6: Report Success

## Plugin Cache Cleared

Successfully cleared plugin cache.

**Cleared:**
- X plugins (Y MB total)

**Preserved:**
- installed_plugins.json (plugin registry)
- known_marketplaces.json (marketplace sources)

**Next steps:**
Reinstall plugins using:

`/plugin install {plugin-name}@{marketplace}`

Or browse and reinstall interactively:

`/plugin`

Error Handling

• Cache not found: Report "Plugin cache directory not found or already empty."
• Permission denied: Report "Permission denied. Check file permissions on ~/.claude/plugins/cache/"
• Plugin not found: Report "Plugin '{name}' not found in cache. Available plugins: {list}"

Safety Notes

• This is safe for both local and git-based marketplaces - the cache is always a downstream copy
• Local marketplace: Plugin will be re-copied from source directory
• Git marketplace: Plugin will be re-cloned/fetched from remote

The original source (your local repo or git remote) is NEVER modified.

Cross-Platform Notes

• Windows: ~ resolves to %USERPROFILE%
• Use forward slashes in paths for consistency
• rm -rf works in Git Bash on Windows

Related Commands

• /user-config:reset-plugins - Complete plugin reset (cache + registry + settings)
• /user-config:prune - General Claude Code cache cleanup (excludes plugins)
• /plugin uninstall {name} - Remove a specific plugin properly