@landienzla/claude-code-notify 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "@landienzla/claude-code-notify",
+  "version": "1.0.0",
+  "description": "Cross-platform desktop notifications when Claude Code needs your attention",
+  "license": "MIT",
+  "keywords": ["notifications", "desktop", "hooks", "cross-platform"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Talha (landienzla@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# claude-code-notify
+
+Cross-platform desktop notifications for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Get notified when Claude Code needs your attention — permission approval, task completion, idle prompts, and more.
+
+Works as a **Claude Code plugin** (zero config) or as a **CLI setup tool**.
+
+## Platforms
+
+| Platform | Method | Sound |
+|----------|--------|-------|
+| Windows | Toast notification (slides in from right) | Silent |
+| macOS | Native notification center | Default |
+| Linux | `notify-send` (libnotify) | Default |
+| WSL | Windows toast via PowerShell | Silent |
+
+## Quick Start
+
+```bash
+npx @landienzla/claude-code-notify setup
+```
+
+Done. Restart Claude Code and you'll get desktop notifications.
+
+## Installation
+
+### Option 1: CLI Setup
+
+```bash
+npx @landienzla/claude-code-notify setup
+```
+
+This installs the notification script to `~/.claude/scripts/` and adds a `Notification` hook to `~/.claude/settings.json`. Your existing settings are preserved.
+
+### Option 2: Plugin Mode
+
+Install globally:
+
+```bash
+npm install -g @landienzla/claude-code-notify
+claude --plugin-dir $(npm root -g)/@landienzla/claude-code-notify
+```
+
+Or per-project:
+
+```bash
+npm install @landienzla/claude-code-notify
+claude --plugin-dir ./node_modules/@landienzla/claude-code-notify
+```
+
+Plugin mode requires no changes to your `settings.json` — the hook is loaded automatically via the plugin system.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `claude-code-notify setup` | Install notification hook into `~/.claude/` |
+| `claude-code-notify test` | Send a test notification |
+| `claude-code-notify uninstall` | Remove notification hook and script |
+| `claude-code-notify help` | Show usage info |
+
+## How It Works
+
+Claude Code fires a [`Notification`](https://docs.anthropic.com/en/docs/claude-code/hooks) hook whenever it needs your attention. This package provides a handler that:
+
+1. Reads the notification context (JSON via stdin)
+2. Extracts the message (e.g. "Waiting for permission to edit file.py")
+3. Detects your OS
+4. Sends a native desktop notification with the contextual message
+
+### Notification Events
+
+The hook fires on all notification types:
+
+- **Permission prompts** — Claude needs approval to run a tool
+- **Idle prompts** — Claude is done and waiting for input
+- **Auth events** — Authentication completed
+- **Elicitation dialogs** — Claude is asking a question
+
+## Requirements
+
+- **Python 3** — used for JSON parsing (available by default on macOS/Linux)
+- **Linux:** `libnotify-bin` for `notify-send`
+  ```bash
+  # Debian/Ubuntu
+  sudo apt install libnotify-bin
+
+  # Fedora
+  sudo dnf install libnotify
+
+  # Arch
+  sudo pacman -S libnotify
+  ```
+- **macOS:** Your terminal app may need notification permission in System Settings > Notifications
+- **Windows/WSL:** PowerShell (included with Windows)
+
+## Uninstall
+
+**CLI mode:**
+
+```bash
+npx @landienzla/claude-code-notify uninstall
+```
+
+**Plugin mode:** Remove the `--plugin-dir` flag from your Claude Code command.
+
+## Troubleshooting
+
+**Notifications not appearing on Windows/WSL:**
+- Ensure Focus Assist / Do Not Disturb is off
+- Check Windows Settings > System > Notifications
+
+**Notifications not appearing on macOS:**
+- Go to System Settings > Notifications > [Your Terminal App] > Allow Notifications
+
+**Notifications not appearing on Linux:**
+- Install `libnotify-bin` (see Requirements)
+- Ensure a notification daemon is running (e.g. `dunst`, `mako`, GNOME/KDE built-in)
+
+**Generic "Needs your attention" message instead of context:**
+- Ensure Python 3 is installed and on your PATH
+
+## License
+
+[MIT](LICENSE)

package/bin/cli.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+const SETTINGS_PATH = path.join(CLAUDE_DIR, 'settings.json');
+const SCRIPTS_DIR = path.join(CLAUDE_DIR, 'scripts');
+const NOTIFY_DEST = path.join(SCRIPTS_DIR, 'notify.sh');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const NOTIFY_SRC = path.join(PACKAGE_ROOT, 'hooks', 'scripts', 'notify.sh');
+
+const HOOK_CONFIG = {
+  Notification: [
+    {
+      matcher: '',
+      hooks: [
+        {
+          type: 'command',
+          command: `bash "${NOTIFY_DEST.replace(/\\/g, '/')}"`,
+          timeout: 10
+        }
+      ]
+    }
+  ]
+};
+
+function setup() {
+  if (!fs.existsSync(CLAUDE_DIR)) {
+    console.error(`Error: ${CLAUDE_DIR} does not exist. Is Claude Code installed?`);
+    process.exit(1);
+  }
+
+  // Copy notify.sh
+  fs.mkdirSync(SCRIPTS_DIR, { recursive: true });
+  fs.copyFileSync(NOTIFY_SRC, NOTIFY_DEST);
+  fs.chmodSync(NOTIFY_DEST, 0o755);
+  console.log(`  Copied notify.sh -> ${NOTIFY_DEST}`);
+
+  // Merge hook into settings.json
+  let settings = {};
+  if (fs.existsSync(SETTINGS_PATH)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+    } catch (e) {
+      const backup = SETTINGS_PATH + '.backup.' + Date.now();
+      fs.copyFileSync(SETTINGS_PATH, backup);
+      console.log(`  Warning: settings.json was invalid, backup saved to ${backup}`);
+      settings = {};
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  settings.hooks.Notification = HOOK_CONFIG.Notification;
+
+  fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+  console.log(`  Updated ${SETTINGS_PATH}`);
+
+  console.log('\nDone! Restart Claude Code for notifications to take effect.');
+}
+
+function uninstall() {
+  if (fs.existsSync(SETTINGS_PATH)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+      if (settings.hooks && settings.hooks.Notification) {
+        delete settings.hooks.Notification;
+        if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+        fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+        console.log(`  Removed Notification hook from ${SETTINGS_PATH}`);
+      } else {
+        console.log('  No Notification hook found in settings.');
+      }
+    } catch (e) {
+      console.error(`  Error reading ${SETTINGS_PATH}: ${e.message}`);
+    }
+  }
+
+  if (fs.existsSync(NOTIFY_DEST)) {
+    fs.unlinkSync(NOTIFY_DEST);
+    console.log(`  Removed ${NOTIFY_DEST}`);
+  }
+
+  console.log('\nDone! Restart Claude Code to apply changes.');
+}
+
+function test() {
+  const input = JSON.stringify({ notification_message: 'Test notification from claude-code-notify' });
+  try {
+    execSync(`echo '${input}' | bash "${NOTIFY_SRC}"`, { stdio: 'inherit', timeout: 15000 });
+    console.log('Test notification sent!');
+  } catch (e) {
+    console.error('Test failed:', e.message);
+    process.exit(1);
+  }
+}
+
+function help() {
+  console.log(`
+claude-code-notify - Desktop notifications for Claude Code
+
+Usage:
+  claude-code-notify setup       Install notification hook into ~/.claude/
+  claude-code-notify uninstall   Remove notification hook from ~/.claude/
+  claude-code-notify test        Send a test notification
+  claude-code-notify help        Show this help
+
+Plugin mode (no setup needed):
+  claude --plugin-dir /path/to/node_modules/claude-code-notify
+`);
+}
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'setup':    setup(); break;
+  case 'uninstall': uninstall(); break;
+  case 'test':     test(); break;
+  case 'help': case '--help': case '-h': case undefined: help(); break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    help();
+    process.exit(1);
+}

package/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "description": "Desktop notification hook — sends native OS notifications when Claude Code needs attention",
+  "hooks": {
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/notify.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/scripts/notify.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Cross-platform desktop notification for Claude Code
+# Reads hook JSON from stdin, extracts notification message, sends native OS notification
+
+INPUT=$(cat)
+
+# Parse JSON with python3 to extract the notification message
+MESSAGE=$(echo "$INPUT" | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+message = data.get('notification_message', data.get('message', 'Needs your attention'))
+for old, new in [('&','&amp;'),('<','&lt;'),('>','&gt;'),('\"','&quot;')]:
+    message = message.replace(old, new)
+print(message)
+" 2>/dev/null)
+
+# Fallback if python3 parsing fails
+MESSAGE="${MESSAGE:-Needs your attention}"
+
+# Detect OS and send notification
+case "$(uname -s)" in
+  Linux*)
+    if grep -qi microsoft /proc/version 2>/dev/null; then
+      # WSL — use Windows toast notification
+      powershell.exe -Command "
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > \$null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] > \$null
+\$xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+\$xml.LoadXml('<toast><visual><binding template=\"ToastText01\"><text id=\"1\">$MESSAGE</text></binding></visual><audio silent=\"true\"/></toast>')
+\$toast = New-Object Windows.UI.Notifications.ToastNotification \$xml
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Claude Code').Show(\$toast)
+" 2>/dev/null
+    else
+      # Native Linux
+      notify-send "Claude Code" "$MESSAGE" --app-name="Claude Code" 2>/dev/null || true
+    fi
+    ;;
+  Darwin*)
+    # macOS
+    ESCAPED=$(echo "$MESSAGE" | sed 's/\\/\\\\/g; s/"/\\"/g')
+    osascript -e "display notification \"$ESCAPED\" with title \"Claude Code\"" 2>/dev/null || true
+    ;;
+  CYGWIN*|MINGW*|MSYS*)
+    # Native Windows (Git Bash / MSYS2)
+    powershell.exe -Command "
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > \$null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] > \$null
+\$xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+\$xml.LoadXml('<toast><visual><binding template=\"ToastText01\"><text id=\"1\">$MESSAGE</text></binding></visual><audio silent=\"true\"/></toast>')
+\$toast = New-Object Windows.UI.Notifications.ToastNotification \$xml
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Claude Code').Show(\$toast)
+" 2>/dev/null
+    ;;
+esac
+
+exit 0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@landienzla/claude-code-notify",
+  "version": "1.0.0",
+  "description": "Cross-platform desktop notifications for Claude Code — plugin and CLI setup tool",
+  "author": "Talha <landienzla@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/landienzla/claude-code-notify"
+  },
+  "bugs": {
+    "url": "https://github.com/landienzla/claude-code-notify/issues"
+  },
+  "homepage": "https://github.com/landienzla/claude-code-notify#readme",
+  "bin": {
+    "claude-code-notify": "./bin/cli.js"
+  },
+  "files": [
+    ".claude-plugin/",
+    "hooks/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude-code",
+    "claude",
+    "plugin",
+    "notifications",
+    "desktop-notifications",
+    "hooks",
+    "toast",
+    "macos",
+    "windows",
+    "linux",
+    "wsl"
+  ]
+}