claude-code-notify

claude-code-notify

Smart desktop notifications for Claude Code. Get notified when Claude finishes responding — with session name, last message, and tmux context. Focus-aware: won't bother you if you're already looking.

What It Does

When Claude Code stops and is waiting for your input, you get a notification like:

(w:2) my-project
Fixed the authentication bug by updating the session config...

• Session name from /rename (falls back to directory name)
• Last message — first 80 chars of what Claude said
• tmux window index — so you know where to switch
• Focus-aware — no notification if you're already looking at the session

Install

As a Claude Code Plugin

# Clone the repo
git clone https://github.com/decko/claude-code-notify.git ~/.claude/plugins/claude-code-notify

# Enable in Claude Code
claude plugins add claude-code-notify

Manual

Copy hooks/stop-hook.sh and register in your ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/stop-hook.sh"
          }
        ]
      }
    ]
  }
}

Requirements

• jq — JSON parsing
• notify-send (Linux) or osascript (macOS) — notifications
• tmux (optional) — focus detection and window index
• bash 4+

Installing Dependencies

Fedora/RHEL:

sudo dnf install jq libnotify

Ubuntu/Debian:

sudo apt install jq libnotify-bin

macOS:

brew install jq
# osascript is built-in

Configuration

Set environment variables in your shell profile (.bashrc, .zshrc):

Variable	Default	Description
CLAUDE_NOTIFY_CONTEXT	false	Show [Work]/[Personal] prefix
CLAUDE_NOTIFY_URGENCY	normal	Urgency: low, normal, critical

Example:

export CLAUDE_NOTIFY_CONTEXT=true
export CLAUDE_NOTIFY_URGENCY=normal

Commands

Command	Description
/notify-help	Show configuration and status
/notify-test	Send a test notification

Use Cases

• Multi-session development in tmux — Running Claude in 3-4 tmux panes working on different tasks (tests, refactoring, docs). Get notified exactly when each session needs your attention, without constantly switching panes to check.

• Long-running operations — Kick off a complex task (large codebase refactor, test suite run, dependency upgrade) and switch to other work. The notification tells you when Claude is done and what it said.

• Code review while Claude works — Send Claude a task, switch to your browser to review a PR or read docs. The notification pops up when Claude needs your input, with enough context in the body to decide if it's urgent.

• Pair programming across projects — Working on a primary project while Claude handles a side task in another session. The window index in the notification (w:2) tells you exactly which tmux window to jump to.

• Meeting multitasking — Start a Claude task before a meeting, get a notification when it's done. Check it when the meeting ends.

Focus Detection

The plugin suppresses notifications when you're already looking at the Claude session:

Environment	Method	Notes
tmux	Pane + window + terminal focus	Best experience
macOS (no tmux)	Frontmost app check	Detects Terminal, iTerm2, kitty, etc.
Linux (no tmux)	Always notify	Wayland limits focus detection

How It Works

1. Claude Code fires the Stop hook when it finishes responding
2. The hook reads the payload (session ID, last message, transcript path)
3. Checks if the tmux pane is focused — skips notification if so
4. Resolves the session name from /rename history in the transcript
5. Sends a notification with session name and last message

Interaction with Other Plugins

If another Stop hook (like ralph-loop) continues the conversation, the stop_hook_active flag is set and this plugin skips the notification. Due to non-deterministic hook ordering, occasional false-positive notifications may occur when ralph-loop is active.

License

MIT