claude-code-alert

Desktop notification hook for Claude Code that alerts you when Claude needs attention — even when you're in another tmux window.

Features

• Terminal bell — fires on every notification for visual bell / tmux activity monitoring
• Desktop notification — notify-send popup with the project path and event type; per-pane deduplication using --replace-id so notifications update in place instead of stacking
• Sound alert — plays bell.oga via PulseAudio with a 3-second per-pane debounce
• tmux coordinates — notification title includes [session:window.pane] (e.g. [0:2.1]) so you know exactly which pane needs you

Notification types

Event	Title
Permission request	Permission Required [0:2.1]
Claude finished / idle	Claude Ready [0:2.1]
Elicitation dialog	Input Needed [0:2.1]
Auth complete	Auth Complete [0:2.1]

Setup

Tested on:

• Fedora 43 Sway Atomic (Wayland)
• tmux 3.5a with oh-my-tmux
• zsh 5.9 with oh-my-zsh

Dependencies:

jq            # JSON parsing
libnotify     # notify-send
pulseaudio    # paplay
tmux          # pane identification

Install on Fedora Atomic:

sudo rpm-ostree install jq libnotify pulseaudio-utils tmux

Install

git clone https://github.com/mzaran/claude-code-alert.git
cd claude-code-alert
bash install.sh

Then restart Claude Code.

Manual install

1. Copy notify.sh to ~/.claude/hooks/notify.sh and make it executable:

mkdir -p ~/.claude/hooks
cp notify.sh ~/.claude/hooks/notify.sh
chmod +x ~/.claude/hooks/notify.sh

2. Add to ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/notify.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

How it works

Claude Code fires a Notification hook event (as JSON on stdin) whenever it needs your attention. The hook:

1. Reads the JSON payload and maps notification_type to a human-readable title
2. Queries tmux for the current pane's coordinates (session:window.pane) using $TMUX_PANE
3. Fires a terminal bell (\a)
4. Sends a desktop notification via notify-send — the --replace-id is derived from the tmux pane number so multiple notifications from the same pane update in place
5. Plays a sound via paplay with a 3-second cooldown per pane to avoid audio spam