npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@ruben0305-mint/claude-notifier

v0.1.0

Published

Zero-dependency native notifications for Claude Code hooks.

Readme

claude-notifier

License: MIT Node.js

Native desktop notifications for Claude Code, implemented as a small, zero-runtime-dependency Node.js hook.

Why?

Claude Code can spend minutes working while your terminal is in another window. claude-notifier lets you keep working and receive a native notification when Claude finishes, needs approval/input, or approaches a capacity limit.

┌───────────────┐   JSON/stdin   ┌─────────────────┐   native command   ┌─────────────┐
│ Claude Code   │ ──────────────▶ │ claude-notifier │ ─────────────────▶ │ OS desktop  │
│ Stop/Notify   │                 │ parse + route   │                    │ notification│
└───────────────┘                 └─────────────────┘                    └─────────────┘
                                        │
                                        └── critical alert once at ≤ 5%

Features

  • Completion notifications — receive Claude Code finished when a Stop hook fires.
  • Approval/input notifications — receive Claude Code needs your input for permission prompts and questions.
  • Rate-limit context — include the parsed remaining percentage in the final notification.
  • Critical threshold — send an urgent alert immediately when remaining capacity reaches 5% or less, with duplicate-alert suppression until recovery.
  • Native OS integrations — osascript (macOS), PowerShell Toast Notifications (Windows), and notify-send (Linux).
  • Safe installer — merge hooks into ~/.claude/settings.json without replacing unrelated settings or existing hooks.
  • No external runtime dependencies — only Node.js built-ins are used.

Requirements

  • Node.js 18 or newer.
  • Claude Code with command hooks enabled.
  • Linux: notify-send from libnotify.
  • Windows: PowerShell with Windows Runtime toast APIs (Windows 10/11).
  • macOS: osascript (included with macOS).

Quick start

From a clone of this repository:

npm install
node install.js

The installer is idempotent. It adds these commands to your Claude Code settings:

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "claude-notifier hook" }] }],
    "Notification": [{ "hooks": [{ "type": "command", "command": "claude-notifier hook" }] }]
  }
}

On macOS/Linux, the shell wrapper is also available:

./install.sh

If the package is installed globally, use the executable directly:

claude-notifier hook

Supported payloads

Claude Code sends hook data on stdin. The parser accepts JSON objects, JSON strings, buffers, and selected text forms. It intentionally only interprets explicit remaining-capacity fields; arbitrary fields such as tokens: 4 are ignored.

Examples that are recognized:

{ "rate_limit_remaining_percent": 82 }
{ "usage": { "rateLimit": { "remainingPercent": 41 } } }
{ "creditsRemaining": 0.05 }
Rate Limit remaining: 4%

Values between 0 and 1 are treated as fractions (0.05 → 5%); values between 0 and 100 are treated as percentages. Values are clamped to 0–100. Unknown or malformed payloads are ignored safely.

Important: Claude Code hook payloads do not universally expose a live rate-limit stream. The percentage is shown only when the incoming hook payload contains a supported metric. claude-notifier never calls an Anthropic API and never invents a percentage.

Notification behavior

| Event | Notification | | --- | --- | | Stop with 82% remaining | Claude Code finished • Rate Limit remaining: 82% | | Permission/input notification | Claude Code needs your input | | Any event crossing into ≤ 5% | ⚠️ Attention: only 4% of Rate Limit / credits available! |

Critical alerts are emitted once while capacity is critical. After a later observation above 5%, the alert is re-armed for the next critical crossing.

Development

npm test
npm run build
node bin/claude-notifier.js --version

The test suite uses Node's built-in node:test runner and injects process/filesystem boundaries, so tests do not send real notifications or modify your Claude settings.

Project modules:

Security and privacy

  • No network requests are made.
  • Payloads are read from stdin and are not persisted by this project.
  • Notification text is passed as process arguments; it is not evaluated as a shell command.
  • The installer writes only the selected Claude settings file and preserves existing JSON keys.
  • Review hook payloads before enabling third-party hooks in a shared or managed environment.

Troubleshooting

No Linux notification appears

Install notify-send and verify it independently:

notify-send "Claude Code" "Test notification"

Windows toast does not appear

Run PowerShell with the same user account and verify that Windows notifications are enabled for PowerShell. The command uses -NoProfile and does not require a PowerShell profile.

The final message says unknown

The hook payload did not include a recognized remaining-capacity field. Add or preserve one of the documented fields in the integration that supplies the payload; this project does not infer a rate limit from unrelated token counts.

Existing hooks were not replaced

That is intentional. The installer appends only the claude-notifier hook command when it is not already present.

Contributing

  1. Fork the repository and create a focused branch.
  2. Keep the zero-dependency runtime constraint.
  3. Add a failing node:test test before changing behavior.
  4. Run npm test, npm run build, and git diff --check.
  5. Open a pull request describing the payload shape and platforms tested.

Bug reports should include Node.js version, OS, Claude Code hook event name, and a redacted example payload. Never include API keys, private prompts, or sensitive project content.

License

MIT © 2026 claude-notifier contributors. See LICENSE.