New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Diagnostic plugin that reports why installed hooks and plugins fail to run, with remedies.

GitHub stars
32
View on GitHub

What it does

  • Adds a hook-failure-audit Stop hook plus SessionStart notices for a missing node and missing prerequisite tools
  • Classifies each failed hook as a launch failure, stale config, ambiguous, or completed non-zero exit, with a remedy
  • Warns once per session per failing hook registration, and re-warns when a new registration starts failing
  • Designed for users whose hooks fail silently, since it needs jq for the audit and node only for the prerequisites notice

Detects and reports why installed plugins cannot run: hooks that fail to launch, and missing runtimes or prerequisite tools.

Add marketplace

/plugin marketplace add melodic-software/claude-code-plugins

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install plugin-diagnostics@melodic-software

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Readme

plugin-diagnostics

Detects and reports why installed plugins cannot run: hooks that fail to launch, and missing runtimes or prerequisite tools. It is hooks only: no skills. It is on by default for a new install, and works whether or not any other plugin is enabled. If you already had this marketplace installed, updating it does not install plugin-diagnostics (ADR 0109, probe row default-on-existing-users): run claude plugin install plugin-diagnostics@melodic-software.

Contents

What it reports

HookEventReports
hook-failure-auditStopa hook that failed to launch or exited with a code other than 0 or 2, with its failure class and remedy, once per session per failing hook registration, as a systemMessage
node noticeSessionStartthat node is not on PATH, so hooks that launch through node do not run, once per session
prerequisites noticeSessionStartfor each enabled plugin whose prerequisites.json declares session_probe, the tools its hooks need that are missing, as one notice

The two session-start rows follow the prerequisites contract § Hook notices. The node notice runs under sh or PowerShell and needs no node; the prerequisites notice launches node through lib/node-or-skip.sh, so a machine without node gets the node notice and nothing else.

The hook-failure audit

Its user-facing systemMessage warning fires regardless of sink wiring (only its envelope needs a sink). A hook that fails to launch is a non-blocking error: the guarded tool call goes ahead unless the hook sets onFailure: "block". Claude Code shows a <hook name> hook error notice in the transcript on events such as PreToolUse, and the notice can cut stderr short. Claude Code 2.1.327 fixed failing hooks showing nothing for SubagentStop in background agents, SessionEnd at /clear and /resume, and CwdChanged and FileChanged in fullscreen (changelog). The hooks page does not list the notice per event, so the audit still reports what no notice shows:

  • a failure on an event that shows no notice, including a launch failure;
  • an exec-failure signature past the notice's cut, since the audit classifies the full stderr;
  • the failure's class and its remedy, such as /reload-plugins for stale config, which the notice does not give.

It runs once per Stop, tails a bounded window of the session transcript for hook_non_blocking_error attachments (structural match on the attachment type, never substring), and warns once per session per distinct failing hook registration, keyed on hookName plus the registered command because several plugins share an event and matcher, re-warning when a new registration starts failing. It lives in this plugin, not in the plugin it might report on, deliberately: an in-plugin detector shares its plugin's registration form and dies with it, which is exactly how disk-hygiene's guard monitor missed the #1416 incident class.

Each failure record is classed one of four ways, and the warning gives each class its own diagnosis and remedy:

  • launch failure: stderr carries an exec-failure signature; the hook never ran.
  • stale config: exit 127 and the whole stderr is bash's missing-script line (bash: <path>: No such file or directory). The session still runs hook config it loaded before a plugin update or an in-place edit deleted that script; the remedy is /reload-plugins, or a restart.
  • ambiguous: exit 126 or 127 with neither of the above, so the registered command and the hook's own commands are both suspects.
  • completed non-zero exit: the hook ran and failed.

Its budget share is stated as a process count, not a duration, and the host is the reason. The hook-budget convention states each always-on hook's budget as k x S plus measured work (k = fewest spawns, S = one no-op spawn's time), not a fixed millisecond figure, and on the host in #3508 one process creation costs 180-2,841 ms (median 1,108 ms at 501 concurrent processes), so the count is what decides whether the set fits and a duration measured anywhere else does not transfer. On a turn with no hook failure recorded, the common case, the hook costs 9 process creations and 4 program execs: one wc for the tail-cap decision, one grep pre-filter that opens the transcript directly, and two jq passes inside the synced hook-utils.sh. The creations above that are subshell forks inside the same shared library. It was 18 creations and 6 execs before #3512. Counts are measured with strace -ff -e trace=clone,clone3,fork,vfork,execve, not bash -x: a command substitution whose command carries its own redirection forks a subshell that xtrace cannot see, and those forks were most of the cost. hook-failure-audit.test.sh asserts both ceilings. Windows Git Bash, the host the convention binds to, measured S (the bash spawn floor) at 33 ms on 2026-09-30, through the bash the launcher spawns (20 ms on the PATH bash), but the hook-failure-audit wall there is still unmeasured for this row, so its spawn-equivalents (hook wall divided by the same-run S) are still owed.

The audit also emits the hook-telemetry envelope as hook-failure-audit, which reaches a sink only where one is wired, such as session-telemetry's.

Install

/plugin marketplace add melodic-software/claude-code-plugins
/plugin install plugin-diagnostics@melodic-software

Requirements

The hook-failure audit is a Bash script (Git Bash on native Windows) run in shell form, needing no node, and uses jq; without jq it skips its work. The prerequisites notice needs node and is skipped silently without it, since the node notice already says node is missing.

Configuration

hook_failure_audit_enabled (default on) switches the hook-failure audit off. stdin_read_timeout (seconds, default 2) is an idle bound on reading the hook payload, after which the audit skips.

Options reference

Generated from this plugin's .claude-plugin/plugin.json. For how Claude Code asks for these and hands them to the plugin, see User configuration.

OptionTypeDefaultDescription
hook_failure_audit_enabledbooleantrueWarns once per session per hook when the transcript records hook launch or exec failures Claude Code never surfaced. On by default.
stdin_read_timeoutnumber
min 1
2Idle bound on reading the hook payload from stdin: how long the pipe may go silent before the hook gives up and fails open. Default 2.

How to set these

Set the options above for plugin-diagnostics@<marketplace>, replacing <marketplace> with the marketplace you installed this plugin from:

Do not uninstall the plugin to reconfigure it: see What an uninstall deletes and keeps. For a Claude Code release without plugin configure, see Plugin install.

Upstream documentation

Details

Marketplace
melodic-software/claude-code-plugins
Source
plugins/plugin-diagnostics
Category
Claude Code

More from melodic-software/claude-code-plugins

All 139

Similar to plugin-diagnostics

More Automation & Workflows