Claude Notify

Desktop notifications for Claude Code events. When Claude finishes working, needs permission, or asks a question, you get a macOS alert dialog. Click "Go to Terminal" to switch to your terminal and the correct tmux window.

macOS only (uses AppleScript).

Install

Add the voldemortensen-plugins marketplace, then install the plugin:

/plugin marketplace add voldemortensen/marketplace
/plugin install claude-notify@voldemortensen-plugins

Restart Claude Code.

Events

Event	Urgency	What happens
Claude stops	Normal	"Claude finished" dialog, OK is default
Notification	Normal	"Claude notification" dialog, OK is default — informational types filtered out, see below
Permission request	Urgent	"Permission needed" dialog with caution icon, Go to Terminal is default
Elicitation	Urgent	"Input needed" dialog with caution icon, Go to Terminal is default
AskUserQuestion	Urgent	"Input needed" dialog with caution icon, Go to Terminal is default

Urgent events make "Go to Terminal" the default button (press Enter to jump straight there).

If your terminal is already the frontmost app, no notification is shown.

Which notifications are filtered

Claude Code fires its Notification hook for a lot of things that need nothing from you — most annoyingly a teammate or subagent finishing ("Teammate @foo finished"), which in auto mode means work is still going. The hook payload includes a notification_type field, so these are dropped by type:

Suppressed	Why
agent_completed	A teammate/subagent finished; nothing to do
idle_prompt	The "waiting for your input" reminder
auth_success	Login succeeded
elicitation_complete, elicitation_response	A question was already answered
computer_use_exit	Claude stopped driving the computer

Everything that actually blocks on you still notifies: agent_needs_input, permission_prompt, worker_permission_prompt, elicitation_dialog, push_notification, computer_use_enter. Unrecognized types notify too, so new Claude Code notification kinds stay visible until they prove to be noise.

Mute more types with CLAUDE_NOTIFY_IGNORE (an extended regex matched against the whole notification_type):

{
  "env": {
    "CLAUDE_NOTIFY_IGNORE": "push_notification|computer_use_enter"
  }
}

Separately, Claude Code has its own built-in push notifications under /config — "Push when Claude decides" and "Push when actions required". Those are independent of this plugin; if you're getting duplicate alerts, check there too.

Supported Terminals

Auto-detected via $TERM_PROGRAM:

• Alacritty
• Ghostty
• iTerm2
• Kitty
• WezTerm
• Terminal.app

Supported Multiplexers

• tmux (auto-detected via $TMUX)

Configuration

Override auto-detection with environment variables. Set them in ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_NOTIFY_TERMINAL": "iTerm",
    "CLAUDE_NOTIFY_PROCESS": "iTerm2"
  }
}

Or in your shell profile.

Variable	Purpose	Default
CLAUDE_NOTIFY_TERMINAL	Terminal app name for AppleScript activation	Auto-detect from $TERM_PROGRAM
CLAUDE_NOTIFY_PROCESS	Process name for frontmost app check	Same as CLAUDE_NOTIFY_TERMINAL
CLAUDE_NOTIFY_IGNORE	Extra notification_type values to suppress (extended regex)	None beyond the built-in list
CLAUDE_NOTIFY_MULTIPLEXER	Set to none to disable tmux switching	Auto-detect from $TMUX
CLAUDE_NOTIFY_GHOSTTY_TARGET	Set to none to disable Ghostty tab targeting (just activate the app)	Enabled

Ghostty tab targeting

On Ghostty, "Go to Terminal" switches to the exact tab/split running this session, not just the app. Ghostty doesn't expose a per-surface ID to the shell, so the hook matches surfaces by working directory (via Ghostty's scripting API), then breaks ties by title — Claude prefixes its terminal title with a status glyph, so a Claude tab is preferred over a plain shell or another program in the same directory. Two Claude sessions in the same directory can't be told apart; it falls back to a plain app activate if no surface matches. Requires Ghostty 1.2+ (scripting support). Set CLAUDE_NOTIFY_GHOSTTY_TARGET=none to opt out.

iTerm2 note

If auto-detection doesn't work for iTerm2, set both:

• CLAUDE_NOTIFY_TERMINAL=iTerm (AppleScript app name)
• CLAUDE_NOTIFY_PROCESS=iTerm2 (System Events process name)

License

MIT