
plugin-diagnostics
Diagnostic plugin that reports why installed hooks and plugins fail to run, with remedies.
- GitHub stars
- 32
What it does
- Adds a
hook-failure-auditStop hook plus SessionStart notices for a missingnodeand 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
jqfor the audit andnodeonly 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-pluginsRun it inside Claude Code once, then install the plugin below.
Install
/plugin install plugin-diagnostics@melodic-softwareRun it inside Claude Code after adding the marketplace.
Files
Discovered from sourceReadme
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
| Hook | Event | Reports |
|---|---|---|
hook-failure-audit | Stop | a 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 notice | SessionStart | that node is not on PATH, so hooks that launch through node do not run, once per session |
| prerequisites notice | SessionStart | for 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-pluginsfor 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.
| Option | Type | Default | Description |
|---|---|---|---|
hook_failure_audit_enabled | boolean | true | Warns once per session per hook when the transcript records hook launch or exec failures Claude Code never surfaced. On by default. |
stdin_read_timeout | number min 1 | 2 | Idle 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:
- In a session or headless:
/pluginin a session orclaude plugin configure. The configure command is the preferred headless route in the plugin-reconfiguration convention, which records its limits. - By hand: under
pluginConfigsin your user settings.
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- plugin-profiles
- plugin-quality
- powershell-format
- prototype
- python-format
- rate-limit-guard
- rate-limits
- repo-fleet-hygiene
- repo-hygiene
- requirements-elicitationv1.0.0
- researchv1.0.0
- response-qualityv1.0.0
- retro-audio
- review
- ruff-format
- securityv1.0.0
- session-flow
- session-telemetry
- skill-quality
- soft-skillsv1.0.0
- songwriting
- source-control
- spec-driven-developmentv1.0.0
- speech
Similar to plugin-diagnostics
More Automation & Workflows
eccaffaan-m/everything-claude-code308.6K starsHarness-native ECC operator layer - 72 agents, 328 skills, 99 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready work
n8nn8n-io/n8n210.9K starsn8n Claude Code plugin — shared skills, commands, and agents for n8n development
hookifyanthropics/claude-code156.1K starsEasily create custom hooks to prevent unwanted behaviors by analyzing conversation patterns or from explicit instructions. Define rules via simple markdown file
claude-mem-coworkthedotmack/claude-mem118.9K starsClaude-Mem for Cowork (Claude app cloud sessions) - hooks stream tool use to cmem.ai and inject observations into new sessions and agents
ruview-liveruvnet/RuView104.5K starsClaude Code mod: /ruview opens a live pane with your CSI nodes (ESP32, Realtek) and ESPHome radar (presence, distance, device-reported vitals), refreshed on a t
claude-flowruvnet/ruflo82.2K starsEnterprise AI agent orchestration plugin with 150+ commands, 74+ specialized agents, SPARC methodology, swarm coordination, GitHub integration, and neural train