claude-code-plugins

Pre-computed context

check's node and jq probes and OS-family detection ran at load time. Read these rows instead
of re-issuing them. The node and jq rows show the tool's path, or absent when missing; the
uname -s row shows the kernel name, or unknown when it fails to run:

• node: !{ command -v node 2>/dev/null || echo "absent"; }
• jq: !{ command -v jq 2>/dev/null || echo "absent"; }
• uname -s: !{ uname -s 2>/dev/null || echo "unknown"; }

A row reading [shell command execution disabled by policy] carries no result: run that probe via
Bash instead.

Purpose

Thin check-centric setup per the uniform setup contract (docs/plugin-philosophy.md
"Setup is explicit and repeatable" in the marketplace repository): check inspects and
reports, apply resolves. This plugin owns no consumer-project configuration. The only
tunables are the four native userConfig toggles (master + one per channel), and every
remaining prerequisite is a system tool or an OS package. So apply is pure
guidance-and-verify with no write path: it installs nothing and edits nothing.

Action routing: no argument or check runs the check; apply runs the check first, then
offers the resolution for each finding. Both are non-interactive. Never prompt when the
action is given.

check (read-only)

The hook script and the shared library it sources are the single source of truth for what this
plugin requires and how it degrades: ${CLAUDE_PLUGIN_ROOT}/hooks/desktop-notification.sh and
${CLAUDE_PLUGIN_ROOT}/hooks/hook-utils.sh.

Read it first. Probe what it actually does, don't recite this file. Then read the pre-computed
node, jq and uname -s rows, run the remaining probes via Bash, and report a PASS/FAIL/INFO table with
one remediation line per FAIL. Do not modify anything.

When the plugin's toggle is disabled, every prerequisite absence downgrades from FAIL to
INFO. The hook exits through its enabled-gate before probing anything, so a deliberately
disabled plugin is not broken. Report the probes informationally and note that re-enabling
restores the FAIL semantics.

1. Bash version. Check ${BASH_VERSION} against the hook's documented floor (README
   Requirements: Bash 3.2+). INFO when below 5.0: EPOCHREALTIME is unset there, so the
   opt-in telemetry envelope is skipped while notifications still fire, a degrade, not a
   failure.
2. jq. The pre-computed jq row. FAIL if absent: without it the hook can neither classify the
   notification nor emit its terminal sequence, so it surfaces a systemMessage notice, once per session and
   agent and renewed every eighth skip, and drops every notification for the session.
3. Node.js. The pre-computed node row. FAIL if absent: every hook row launches through
   node hooks/exec-bash.mjs, and Claude Code's native binary neither ships nor uses Node, so
   without it the hook does not launch and no notification fires. The probe runs through the Bash
   tool, so it works when the launcher cannot. Remediation: install Node.js from
   https://nodejs.org/en/download, or from the platform package manager.
   Claim: Claude Code's native binary does not invoke Node at runtime, so Node is a separate
   prerequisite for a hook launched as node.
   Basis: https://code.claude.com/docs/en/setup, npm install section ("The installed claude
   binary does not itself invoke Node"), and https://code.claude.com/docs/en/hooks, "Exec form
   and shell form".
   As of: 2026-09-29.
   Recheck: the setup page stops saying the binary does not use Node, or the hooks page changes the
   exec-form node example.
4. Per-OS os_toast dependency. Take the current OS family from the pre-computed uname -s row
   and probe ONLY that family's requirement (the hook's case "$(uname -s)" does exactly this):
   • Linux. command -v notify-send (libnotify). FAIL only if the os_toast channel is
     enabled and it is absent; otherwise INFO. Absent → the os_toast channel is a
     documented silent no-op; remediation is the README's install hint (libnotify-bin on
     Debian/Ubuntu, libnotify on Fedora). The terminal channels are unaffected.
   • macOS (Darwin). INFO: osascript is built-in, no dependency. Note the first toast
     prompts to allow notifications for the terminal app.
   • Windows / other. INFO: the hook has no os_toast branch on this platform (a
     fire-and-forget process leaves no live activator host for a WinRT toast). The
     terminal_notify OSC 9 channel carries attention here; nothing to install.
5. Channel toggles. Report the effective value of all four native booleans (unexpanded
   or empty means the default true): master ${user_config.desktop_notification_enabled},
   ${user_config.desktop_notification_bell_enabled},
   ${user_config.desktop_notification_terminal_notify_enabled}, and
   ${user_config.desktop_notification_os_toast_enabled}. Call out when the master toggle is
   off (the whole hook is muted) or when the only channel that would fire on this OS is
   disabled.
6. Hook registration. INFO: confirm the plugin is enabled for this project
   (/plugin → Installed) rather than parsing settings files.

apply (idempotent)

Run check, then for each FAIL or actionable INFO offer the resolution. This skill installs
nothing and writes nothing, so every remediation is a pointer the user acts on:

• missing Node.js. https://nodejs.org/en/download or the platform package manager.
• missing jq / old Bash. The platform install instructions from the README Requirements
  section. This skill never installs system packages.
• missing notify-send (Linux, os_toast enabled). sudo apt install libnotify-bin
  (Debian/Ubuntu) or sudo dnf install libnotify (Fedora), per the README's per-OS table.
  Guidance only. The user runs it.
• a toggle is off. Reconfigure through Claude Code's native flow, per the marketplace's
  plugin-reconfiguration convention, which owns the verified-version record
  (https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/plugin-reconfiguration/README.md):
  interactive /plugin configure desktop-notification@<marketplace> any time, or headless
  claude plugin install desktop-notification@<marketplace> -s <scope> --config <key>=true
  (repeatable per key). Against an already-installed plugin it prints already installed and
  still writes the value. Do not uninstall to reconfigure: uninstalling drops this plugin's
  entire stored pluginConfigs entry, resetting every option in the README's Options reference
  to its manifest default. -s defaults to user; pass the install scope claude plugin list
  reports for this plugin, and run from that project's directory for a project/local scope.
  A rerun at another scope adds an install record at that scope and enables the plugin there
  (measured in both directions); the value itself always lands in user settings. A rejected value prints a warning yet
  exits 0, so read the output. These options are personal userConfig
  values, so this skill never writes user settings or pluginConfigs. Afterwards rerun check
  in a fresh session. The rendered ${user_config.*} is injected at skill load and each
  hook receives its CLAUDE_PLUGIN_OPTION_* from an environment fixed at session start, so a
  same-session check still reports the OLD value; report the observed effective value, never an
  unobserved change.

After the user reports acting on any system-tool remediation, re-run the relevant check
probe live via Bash (a pre-computed row predates the remediation) and report its actual
result. Never claim resolved on the user's say-so alone.
Re-running apply when everything already passes changes nothing and reports "already
configured".

What this skill does NOT do

• Install Node.js, jq, libnotify, or any system package. apply is guidance-and-verify with no
  write path.
• Fire a notification. A permission_prompt or idle_prompt exercises the hook end-to-end.
• Write the plugin cache, Claude Code user settings, or pluginConfigs. Nor the hook scripts.