Menú
Claude Code health check — scans plugins, settings, hooks, MCP, runtime state, permissions, marketplace with optional fixes. Use when checking project health or troubleshooting setup.
| created | "2026-02-04T00:00:00.000Z" |
| modified | "2026-05-14T00:00:00.000Z" |
| reviewed | "2026-05-14T00:00:00.000Z" |
| description | Claude Code health check — scans plugins, settings, hooks, MCP, runtime state, permissions, marketplace with optional fixes. Use when checking project health or troubleshooting setup. |
| allowed-tools | Bash(bash *), Bash(pre-commit *), Read, Glob, Grep, TodoWrite, AskUserQuestion |
| args | [--scope=all|registry|stack|agentic|runtime] [--fix] [--dry-run] [--verbose] |
| argument-hint | [--scope=all|registry|stack|agentic|runtime] [--fix] [--dry-run] [--verbose] |
| name | health-check |
Single entry point for Claude Code health diagnostics. Runs environment checks (plugin registry, settings, hooks, MCP servers, SessionStart executability, pre-commit validity, permissions coverage, marketplace enrollment) plus optional deeper audits, and routes --fix to the appropriate internal workflow.
| Use this skill when... | Use another approach when... |
|---|---|
| Running Claude Code diagnostics | Viewing raw settings (use Read on settings.json) |
| Troubleshooting plugin registry issues | Inspecting marketplace metadata manually |
| Auditing plugins for project fit | Installing a specific plugin (use /plugin install) |
| Checking skill agentic-optimisation quality | Editing a single known skill |
One-stop --fix across registry/stack/agentic | Precise surgical edits to a single file |
pwdfind . -maxdepth 2 -path '*/.claude/settings.json'find . -maxdepth 2 -path '*/.claude/settings.local.json'Parse these from $ARGUMENTS:
| Parameter | Description |
|---|---|
--scope=<all|registry|stack|agentic|runtime> | Which audits to run. Default all. |
--fix | Apply fixes to findings (prompts for confirmation). |
--dry-run | Preview fixes without modifying files. |
--verbose | Include detailed diagnostics. |
Scope semantics:
| Scope | Covers |
|---|---|
registry | Plugin registry health (orphaned projectPath, stale enabledPlugins, registry-vs-settings drift) |
stack | Enabled plugins vs detected project tech stack |
agentic | Skill/command/agent agentic-optimisation compliance |
runtime | ~/.claude.json bloat (dead projects[], dead githubRepoPaths[*], orphaned disabledMcpServers, duplicate MCP naming). Read-only audit. |
all | Environment checks + all four audits |
Execute this diagnostic router. Default scope is all when --scope is not provided.
Environment checks run regardless of --scope. They cover the baseline health of the Claude Code installation and the current project's .claude/ directory.
bash "${CLAUDE_SKILL_DIR}/scripts/check-plugins.sh" --home-dir "$HOME" --project-dir "$(pwd)"
bash "${CLAUDE_SKILL_DIR}/scripts/check-settings.sh" --home-dir "$HOME" --project-dir "$(pwd)"
bash "${CLAUDE_SKILL_DIR}/scripts/check-hooks.sh" --home-dir "$HOME" --project-dir "$(pwd)"
bash "${CLAUDE_SKILL_DIR}/scripts/check-mcp.sh" --home-dir "$HOME" --project-dir "$(pwd)"
Parse STATUS= and ISSUES: from each. Pass --verbose when set on $ARGUMENTS.
If check-settings.sh emits PROJECT_DIR_RESOLVED=<path>, the workspace root had no .claude/ but a single nested */.claude/settings.json was found one level down (parent-workspace / monorepo layout). Note the resolved path in the report so the user knows which config was checked. If it emits PROJECT_DIR_HINT=<msg>, surface the hint — multiple nested configs were found and the user should re-run with --project-dir to target one.
Check whether scripts/install_pkgs.sh (or any script registered in the SessionStart hook in .claude/settings.json) is executable and exits cleanly in both remote and local contexts.
SessionStart hook command from .claude/settings.json (look for the command field).CLAUDE_CODE_REMOTE=true bash <script-path>
CLAUDE_CODE_REMOTE=false bash <script-path>
If .pre-commit-config.yaml exists:
pre-commit validate-config .pre-commit-config.yaml
Report:
pre-commit not installed — skip check, suggest pip install pre-commitCompare tools referenced in project files against permissions.allow in .claude/settings.json.
permissions.allow from .claude/settings.json. Extract the command prefix from each Bash(<prefix>:*) entry.justfile / Justfile — commands on recipe linesMakefile — shell commands on recipe lines.pre-commit-config.yaml — entry: fieldsBash(<tool>:*) entry exists in permissions.allowBash(<tool>:*) entry in permissions.allow:
Scoring:
The local marketplace key (set by claude marketplace add <name>) is user-chosen and varies between installs (commonly laurigates-claude-plugins, sometimes claude-plugins). Identify the marketplace by its stable source.repo, not by a hardcoded local key.
.claude/settings.json.extraKnownMarketplaces and find the one whose source.repo equals "laurigates/claude-plugins". Capture that entry's key as $MP_KEY.enabledPlugins contains at least one key with the suffix @$MP_KEY.enabledPlugins has no @$MP_KEY entries (marketplace enrolled but no plugins enabled)extraKnownMarketplaces entry with source.repo = laurigates/claude-plugins (run /configure:claude-plugins --fix to add it)Reference jq snippet (for verification or fix scripts):
MP_KEY=$(jq -r '.extraKnownMarketplaces // {} | to_entries | map(select(.value.source.repo == "laurigates/claude-plugins")) | .[0].key // empty' .claude/settings.json)
if [ -z "$MP_KEY" ]; then
echo "ERROR: no extraKnownMarketplaces entry with source.repo = laurigates/claude-plugins"
else
jq -e --arg k "@$MP_KEY" '.enabledPlugins // {} | to_entries | map(select(.key | endswith($k))) | length > 0' .claude/settings.json >/dev/null \
&& echo "OK: marketplace enrolled as $MP_KEY with enabled plugins" \
|| echo "WARN: marketplace $MP_KEY enrolled but no @${MP_KEY} entries in enabledPlugins"
fi
For --scope=registry or all:
bash "${CLAUDE_PLUGIN_ROOT}/skills/health-plugins/scripts/check-registry.sh" \
--home-dir "$HOME" --project-dir "$(pwd)"
Parse STATUS=, PLUGIN_COUNT=, ORPHANED_ENTRIES=, STALE_ENABLED_ENTRIES=, and ISSUES:.
For --scope=stack or all: follow the tech-stack audit steps from the internal health-audit skill (see ${CLAUDE_PLUGIN_ROOT}/skills/health-audit/SKILL.md and its REFERENCE.md).
For --scope=agentic or all: follow the skill-quality audit steps from the internal health-agentic-audit skill (see ${CLAUDE_PLUGIN_ROOT}/skills/health-agentic-audit/SKILL.md and its REFERENCE.md).
For --scope=runtime or all:
bash "${CLAUDE_SKILL_DIR}/scripts/check-runtime.sh" --home-dir "$HOME" --project-dir "$(pwd)"
Parse STATUS=, RUNTIME_SIZE_BYTES=, PROJECTS_TOTAL=, PROJECTS_DEAD=, GH_PATHS_TOTAL=, GH_PATHS_DEAD=, ORPHAN_DISABLED_MCP=, DUPLICATE_MCP=, CLEANUP_SUGGESTED=, and ISSUES:. Pass --verbose to list every dead path / orphaned server (default is a single rolled-up issue per category to keep output compact).
The runtime scope audits ~/.claude.json — the harness state file that grows with every session and is never auto-pruned. It reports four classes of bloat: dead projects[] keys, dead githubRepoPaths[*] worktree paths, orphaned disabledMcpServers[] entries, and bare-vs-namespaced duplicate MCP names. The audit is read-only: it prints suggested jq filters for the operator to run manually after closing other Claude Code sessions.
Concurrent-write warning. The harness rewrites
~/.claude.jsonon session end. Before acting on the audit's suggested cleanups, close every other Claude Code session — otherwise the in-memory state of a live session will clobber your edits when it next writes the file. An automated cleanup writer is out of scope for this audit.
Print a consolidated report grouped by scope:
~/.claude.json size, dead projects/githubRepoPaths, orphaned disabledMcpServers, duplicate MCP naming (read-only — no --fix path)Use STATUS= indicators (OK/WARN/ERROR) and issue counts per scope. Include a summary table:
| Check | Status | Issues |
|---|---|---|
| Plugin registry | OK/WARN/ERROR | ... |
| Settings files | OK/WARN/ERROR | ... |
| Hooks configuration | OK/WARN/ERROR | ... |
| MCP servers | OK/WARN/ERROR | ... |
| SessionStart smoke test | OK/WARN/ERROR | ... |
| Pre-commit config | OK/WARN/ERROR/SKIP | ... |
| Permissions coverage | OK/WARN/ERROR | ... |
| Marketplace enrollment | OK/WARN/ERROR | ... |
| Registry audit | OK/WARN/ERROR | ... |
| Stack audit | OK/WARN/ERROR | ... |
| Agentic audit | OK/WARN/ERROR | ... |
| Runtime audit | OK/WARN/ERROR | ... |
See REFERENCE.md for the full report template.
--fix)If --fix is set:
If --scope=all AND findings exist in multiple scopes, use AskUserQuestion to let the user pick which scopes to fix (multi-select: registry, stack, agentic).
For each selected scope, delegate:
| Scope | Delegate to |
|---|---|
registry | bash "${CLAUDE_PLUGIN_ROOT}/skills/health-plugins/scripts/fix-registry.sh" --home-dir "$HOME" --project-dir "$(pwd)" (pass --dry-run when set) |
stack | Follow the --fix flow in ${CLAUDE_PLUGIN_ROOT}/skills/health-audit/SKILL.md (Step 6) |
agentic | Follow the --fix flow in ${CLAUDE_PLUGIN_ROOT}/skills/health-agentic-audit/SKILL.md (Step 6) |
Parse each script's output (STATUS=, REMOVED_COUNT=, MESSAGE=, RESTART_REQUIRED=) and report what changed.
If any fix reports RESTART_REQUIRED=true, remind the user to restart Claude Code.
Re-run the relevant checks and confirm issue counts have dropped.
| Context | Command |
|---|---|
| Full scan | /health:check |
| Registry only | /health:check --scope=registry |
| Stack relevance only | /health:check --scope=stack |
| Agentic audit only | /health:check --scope=agentic |
| Runtime state audit (~/.claude.json) | /health:check --scope=runtime |
| Fix everything (interactive) | /health:check --fix |
| Dry-run preview of fixes | /health:check --fix --dry-run |
| Detailed diagnostics | /health:check --verbose |
| Check plugin registry exists | find ~/.claude/plugins -name 'installed_plugins.json' |
| Validate settings JSON | find .claude -maxdepth 1 -name 'settings.json' |
| Smoke-test install script | CLAUDE_CODE_REMOTE=true bash scripts/install_pkgs.sh |
| Validate pre-commit config | pre-commit validate-config .pre-commit-config.yaml |
| Check marketplace enrollment | find .claude -maxdepth 1 -name 'settings.json' then grep for extraKnownMarketplaces |
| Issue | Symptom | Fix path |
|---|---|---|
| #14202 | Plugin shows "installed" but not active | /health:check --scope=registry --fix |
Stale enabledPlugins key in settings.json | Plugin appears enabled but no registry/marketplace entry | /health:check --scope=registry --fix |
Orphaned projectPath | Plugin installed for deleted project | /health:check --scope=registry --fix |
| Invalid settings JSON | Settings file won't load | /health:check |
| Missing marketplace enrollment | laurigates/claude-plugins skills unavailable in web sessions | /configure:claude-plugins --fix |
Refresh the plan to focus on the task at hand. Use when context grew, completed steps muddy it, or you want to clear context and continue in auto mode.
Sequential-wave dispatch for WO chains where output of one feeds the next, shared locks, or shared files prevent fan-out. Use when planning dependent multi-WO landings.
Publish npm packages built with Bun: package.json config, CLI tool packaging, provenance signing, release automation. Use when setting up `publishConfig`/`files`/`bin`, packaging a CLI, enabling `--provenance`, or wiring release-please.
Scaffold a new ComfyUI custom-node repo (TypeScript + bun build, CI, release-please, vitest+pytest) consuming @laurigates/comfy-modal-kit. Use when bootstrapping or init-ing a comfyui node pack.
Dispatch contract for spawning parallel agents covering worktree collisions, scope overflow, and silent exits. Use when fanning out concurrent agents or authoring a lead prompt.
Resume development from current project state. Use when the user asks to continue work, pick up where we left off, find the next task, or resume a TDD cycle after a break.