Diagnose and fix issues with the Claude Code plugin registry. This command specifically addresses issue #14202 where project-scoped plugins incorrectly appear as globally installed.
When to Use This Skill
Use this skill when...
Use another approach when...
Fixing plugin registry corruption (issue #14202)
Comprehensive health check (use
/health:check
)
Diagnosing project-scope vs global plugin issues
Auditing plugins for relevance (use
/health:audit
)
Cleaning up orphaned plugin entries
Settings validation only needed
Resolving "plugin already installed" errors
Agentic optimization audit (use
/health:agentic-audit
)
Manually inspecting registry JSON
Just viewing installed plugins (read registry file)
find . -maxdepth 1 -type d -name \'.claude-plugin\'
Background: Issue #14202
When a plugin is installed with
--scope project
in one project, other projects incorrectly show the plugin as "(installed)" in the Marketplaces view. This happens because:
The plugin registry at
~/.claude/plugins/installed_plugins.json
stores
projectPath
for project-scoped installs
The Marketplaces view only checks if a plugin key exists, not whether it's installed for the
current
project
The install command refuses to install because it thinks the plugin already exists
Impact
Users cannot install the same plugin across multiple projects with project-scope isolation.
Parameters
Parameter
Description
--fix
Apply fixes to the plugin registry
--dry-run
Show what would be fixed without making changes
--plugin
Check/fix a specific plugin only
Execution
Execute this plugin registry diagnostic:
Step 1: Read the plugin registry
Read
~/.claude/plugins/installed_plugins.json
Parse each plugin entry to extract: plugin name and source, whether it has a
projectPath
(project-scoped), and the installation timestamp and version
Step 2: Identify issues in the registry
Check for these issue types:
Issue Type
Detection
Severity
Orphaned projectPath
projectPath
directory doesn't exist
WARN
Missing from current project
Plugin has different
projectPath
than current directory
INFO
Duplicate scopes
Same plugin installed both globally and per-project
WARN
Invalid entry
Missing required fields or malformed data
ERROR
Step 3: Report findings
Print a structured diagnostic report listing all installed plugins with scope and status, followed by issues found with severity, details, and suggested fixes.
Step 4: Apply fixes (if --fix flag)
For each issue, apply the appropriate fix:
Orphaned projectPath
-- remove the orphaned entry from installed_plugins.json
Plugin needed in current project
-- ask user which plugins to install, add new entry with current
projectPath
, update
.claude/settings.json
with
enabledPlugins
if needed
Before making changes:
Create backup:
~/.claude/plugins/installed_plugins.json.backup
Validate JSON after modifications
Report what was changed
Step 5: Verify the fix
After applying fixes:
Re-read the registry
Confirm issues are resolved
Remind user to restart Claude Code for changes to take effect
Registry Structure Reference
{
"version"
:
2
,
"plugins"
:
{
"plugin-name@marketplace-name"
:
[
{
"scope"
:
"project"
,
"projectPath"
:
"/path/to/project"
,
"installPath"
:
"~/.claude/plugins/cache/marketplace/plugin-name/1.0.0"
,
"version"
:
"1.0.0"
,
"installedAt"
:
"2024-01-15T10:30:00Z"
,
"lastUpdated"
:
"2024-01-15T10:30:00Z"
,
"gitCommitSha"
:
"abc123"
}
]
}
}
Scope types:
"scope": "project"
— has
projectPath
, only active in that project
"scope": "user"
— no
projectPath
, active globally
Manual Workaround
If automatic fix fails, users can manually edit
~/.claude/plugins/installed_plugins.json
:
Open the file in an editor
Find the plugin entry
Either:
Remove
projectPath
to make it global
Change
projectPath
to current project path
Add a new entry with different key for current project
Save and restart Claude Code
Agentic Optimizations
Context
Command
Plugin registry diagnostics
/health:plugins
Fix registry issues
/health:plugins --fix
Dry-run mode
/health:plugins --dry-run
Inspect registry
jq '.' ~/.claude/plugins/installed_plugins.json 2>/dev/null
Check specific plugin
jq '.["plugin-name"]' ~/.claude/plugins/installed_plugins.json 2>/dev/null
List orphaned paths
jq -r 'to_entries[] | select(.value.projectPath? and (.value.projectPath | test("."))) | .value.projectPath' ~/.claude/plugins/installed_plugins.json 2>/dev/null
Flags
Flag
Description
--fix
Apply fixes (with confirmation prompts)
--dry-run
Show what would be fixed without changes
--plugin
Target a specific plugin
See Also
/health:check
- Full diagnostic scan
/health:settings
- Settings file validation
Issue #14202
- Upstream bug report