/health:check

Run a comprehensive diagnostic scan of your Claude Code environment. Identifies issues with plugin registry, settings files, hooks configuration, and MCP servers.

When to Use This Skill

Use this skill when...	Use another approach when...
Running comprehensive Claude Code diagnostics	Checking specific component only (use /health:plugins, /health:settings)
Troubleshooting general Claude Code issues	Plugin registry issues only (use /health:plugins --fix)
Validating environment configuration	Auditing plugins for project fit (use /health:audit)
Identifying misconfigured settings or hooks	Just viewing settings (use Read tool on settings.json)
Quick health check before starting work	Need agentic optimization audit (use /health:agentic-audit)

Context

• User home: !echo $HOME
• Current project: !pwd
• Plugin registry exists: !find ~/.claude/plugins -maxdepth 1 -name 'installed_plugins.json'
• User settings exists: !find ~/.claude -maxdepth 1 -name 'settings.json'
• Project settings exists: !find .claude -maxdepth 1 -name 'settings.json'
• Local settings exists: !find .claude -maxdepth 1 -name 'settings.local.json'

Parameters

Parameter	Description
--fix	Attempt to automatically fix identified issues
--verbose	Show detailed diagnostic information

Execution

Execute this comprehensive health check:

Step 1: Check the plugin registry

1. Read ~/.claude/plugins/installed_plugins.json if it exists
2. For each installed plugin, verify:
   • If projectPath is set, confirm the directory exists
   • Flag orphaned entries (projectPath points to deleted directory)
   • Flag potential scope conflicts (same plugin installed globally and per-project)
3. Check if current project has plugins that show as "installed" but are not active here

Step 2: Validate settings files

1. Validate JSON syntax in all settings files:
   • ~/.claude/settings.json (user-level)
   • .claude/settings.json (project-level)
   • .claude/settings.local.json (local overrides)
2. Check for common issues: invalid permission patterns, conflicting allow/deny rules, deprecated settings

Step 3: Check hooks configuration

1. Read hooks from settings files
2. Validate that hook command paths exist
3. Check timeout configurations
4. Identify potential hook conflicts

Step 4: Check MCP server configuration

1. Look for MCP configuration in .claude/settings.json, .mcp.json, and plugin-provided MCP configs
2. Validate server command paths
3. Check for missing environment variables

Step 5: Generate the diagnostic report

Print a structured report covering each check area (Plugin Registry, Settings Files, Hooks, MCP Servers) with status indicators (OK/WARN/ERROR), issue counts, and recommended actions. Use the report template from REFERENCE.md.

Agentic Optimizations

Context	Command
Quick health check	/health:check
Health check with auto-fix	/health:check --fix
Detailed diagnostics	/health:check --verbose
Check plugin registry exists	test -f ~/.claude/plugins/installed_plugins.json && echo "exists" || echo "missing"
Validate settings JSON	jq empty .claude/settings.json 2>&1
List MCP servers	jq -r '.mcpServers | keys[]' .mcp.json 2>/dev/null

Known Issues Database

Reference these known Claude Code issues when diagnosing:

Issue	Symptoms	Solution
#14202	Plugin shows "installed" but not active in project	Run /health:plugins --fix
Orphaned projectPath	Plugin was installed for deleted project	Run /health:plugins --fix
Invalid JSON	Settings file won't load	Validate and fix JSON syntax
Hook timeout	Commands hang or fail silently	Check hook timeout settings

Flags

Flag	Description
--fix	Attempt automatic fixes for identified issues
--verbose	Include detailed diagnostic output

See Also

• /health:plugins - Detailed plugin registry diagnostics
• /health:settings - Settings file validation
• /health:hooks - Hooks configuration check
• /health:mcp - MCP server diagnostics