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

@delorenj/claude-notifications

v2.1.0

Published

Delightful Notification for Claude Code

Downloads

357

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

lasertoastlasertoast

Keywords

claude-codenotificationsadhdaudiodesktop-notificationslinuxproductivitycli

Readme

Claude Notifications 🔔

Delightful audible notifications for Claude Code. Never alt+tab back to disappointment, thinking it was cranking away for 30-minutes on your task only to see a "Just double checking - you cool with this plan? Y/n"

Notification bar as seen in Ubuntu

⚡ Super Quick Install

npm install -g @delorenj/claude-notifications
claude-notifications install

Step 1 installs the CLI and generates sound assets. Step 2 opens an interactive selector that:

  • 🔎 Detects every supported agent CLI on your $PATH (Claude Code, Opencode, Gemini, Auggie, Copilot, Kimi, Vibe, Codex)
  • ☑️ Lets you toggle which ones should receive notification hooks
  • 🪝 Writes a marker-tagged hook block into each selected CLI's config (idempotent — re-running is safe)
  • 🚫 Shows unsupported CLIs disabled with a reason rather than silently skipping them

Hook installation no longer runs automatically on npm install — it's an explicit, opt-in step so you stay in control of what gets written to your agent configs.

Features

  • 🎵 Final Fantasy Dream Harp - Classic C-D-E-G ascending/(optional)descending pattern
  • 🔔 Service Desk Bell - Optional short, crisp bell sound for a quick "done!" signal
  • 🔊 Cross-Platform Audio - Works on Linux and macOS
  • 🖥️ Desktop Notifications - Visual notifications with Claude Code branding (optional)
  • 🎨 Zellij Visual Notifications - Beautiful animated pane borders and status bar notifications
  • 🪝 Auto-Integration - Automatically configures Claude Code hooks
  • ⚡ Zero Configuration - Works out of the box
  • 🌐 Webhook Support - Trigger a webhook in addition to or instead of the sound
  • 🎨 Customizable - Easy to modify sounds and settings

Usage

After installation, Claude Code will begin notifying you when it finishes or is waiting on your response.

Manual Commands

# Interactive hook installer (TUI)
claude-notifications install

# Scripted install for specific CLIs (skips the TUI)
claude-notifications install --non-interactive --cli=claude-code

# Preview changes without writing
claude-notifications install --dry-run --cli=claude-code

# Show which CLIs are detected and whether hooks are installed
claude-notifications status
claude-notifications status --json

# Cleanly remove everything this package installed
claude-notifications uninstall

# Regenerate sound assets only
claude-notifications sounds

# Trigger notification manually
claude-notify
claude-notify --bell

# Test the system
claude-notifications test
claude-notifications test-bell

# Full flag reference
claude-notifications help

Adding support for another agent CLI

Each supported CLI is a module under lib/adapters/<id>.js exporting this shape:

{
  id, label, binary, supportsHooks,
  detect(deps), configPath(), install(ctx), uninstall(ctx), status(ctx)
}

To add a new adapter:

  1. Copy lib/adapters/claude-code.js as a starting point (for hook-capable CLIs) or lib/adapters/_stub.js::createStubAdapter({...}) (for CLIs whose hook API you haven't verified yet).
  2. Implement install / uninstall using the upsertByMarker / removeByMarker helpers from lib/adapters/index.js so the entry is idempotent and cleanly removable.
  3. Register the module by appending a require() line to the adapterFactories array in lib/adapters/index.js.
  4. Add a test under test/adapters/<id>.test.js following the pattern in test/adapters/claude-code.test.js.

The TUI and status commands pick up the new adapter automatically.

Zellij CLI

The package also includes zellij-notify for programmatic control:

# Send notification to current tab
zellij-notify "Build complete!"

# Send to specific tab by index
zellij-notify -i 2 "Backend tests passed"

# Quick 5-second notification
zellij-notify -q "Deployment started"

# Dismissable alert (requires Ctrl+N to clear)
zellij-notify -d -t error "Review required"

# Broadcast to all tabs
zellij-notify -a "System maintenance in 5 minutes"

# Full help
zellij-notify --help

See ZELLIJ-NOTIFY.md for complete CLI documentation.

The Sound

  • Pattern: C1-D1-E1-G1-C2-D2-E2-G2-C3-G2-E2-D2-C2-G1-E1-D1-C1
  • Duration: ~2 seconds of dreamy notes

How It Works

The package automatically:

  1. Detects Claude Code - Finds your Claude Code configuration
  2. Adds Stop Hook - Configures the notification trigger
  3. Creates Sound - Generates the sound using sox
  4. Sets Up Commands - Installs claude-notify globally

Claude Code Integration

The installer automatically adds this to your Claude Code settings:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "claude-notify"
          }
        ]
      }
    ]
  }
}

Requirements

  • Node.js 14+ (you probably have this if you use Claude Code)
  • Linux or macOS (Windows support coming soon)
  • Audio system (PulseAudio, ALSA, or CoreAudio)

Auto-Installed Dependencies

The package will automatically install:

  • sox for sound generation (Linux: apt/dnf, macOS: brew)
  • node-notifier for desktop notifications

Customization

Change the Sound

Replace the generated sound file:

# Find the sound file
ls ~/.local/share/sounds/claude-notification.wav

# Replace with your own
cp your-custom-sound.wav ~/.local/share/sounds/claude-notification.wav

Zellij Visual Notifications

If you're using Zellij as your terminal multiplexer, claude-notifications can send visual notifications directly to your Zellij panes with animated borders, status bar indicators, and tab badges.

Setup:

  1. Install the Zellij plugin:

    # The plugin should be installed at:
~/.config/zellij/plugins/zellij_visual_notifications.wasm

  2. Add to your Zellij layout:

    layout {
    pane
    pane size=1 {
        plugin location="file:~/.config/zellij/plugins/zellij_visual_notifications.wasm" {
            enabled true
            theme "catppuccin"  // or dracula, nord, tokyo-night, etc.
            show_status_bar true
            show_border_colors true
            animation_enabled true
        }
    }
}

  3. Configure in settings.json:

    {
  "zellijVisualization": {
    "enabled": true,
    "pluginName": "zellij_visual_notifications",
    "notificationType": "attention",
    "title": "Claude Code",
    "message": "Waiting for you...",
    "priority": "high"
  }
}

Visual Features:

  • 🎨 Animated Pane Borders - Pulsing colors based on notification type
  • 📊 Status Bar Widget - Shows active notifications with icons
  • 🏷️ Tab Badges - Visual indicators on tabs with active notifications
  • ⌨️ Keyboard Control - Press Ctrl+N to clear notifications
  • 🎭 10+ Themes - Catppuccin, Dracula, Nord, Tokyo Night, and more
  • ♿ Accessibility - Pattern-based indicators for color-blind users

Notification Types:

  • ✅ success - Green pulsing border (build passed, tests succeeded)
  • ❌ error - Red pulsing border (build failed, errors found)
  • ⚠️ warning - Yellow pulsing border (warnings, deprecated APIs)
  • ℹ️ info - Blue pulsing border (general information)
  • 👁️ attention - Purple pulsing border (Claude waiting for input)

Configure Webhooks

You can configure a webhook to be triggered when a notification occurs. This is useful for integrating with other services, such as IFTTT, Zapier, or a custom server.

Create a configuration file at ~/.config/claude-notifications/settings.json.

Example settings.json:

{
  "sound": true,
  "soundType": "claude-notification",
  "desktopNotification": false,
  "webhook": {
    "enabled": true,
    "url": "https://maker.ifttt.com/trigger/claude_notification/with/key/YOUR_KEY",
    "replaceSound": false
  }
}

Configuration Options:

  • sound: (boolean) Whether to play notification sounds. Defaults to true.
  • soundType: (string) Which sound to play. Available options:
    • "claude-notification" - Final Fantasy dream harp (default)
    • "claude-notification-bell" - Service desk bell
  • desktopNotification: (boolean) Whether to show desktop notification banners. Defaults to false.
  • zellijVisualization.enabled: (boolean) Whether to send visual notifications to Zellij. Defaults to true when inside Zellij.
  • zellijVisualization.pluginName: (string) Name of the Zellij plugin to send notifications to. Defaults to "zellij_visual_notifications".
  • zellijVisualization.notificationType: (string) Type of notification to send. Options: success, error, warning, info, attention, progress. Defaults to "attention".
  • zellijVisualization.title: (string) Notification title. Defaults to "Claude Code".
  • zellijVisualization.message: (string) Notification message. Defaults to "Waiting for you...".
  • zellijVisualization.priority: (string) Notification priority. Options: low, normal, high, critical. Defaults to "high".
  • webhook.enabled: (boolean) Whether to trigger the webhook. Defaults to false.
  • webhook.url: (string) The URL to send the POST request to.
  • webhook.replaceSound: (boolean) If true, the sound will not play when a webhook is triggered. Defaults to false.

The webhook will be sent as a POST request with a JSON payload:

{
  "message": "Claude is waiting for you..."
}

Sound Files

Sound files are stored in ~/.config/claude-notifications/sounds/ and can be customized by replacing the .wav files in that directory.

Create Custom Patterns

Use sox to create new victory fanfares:

Note: Previously, a tedious chore I wouldn't recommend to a sane person. But now that we live in a fictional Blade Runner, Cyberpunk-inspired alternate timeline, just ask your robot buddy to do it!

# Simple ascending scale
sox -n custom.wav synth 0.1 sine 261.63 : synth 0.1 sine 293.66 : synth 0.1 sine 329.63

# Your imagination is the limit!

Troubleshooting

No Sound?

# Test your audio system
paplay /usr/share/sounds/alsa/Front_Left.wav  # Linux
afplay /System/Library/Sounds/Glass.aiff      # macOS

# Reinstall
claude-notifications install

No Notification?

# Test manually
claude-notify

# Check Claude Code config
claude-notifications install  # Will show config location

Command Not Found?

# Reinstall globally
npm install -g @delorenj/claude-notifications

# Or use npx
npx @delorenj/claude-notifications test

Uninstall

npm uninstall -g @delorenj/claude-notifications

The uninstaller will clean up sound files and notify you about manual config cleanup.

Development

Local Development

git clone https://github.com/delorenj/claude-notifications.git
cd claude-notifications
npm link
claude-notifications install

Publishing

npm version patch
npm publish

Contributing

PRs welcome! Especially for:

  • Windows support
  • More sound patterns
  • Better Claude Code detection
  • macOS improvements

License

MIT License - Make it your own! 🎵

Ready to level up your Claude Code experience?

npm install -g @delorenj/claude-notifications

Made with ❤️ for fellow developers of the world over. but mostly for me, who alt-tabs away into the night leaving techno-breadcrumb trails of unanswered and unfinished Claude Code tasks.

🎮✨ Enjoy! ✨🎮