Claude Code Notify

Cross-platform desktop notifications for Claude Code — Windows / macOS / Linux.

中文文档

Install

Two commands, zero config:

# 1. Add plugin source
/plugin marketplace add ferrymo/claude-code-notify

# 2. Install
/plugin install claude-code-notify@claude-code-notify

On first launch after install, the SessionStart hook automatically:

• Installs BurntToast module (Windows)
• Generates a default notification icon
• Checks system notification tools (macOS/Linux)

No manual setup required — it just works.

Triggers

Hook	Scenario	Type
Stop	Claude finished / idle	info
Notification + permission_prompt	Claude needs approval	warning
StopFailure	Claude encountered an error	error

Dependencies

Handled automatically. Listed here for reference only:

• Windows: PowerShell 7 (pwsh) + BurntToast (auto-installed)
• macOS: osascript (built-in); optional terminal-notifier for icon support (brew install terminal-notifier)
• Linux: notify-send (sudo apt install libnotify-bin)

Custom Avatar

Replace the icon file with your own PNG (256x256 recommended):

~/.claude/notify-icon.png

The default is a simple auto-generated pixel icon. Just overwrite it with your own.

Notification Details

• Windows: Toast notification with custom avatar and sound
• macOS: Native Notification Center (icon supported via terminal-notifier)
• Linux: notify-send desktop notification with urgency levels

Each notification includes: project name + git branch, terminal type, Claude message summary.

Plugin Structure

claude-code-notify/
├── .claude-plugin/
│   ├── plugin.json          # Plugin metadata
│   └── marketplace.json     # Marketplace registry
├── hooks/
│   └── hooks.json           # Auto-loaded hooks definition
├── setup.cmd / setup.ps1    # SessionStart auto-setup (deps + icon)
├── run-hook.cmd             # Windows hook entry
├── run-hook.sh              # Unix hook entry
├── notify.ps1               # Windows notification core (BurntToast)
├── notify.sh                # macOS/Linux notification core
└── README.md

Uninstall

/plugin uninstall claude-code-notify@claude-code-notify

The icon file ~/.claude/notify-icon.png is preserved — delete it manually if needed.

License

MIT