/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

• Read ~/.claude/plugins/installed_plugins.json if it exists

• 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)

• Check if current project has plugins that show as "installed" but are not active here

Step 2: Validate settings files

• Validate JSON syntax in all settings files:

• ~/.claude/settings.json (user-level)

• .claude/settings.json (project-level)

• .claude/settings.local.json (local overrides)

• Check for common issues: invalid permission patterns, conflicting allow/deny rules, deprecated settings

Step 3: Check hooks configuration

• Read hooks from settings files

• Validate that hook command paths exist

• Check timeout configurations

• Identify potential hook conflicts

Step 4: Check MCP server configuration

• Look for MCP configuration in .claude/settings.json , .mcp.json , and plugin-provided MCP configs

• Validate server command paths

• 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