Claude Code Browser Notification Extension

Get browser notifications when Claude Code (CLI) needs your input, permission approval, or has finished a task.

Installation

Quick Install (Recommended)

Run this one-liner to automatically set up everything:

curl -fsSL https://raw.githubusercontent.com/MaximilianMauroner/claude-code-notify/main/install.sh | bash

What this does:

1. Clones the repository to ~/.claude/claude-code-notify
2. Builds the notification server
3. Makes hook scripts executable
4. Configures Claude Code hooks in ~/.claude/settings.json. Re-running replaces this installer's hooks and leaves every other hook in place.

Requirements: git, node, npm

Install the Browser Extension

Install the extension from your browser's store:

Chrome / Chromium / Brave

Install from the Chrome Web Store (search for "Claude Code Notify")

Firefox

Install from Firefox Add-ons (search for "Claude Code Notify")

Verify Installation

1. Click the extension icon in your browser - it should show "Connected"
2. Start Claude Code and interact until it needs input or finishes a task
3. You should see a browser notification

Uninstall

To remove the extension completely:

~/.claude/claude-code-notify/uninstall.sh

This removes the hooks from settings, stops the server, and deletes the installation directory. You'll need to manually remove the browser extension.

---

Manual Installation

If you prefer to set things up manually or want to understand what the install script does:

1. Clone the Repository

git clone https://github.com/MaximilianMauroner/claude-code-notify.git ~/.claude/claude-code-notify

2. Build the Server

cd ~/.claude/claude-code-notify/server
npm install
npm run build

3. Make Scripts Executable

chmod +x ~/.claude/claude-code-notify/hooks/notify.sh
chmod +x ~/.claude/claude-code-notify/hooks/ensure-server.sh
node -p 'process.execPath' > ~/.claude/claude-code-notify/hooks/node-path

The hook runs that recorded binary. Claude Code does not put node on the hook PATH.

4. Configure Claude Code Hooks

Add the following to your ~/.claude/settings.json (create it if it doesn't exist). The installer writes the same fields with the script path quoted absolutely.

PermissionRequest fires when Claude asks to use a tool. matcher "" matches every tool. The hook is async, so it does not block the prompt, and it prints no decision, so it never allows or denies. onFailure is continue, so a failed hook does not deny the request. timeout is seconds. Claude Code does not enforce it while async is true.

Notification uses the same empty matcher, which matches every notification type, including types added later. Stop has no matcher: that event does not support one.

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME/.claude/claude-code-notify/hooks/notify.sh\"",
            "timeout": 15,
            "async": true,
            "onFailure": "continue"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME/.claude/claude-code-notify/hooks/notify.sh\"",
            "timeout": 15,
            "async": true,
            "onFailure": "continue"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME/.claude/claude-code-notify/hooks/notify.sh\"",
            "timeout": 15,
            "async": true,
            "onFailure": "continue"
          }
        ]
      }
    ]
  }
}

5. Install the Browser Extension

Install from the Chrome Web Store or Firefox Add-ons (search for "Claude Code Notify").

---

Architecture

┌─────────────────┐     HTTP POST      ┌─────────────────┐     WebSocket     ┌─────────────────┐
│  Claude Code    │ ─────────────────► │  Local Server   │ ◄───────────────► │ Browser Extension│
│  (with hooks)   │                    │  (Node.js)      │                   │  (Chrome/Firefox)│
└─────────────────┘                    └─────────────────┘                   └─────────────────┘

1. Claude Code Hooks - Send HTTP requests when events occur
2. Local WebSocket Server - Receives hook events, broadcasts to browser
3. Browser Extension - Connects to server, shows notifications

Notification Types

Permission alerts come from PermissionRequest, which runs when Claude asks to use a tool. The credit for that alert is stored only after the notification server accepts it. Each delivered PermissionRequest then consumes one following permission_prompt for the same session within 15 seconds. Unused credits expire after 15 seconds and are cleared when Stop ends the turn. A permission_prompt with no remaining credit, including a sandboxed command's network request, is still delivered.

Every other Notification type is delivered. A type this version does not know about still shows a generic "Claude Code" notification. When Claude includes a message, that text is shown instead of the default.

This is the beginning of the README. Read the rest at the original. Read the full README ↗