Macos Notifier

Install

In Claude Code, run:

/plugin marketplace add Xiryl/claude-plugin-notification
/plugin install macos-notifier@claude-plugin-notification
/reload-plugins

That's it. The next time Claude finishes a task you'll get a native macOS notification.

Why /reload-plugins? After installing a plugin, Claude Code copies it into the local cache and marks it as enabled, but hooks are only loaded on session start or when you run /reload-plugins. Skip this step and the plugin is installed but silent — no notifications until you restart Claude Code or reload manually. The install command itself reminds you (✓ Installed macos-notifier. Run /reload-plugins to apply.).

---

Table of contents

• What you get
• Configuration
• Events
• Sounds
• Example configs
• Requirements
• How it works
• Updating
• Troubleshooting
• Contributing
• License

---

What you get

Native	Uses macOS Notification Center — no Electron, no Node, no daemon
Two events	Fires on task completion and when Claude is blocked waiting on you
Distinct sounds	Optional override so you can tell "done" from "needs input" by ear
Click → terminal	Clicking the notification activates your terminal app (iTerm, Terminal, Ghostty, ...)
Configurable	Sound, title format, description format — all customizable via JSON
Per-project	Different notifications when working on different projects, optional
Lightweight	Two small bash scripts, ~180 LOC total
Offline	No network calls, no telemetry

Configuration

Configuration is optional. Without a config file you get sensible defaults: title Claude Code, message Task complete, sound Glass, no click action.

To customize, drop a JSON file at one of these paths:

Path	Scope
.claude/macos-notifier.json	Per-project — wins over the global file
~/.claude/macos-notifier.json	Global — applies to every project

Both files use the same schema. A starter is checked in as macos-notifier/config.example.json.

Schema

{
  "sound": "Glass",
  "soundOnInputNeeded": "Funk",
  "title": {
    "mode": "project",
    "value": "Claude Code"
  },
  "description": {
    "mode": "duration",
    "value": "Task complete",
    "values": ["Done!", "Ready", "Task complete"]
  },
  "click": {
    "enabled": true,
    "terminal": "auto"
  },
  "events": {
    "stop": true,
    "notification": true
  }
}

Top-level fields

Field	Type	Default	Description
sound	string	"Glass"	macOS notification sound name (see Sounds)
soundOnInputNeeded	string	same as sound	Sound override for input-needed notifications. Lets you tell "done" from "waiting" by ear.
title	object	—	How to compute the notification title
description	object	—	How to compute the notification body (Stop event only)
click	object	—	Behavior when the notification is clicked
events	object	both true	Toggle each event on/off — see Events

title.mode

Mode	Result	Example
static	Uses title.value literally	Claude Code
project	<cwd-basename> (<git-branch>). Falls back to bare basename outside git.	claudeplugin (main)
session	Claude <first-8-chars-of-session-id>	Claude a3f1c7d2

description.mode

Mode	Result	Example
static	Uses description.value literally	Task complete
random	Picks a random string from description.values each time	Done!
duration	Time since the last user prompt	Done in 2m 14s

duration mode falls back to description.value for the first turn after a session resume (no prior prompt to measure from).

click.terminal

When click.enabled is true, clicking the notification activates this app:

Value	Activates
auto	Detects from $TERM_PROGRAM (recommended)
iterm	iTerm2
terminal	Apple Terminal
ghostty	Ghostty
warp	Warp
wezterm	WezTerm
vscode	VS Code
any bundle ID	Used as-is, e.g. com.example.MyTerminal

Click action requires terminal-notifier. Without it, notifications still appear via osascript but clicking does nothing.

Events

The plugin fires on two Claude Code events. You can toggle each one independently in events.

Event	When it fires	Notification body
stop	Claude finishes a task and the prompt becomes available again	Follows description.mode (static / random / duration)
notification	Claude is blocked waiting on you — permission prompt, tool confirmation, idle for input	Uses Claude's own message, e.g. "Claude needs your permission to use Bash". Falls back to "Claude needs your input" if no message is provided.

"events": {
  "stop": true,
  "notification": true
}

Set either to false to silence that event. Set soundOnInputNeeded if you want a different sound for notification events than for stop — handy when you're on another monitor and want to know whether you can keep working or need to come back.

Sounds

Any file from /System/Library/Sounds/. The popular ones:

Sound	Vibe
Glass	Default — light, clean
Hero	Triumphant
Submarine	Low, attention-grabbing
Pop	Quick, terse
Tink	Minimal
Ping	…pingy
Funk	Quirky
Bottle	Soft pop
Frog	Chill
Purr	Subtle

Preview one with afplay /System/Library/Sounds/Glass.aiff.

Example configs

Minimal — fixed title and message, no click:

{
  "sound": "Pop",
  "title":       { "mode": "static", "value": "Claude" },
  "description": { "mode": "static", "value": "Done" },
  "click":       { "enabled": false }
}

Maximum context — project name + duration + distinct sounds + click:

{
  "sound": "Hero",
  "soundOnInputNeeded": "Funk",
  "title":       { "mode": "project" },
  "description": { "mode": "duration" },
  "click":       { "enabled": true, "terminal": "auto" },
  "events":      { "stop": true, "notification": true }
}

Only when Claude needs me — silent on task completion:

{
  "sound": "Submarine",
  "title":  { "mode": "static", "value": "Claude needs you" },
  "events": { "stop": false, "notification": true }
}

Random vibe:

{
  "sound": "Glass",
  "title":       { "mode": "static", "value": "Claude Code" },
  "description": {
    "mode": "random",
    "values": [
      "Done!",
      "All set.",
      "Back to you.",
      "Ready when you are."
    ]
  },
  "click": { "enabled": true, "terminal": "auto" }
}

Requirements

Tool	Required for	Install
macOS	the whole thing	—
jq	reading the config file	brew install jq
terminal-notifier	click-to-focus action	brew install terminal-notifier

osascript is built into macOS and is used as a fallback when terminal-notifier is missing.

How it works

The plugin registers three hooks:

Hook	Script	Purpose
UserPromptSubmit	scripts/start.sh	Writes /tmp/claude-notify-<session>.start with the current epoch — used for duration mode
Stop	scripts/notify.sh	Task complete. Reads config, computes title/message, fires the notification.
Notification	scripts/notify.sh	Claude is waiting on you. Same script — it branches on hook_event_name from stdin and uses Claude's own message field as the body.

Layout:

macos-notifier/
├── .claude-plugin/plugin.json
├── hooks/hooks.json
├── scripts/
│   ├── start.sh    (UserPromptSubmit)
│   └── notify.sh   (Stop)
└── config.example.json

Updating

/plugin marketplace update claude-plugin-notification

Troubleshooting

See INSTALL.md for the full checklist.

Contributing

PRs welcome — see CONTRIBUTING.md.

License

MIT — see LICENSE.