Claude Notifications (plugin)

Smart notifications for Claude Code with click-to-focus, git branch display, and webhook integrations.

Boost your productivity — check out the advanced task manager for Claude with a convenient UI, from the creator of this plugin.

Features

Cross-platform: macOS (Intel & Apple Silicon), Linux (x64 & ARM64), Windows 10+ (x64)
6 notification types: Task Complete, Review Complete, Question, Plan Ready, Session Limit, API Error
Click-to-focus (macOS, Linux): click notification to focus the exact project window and tab — Ghostty, VS Code, iTerm2, Warp, kitty, WezTerm, Alacritty, Hyper, Apple Terminal, GNOME Terminal, Konsole, Tilix, Terminator, XFCE4 Terminal, MATE Terminal
Multiplexers: tmux (including iTerm2 -CC integration mode), zellij, WezTerm, kitty — click switches to the correct session/pane/tab
Git branch in title: ✅ Completed main [cat]
Sounds: MP3/WAV/FLAC/OGG/AIFF, volume control, audio device selection
Webhooks: Slack, Discord, Telegram, Lark/Feishu, Microsoft Teams, ntfy.sh, PagerDuty, Zapier, n8n, Make, custom — with retry, circuit breaker, rate limiting (docs)
Plugin compatibility: works with double-shot-latte and other plugins that spawn background Claude instances

Installation

Prerequisites

Claude Code
Windows users: Git Bash (included with Git for Windows)
macOS/Linux users: No additional software required

Quick Install (Recommended)

One command to install everything:

curl -fsSL https://raw.githubusercontent.com/777genius/claude-notifications-go/main/bin/bootstrap.sh | bash

Windows users: run this from Git Bash. If you run it from PowerShell and bash opens WSL, the installer would target Linux paths and binaries instead of Windows.

Then restart Claude Code and optionally run /claude-notifications-go:settings to configure sounds.

The binary is downloaded once and cached locally. You can re-run /claude-notifications-go:settings anytime to reconfigure.

If the bootstrap script doesn't work for your environment, use the Manual Install steps below inside Claude Code.

Manual Install

Step-by-step installation inside Claude Code (if bootstrap doesn't work)

Run these slash commands in the Claude Code chat, not in your system terminal:

# 1) Add marketplace
/plugin marketplace add 777genius/claude-notifications-go
# 2) Install plugin
/plugin install claude-notifications-go@claude-notifications-go
# 3) Restart Claude Code
# 4) Download binary
/claude-notifications-go:init
# 5) (Optional) Configure sounds and settings
/claude-notifications-go:settings

Having issues with installation? See Troubleshooting.

Updating

Run the same command as for installation — it will update both the plugin and the binary:

curl -fsSL https://raw.githubusercontent.com/777genius/claude-notifications-go/main/bin/bootstrap.sh | bash

Then restart Claude Code to apply the new version. Your settings in ~/.claude/claude-notifications-go/config.json are preserved across updates.

Manual update (if bootstrap didn't work)

Claude Code also periodically checks for plugin updates automatically. Binaries are updated on the next hook invocation when a version mismatch is detected.

To update manually via Claude Code UI:

Run /plugin, select Marketplaces, choose claude-notifications-go, then select Update marketplace
Select Installed, choose claude-notifications-go, then select Update now

If the binary auto-update didn't work (e.g. no internet at the time), run /claude-notifications-go:init to download it manually. If hook definitions changed in the new version, restart Claude Code to apply them.

Supported Notification Types

Status	Icon	Description	Trigger
Task Complete	✅	Main task completed	Stop/SubagentStop hooks (state machine detects active tools like Write/Edit/Bash, or ExitPlanMode followed by tool usage)
Review Complete	🔍	Code review finished	Stop/SubagentStop hooks (state machine detects only read-like tools: Read/Grep/Glob with no active tools, plus long text response >200 chars)
Question	❓	Claude has a question	PreToolUse hook (AskUserQuestion) OR Notification hook
Plan Ready	📋	Plan ready for approval	PreToolUse hook (ExitPlanMode)
Session Limit Reached	⏱️	Session limit reached	Stop/SubagentStop hooks (state machine detects "Session limit reached" text in last 3 assistant messages)
API Error	🔴	Authentication expired, rate limit, server error, connection error	Stop/SubagentStop hooks (state machine detects via `isApiErrorMessage` flag + `error` field from JSONL)

Platform Support

Supported platforms:

macOS (Intel & Apple Silicon)
Linux (x64 & ARM64)
Windows 10+ (x64)

No additional dependencies:

✅ Binaries auto-download from GitHub Releases
✅ Pure Go - no C compiler needed
✅ All libraries bundled
✅ Works offline after first setup

Windows-specific features:

Native Toast notifications (Windows 10+)
Works in PowerShell, CMD, Git Bash, or WSL
MP3/WAV/OGG/FLAC audio playback via native Windows APIs
System sounds not accessible - use built-in MP3s or custom files

Click-to-Focus (macOS & Linux)

Clicking a notification activates your terminal window. Auto-detects terminal and platform.

macOS — via AX API with bundle ID detection:

Terminal	Focus method
Ghostty	Exact tab focus via Ghostty AppleScript, with AXDocument fallback
VS Code / Insiders / Cursor	AXTitle (focus-window subcommand)
iTerm2	Exact tab/pane targeting via iTerm2 Python API when available, otherwise app-level iTerm activation
Warp, kitty, WezTerm, Alacritty, Hyper, Apple Terminal	AXTitle (focus-window subcommand)
Any other (custom `terminalBundleId`)	AXTitle (focus-window subcommand)

Linux — via D-Bus daemon with automatic compositor detection:

Terminal	Supported compositors
VS Code	GNOME, KDE, Sway, X11
GNOME Terminal, Konsole, Alacritty, kitty, WezTerm, Tilix, Terminator, XFCE4 Terminal, MATE Terminal	GNOME, KDE, Sway, X11
Any other	Fallback by name

Linux focus methods (tried in order): GNOME extension, GNOME Shell Eval, GNOME FocusApp, wlrctl (Sway/wlroots), kdotool (KDE), xdotool (X11).

Multiplexers (both platforms): tmux (including iTerm2 -CC integration mode), zellij, WezTerm, kitty — click switches to the correct pane/tab.

iTerm2 note: to open the exact iTerm2 tab or split pane, enable iTerm2 > Settings > General > Magic > Enable Python API. If you just toggled it, restart iTerm2 once. Without the Python API, the plugin falls back to app-level iTerm activation instead of exact tab targeting.

Windows — clicking a notification raises the originating terminal window (Windows Terminal, VS Code, conhost, …) via a protocol-activated toast. Window-level only: tab/split-pane targeting isn't possible (one window hosts all tabs), and picking among multiple WT windows in one process is best-effort. See the guide for details.

See Click-to-Focus Guide for configuration details.

Configuration

Run /claude-notifications-go:settings to configure sounds, volume, webhooks, and other options via an interactive wizard. You can re-run it anytime to reconfigure.

Manual Configuration

Config file location:

Platform	Path
macOS / Linux	`~/.claude/claude-notifications-go/config.json`
Windows (Git Bash)	`~/.claude/claude-notifications-go/config.json`
Windows (PowerShell)	`$env:USERPROFILE\.claude\claude-notifications-go\config.json`

Edit the config file directly:

{
  "notifications": {
    "desktop": {
      "enabled": true,
      "sound": true,
      "volume": 1.0,
      "audioDevice": "",
      "clickToFocus": true,
      "terminalBundleId": "",
      "appIcon": "${CLAUDE_PLUGIN_ROOT}/claude_icon.png"
    },
    "webhook": {
      "enabled": false,
      "preset": "slack",
      "url": "",
      "chat_id": "",
      "format": "json",
      "headers": {},
      "payloadFields": {}
    },
    "suppressQuestionAfterTaskCompleteSeconds": 12,
    "suppressQuestionAfterAnyNotificationSeconds": 7,
    "notifyOnSubagentStop": false,
    "suppressForSubagents": true,
    "notifyOnTextResponse": true,
    "respectJudgeMode": true,
    "notifyOnlyWhenUnfocused": false,
    "notifyDelaySeconds": 0,
    "suppressFilters": [
      {
        "name": "Suppress ClaudeProbe completions (remote-control)",
        "status": "task_complete",
        "gitBranch": "",
        "folder": "ClaudeProbe"
      }
    ]
  },
  "statuses": {
    "task_complete": {
      "title": "✅ Completed",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/task-complete.mp3"
    },
    "review_complete": {
      "title": "🔍 Review",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/review-complete.mp3"
    },
    "question": {
      "title": "❓ Question",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/question.mp3"
    },
    "plan_ready": {
      "title": "📋 Plan",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/plan-ready.mp3"
    },
    "session_limit_reached": {
      "title": "⏱️ Session Limit Reached",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/error.mp3"
    },
    "api_error": {
      "title": "🔴 API Error: 401",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/error.mp3"
    },
    "api_error_overloaded": {
      "title": "🔴 API Error",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/error.mp3"
    }
  }
}

Option	Default	Description
`notifyOnSubagentStop`	`false`	Send notifications when subagents (Task tool) complete. Has no effect unless `suppressForSubagents` is also set to `false`.
`suppressForSubagents`	`true`	Suppress subagent (`SubagentStop`) notifications, plus any `Stop` notification whose transcript is a subagent/teammate transcript. Detection uses the hook event for `SubagentStop` (Claude Code passes the parent session `transcript_path` to that hook, so a path check alone can't identify it). Set to `false` together with `notifyOnSubagentStop: true` to get a notification each time a subagent finishes.
`notifyOnTextResponse`	`true`	Send notifications for text-only responses (no tool usage)
`respectJudgeMode`	`true`	Honor `CLAUDE_HOOK_JUDGE_MODE=true` env var to suppress notifications
`notifyOnlyWhenUnfocused`	`false`	Skip the desktop notification only when the focused terminal window can be matched to the current Claude Code session. Best-effort per platform; if focus can't be determined the notification is still shown.
`notifyDelaySeconds`	`0`	Wait N seconds before delivering a desktop notification (capped at 25s by the hook timeout). With `notifyOnlyWhenUnfocused`, focus is re-checked after the wait. Webhooks are unaffected.
`suppressQuestionAfterTaskCompleteSeconds`	`12`	Suppress question notifications for N seconds after task complete
`suppressQuestionAfterAnyNotificationSeconds`	`7`	Suppress question notifications for N seconds after any notification
`suppressFilters`	`[]`	Array of rules to suppress notifications by status, git branch, and/or folder. Each rule is an AND of its fields; omitted fields match any value. Set `gitBranch` to `""` to match sessions outside git repos.

Each status can be individually disabled by adding "enabled": false.

You can also override individual channels per status:

{
  "statuses": {
    "question": {
      "title": "❓ Question",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/question.mp3",
      "desktop": { "enabled": true },
      "webhook": { "enabled": false }
    }
  }
}

statuses.<name>.enabled is still the master switch for both channels. Use desktop.enabled and webhook.enabled when you want one channel on and the other off for the same status.

Focus-Aware & Delayed Notifications

Two independent options cut notification noise when you're already watching the terminal:

notifyOnlyWhenUnfocused - skip the desktop notification only when the focused terminal window can be matched to the current Claude Code session.
notifyDelaySeconds - wait N seconds before delivering, so a quick task can finish before any banner appears (capped at 25s to stay within the hook timeout).

They compose: with both set, the plugin waits, then notifies only if the terminal still isn't focused - "tell me once I've looked away."

{
  "notifications": {
    "notifyOnlyWhenUnfocused": true,
    "notifyDelaySeconds": 10
  }
}

Both apply to desktop notifications only - webhook delivery is never delayed or suppressed. Focus detection is best-effort and degrades safely by notifying when unsure:

macOS: Ghostty can be matched by exact terminal/session metadata; other terminal apps require the frontmost window title to match the project folder and existing Screen Recording access.
Linux: X11 sessions compare $WINDOWID to the active window. Wayland or terminals without $WINDOWID are treated as unknown.
Windows: the foreground window must belong to the hook process ancestry and its title must contain the project folder. Ambiguous multi-window or multi-tab terminal hosts are treated as unknown.

Unknown means "show the notification", not "suppress it".

Sound Options

Built-in sounds (included):

${CLAUDE_PLUGIN_ROOT}/sounds/task-complete.mp3
${CLAUDE_PLUGIN_ROOT}/sounds/review-complete.mp3
${CLAUDE_PLUGIN_ROOT}/sounds/question.mp3
${CLAUDE_PLUGIN_ROOT}/sounds/plan-ready.mp3
${CLAUDE_PLUGIN_ROOT}/sounds/error.mp3

System sounds:

macOS: /System/Library/Sounds/Glass.aiff, /System/Library/Sounds/Hero.aiff, etc.
Linux: /usr/share/sounds/**/*.ogg (varies by distribution)
Windows: Use built-in MP3s (system sounds not easily accessible)

Supported formats: MP3, WAV, FLAC, OGG/Vorbis, AIFF

List Available Sounds

See all available notification sounds on your system:

# List all sounds (built-in + system)
bin/list-sounds

# Output as JSON
bin/list-sounds --json

# Preview a sound
bin/list-sounds --play task-complete

# Preview at specific volume
bin/list-sounds --play Glass --volume 0.5

Or use the skill command: /claude-notifications-go:sounds

Audio Device Selection

Route notification sounds to a specific audio output device instead of the system default:

# List available audio devices
bin/list-devices

# Output:
#   0: MacBook Pro-Lautsprecher
#   1: Babyface (23314790) (default)
#   2: Immersed

Then add the device name to your ~/.claude/claude-notifications-go/config.json:

{
  "notifications": {
    "desktop": {
      "audioDevice": "MacBook Pro-Lautsprecher"
    }
  }
}

Leave audioDevice empty or omit it to use the system default device.

Test Sound Playback

Preview any sound file with optional volume control:

# Test built-in sound (full volume)
bin/sound-preview sounds/task-complete.mp3

# Test with reduced volume (30% - recommended for testing)
bin/sound-preview --volume 0.3 sounds/task-complete.mp3

# Test macOS system sound at 30% volume
bin/sound-preview --volume 0.3 /System/Library/Sounds/Glass.aiff

# Test custom sound at 50% volume
bin/sound-preview --volume 0.5 /path/to/your/sound.wav

# Show all options
bin/sound-preview --help

Volume flag: Use --volume to control playback volume (0.0 to 1.0). Default is 1.0 (full volume).

Manual Testing

The plugin is invoked automatically by Claude Code hooks. To test manually:

# Test PreToolUse hook
echo '{"session_id":"test","transcript_path":"/path/to/transcript.jsonl","tool_name":"ExitPlanMode"}' | \
  claude-notifications handle-hook PreToolUse

# Test Stop hook
echo '{"session_id":"test","transcript_path":"/path/to/transcript.jsonl"}' | \
  claude-notifications handle-hook Stop

Contributing

See CONTRIBUTING.md for development setup, testing, building, and submitting changes. For local plugin workflows and real-claude smoke/manual E2E testing, see docs/LOCAL_DEVELOPMENT.md.

Troubleshooting

See Troubleshooting Guide for common issues:

Ubuntu 24.04: EXDEV: cross-device link not permitted during /plugin install (TMPDIR workaround)
Windows: install issues related to %TEMP% / %TMP% location
Windows / Git Bash: GitHub Releases download fails because of proxy / TLS inspection / certificate revocation

Documentation

Architecture - Plugin architecture, directory structure, data flow
Local Development And E2E - Local marketplace testing, real Claude smoke tests, manual click-to-focus validation
Click-to-Focus - Configuration, supported terminals, platform details
Volume Control Guide - Customize notification volume
- Configure volume from 0% to 100%
- Logarithmic scaling for natural sound
- Per-environment recommendations
Interactive Sound Preview - Preview sounds during setup
- Interactive sound selection
- Preview before choosing
Plugin Compatibility - Integration with other Claude Code plugins
Troubleshooting - Common install/runtime issues
- Ubuntu 24.04 EXDEV during /plugin install (TMPDIR workaround)
Webhook Integration Guide - Complete guide for webhook setup
- Slack - Slack integration with color-coded attachments
- Discord - Discord integration with rich embeds
- Telegram - Telegram bot integration
- Lark/Feishu - Lark/Feishu integration with interactive cards
- Custom Webhooks - Any webhook-compatible service
- Configuration - Retry, circuit breaker, rate limiting
- Monitoring - Metrics and debugging
- Troubleshooting - Common issues and solutions

License

GPL-3.0 - See LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 357 Commits
.claude-plugin		.claude-plugin
.github		.github
bin		bin
cmd		cmd
commands		commands
config		config
docs		docs
hooks		hooks
internal		internal
pkg/jsonl		pkg/jsonl
scripts		scripts
sounds		sounds
swift-notifier		swift-notifier
.codecov.yml		.codecov.yml
.gitattributes		.gitattributes
.gitignore		.gitignore
.orphaned_at		.orphaned_at
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
claude_icon.png		claude_icon.png
go.mod		go.mod
go.sum		go.sum
setup.sh		setup.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Claude Notifications (plugin)

Table of Contents

Features

Installation

Prerequisites

Quick Install (Recommended)

Manual Install

Updating

Supported Notification Types

Platform Support

Click-to-Focus (macOS & Linux)

Configuration

Manual Configuration

Focus-Aware & Delayed Notifications

Sound Options

List Available Sounds

Audio Device Selection

Test Sound Playback

Manual Testing

Contributing

Troubleshooting

Documentation

License

About

Uh oh!

Releases 74

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Claude Notifications (plugin)

Table of Contents

Features

Installation

Prerequisites

Quick Install (Recommended)

Manual Install

Updating

Supported Notification Types

Platform Support

Click-to-Focus (macOS & Linux)

Configuration

Manual Configuration

Focus-Aware & Delayed Notifications

Sound Options

List Available Sounds

Audio Device Selection

Test Sound Playback

Manual Testing

Contributing

Troubleshooting

Documentation

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 74

Contributors

Uh oh!

Languages