/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 - 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 by running the diagnostic scripts. Pass --verbose and --fix flags through from $ARGUMENTS when specified.
Step 1: Check plugin registry
bash "${CLAUDE_SKILL_DIR}/scripts/check-plugins.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--fix] [--verbose]
Parse the STATUS= and ISSUES: lines from output.
Step 2: Validate settings files
bash "${CLAUDE_SKILL_DIR}/scripts/check-settings.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--verbose]
Parse the STATUS= and ISSUES: lines from output.
Step 3: Check hooks configuration
bash "${CLAUDE_SKILL_DIR}/scripts/check-hooks.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--verbose]
Parse the STATUS= and ISSUES: lines from output.
Step 4: Check MCP server configuration
bash "${CLAUDE_SKILL_DIR}/scripts/check-mcp.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--verbose]
Parse the STATUS= and ISSUES: lines from output.
Step 5: Generate the diagnostic report
Using the structured output from Steps 1-4, print a diagnostic report following the template in REFERENCE.md. Include status indicators (OK/WARN/ERROR), issue counts, and recommended actions. If --fix was used and fixes were applied, include a summary of changes made.
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