ClaudeNotifier

A macOS notification app for Claude Code integration.
Displays native notifications and focuses the correct terminal tab when clicked.

Why? • Features • Installation • Usage • FAQ

✨ Why ClaudeNotifier?

Anthropic's recommended terminal notification setup only works for iTerm2 users (also I could never make it work on my machine). ClaudeNotifier provides a reliable alternative that supports multiple terminals and editors, with extra features like click-to-focus and smart suppression.

Most other notification setups rely on terminal-notifier or osascript one-liners. ClaudeNotifier takes a different approach:

• 📦 Zero dependencies: Just install and run claude-notifier setup.
• 🎯 Click-to-focus the exact tab: Other tools open the app at best. ClaudeNotifier focuses the specific terminal tab or iTerm2 session that triggered the notification.
• 🤫 Smart suppression: Notifications are silenced when you're already looking at the terminal, so you're not interrupted mid-thought.
• 🧹 No notification spam: Each terminal tab and project keeps at most one notification in Notification Center. New notifications replace old ones instead of piling up.
• 🖥️ Wide terminal support: iTerm2, Terminal.app, Ghostty, Warp, VS Code, VSCodium, Cursor, Windsurf, Zed, WebStorm, and IntelliJ IDEA.
• 🩺 Built-in diagnostics: claude-notifier doctor checks your installation, hooks, permissions, and PATH so you can fix issues without guesswork.
• 💅🏻 A pretty icon: Look, someone spent way too long on it. Might as well enjoy it.

📦 Installation

Homebrew (Recommended)

brew install --cask mlz11/tap/claude-notifier

From Source

git clone https://github.com/mlz11/ClaudeNotifier.git
cd ClaudeNotifier
make install

You'll be prompted for the install directory (press Enter for default /Applications).

This builds the app, installs it to the chosen directory, and creates a claude-notifier CLI command in ~/.local/bin.

If ~/.local/bin is not in your PATH, add it:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

🚀 Usage

Quick Setup for Claude Code

claude-notifier setup

You'll be prompted for the Claude config directory (press Enter for default ~/.claude).

This automatically:

• Installs the notification script to your config directory

• Adds hooks to settings.json

• Prompts for required macOS permissions

  🔐 Permissions details

  1. **Notifications**: Required to display notifications. - Manage in: **System Settings → Notifications → ClaudeNotifier**

  2. Automation: Required for click-to-focus.

     • Manage in: System Settings → Privacy & Security → Automation → ClaudeNotifier

  3. System Events: Required for smart suppression. Most terminals (like iTerm2) typically have this permission already, but others (like VS Code) may prompt you to allow it to control System Events on first use.

     • Manage in: System Settings → Privacy & Security → Automation → [Your terminal or IDE]

Diagnosing Issues

claude-notifier doctor

This checks your installation and permissions, showing any issues and how to fix them.

Configuring Preferences

claude-notifier config

Opens an interactive menu to configure icon color, notification sound, and headless mode behavior.

  ClaudeNotifier Configuration
  ↑/↓ navigate · Enter select · Esc back

    ❯ Icon color
      Notification sound
      Headless mode notifications
      Done

Available icon variants:

brown (default)	blue	green

Requirements

• macOS 11.0+
• iTerm2, Terminal.app, Ghostty, Warp, VS Code, VSCodium, Cursor, Windsurf, Zed, WebStorm, or IntelliJ IDEA

❓ FAQ

Why aren't all terminals fully supported (tab-specific focus) like iTerm2?

Full support (tab-specific focus and suppression) requires two things from the terminal: AppleScript integration and a session ID environment variable. Currently only iTerm2 and Terminal.app provide both.

IDE terminals (VS Code, VSCodium, Cursor, Windsurf, Zed, WebStorm, IntelliJ IDEA)

When using Claude Code in an IDE's integrated terminal, these editors have app-level support only:

• App-level suppression: Notifications are suppressed whenever the editor is frontmost, even if you're in the editor rather than the terminal panel. These editors don't expose which panel is focused via AppleScript or environment variables.
• No tab-specific focus: Clicking a notification brings the editor to the foreground but cannot focus a specific terminal instance.

These are upstream limitations, not something ClaudeNotifier can work around without companion extensions.

For the Claude Code extension (as opposed to the integrated terminal), see the extension FAQ entry below.

Ghostty

Ghostty also has app-level support only, for different reasons (it lacks the APIs needed for full integration):

• No session ID environment variable (discussion)
• AppleScript support is planned but not yet implemented (discussion)

Once Ghostty adds both, we can upgrade to full support with tab-specific focus and suppression.

Warp

Warp also has app-level support only. It does not support AppleScript and doesn't expose a session ID environment variable, so tab-specific focus and suppression are not possible.

• AppleScript support request
• Scripting & CLI discussion

Does it work with the Claude Code IDE extension?

Partially. The Claude Code extensions for VS Code, Cursor, Windsurf, VSCodium, WebStorm, and IntelliJ IDEA run Claude as a subprocess rather than in a terminal. This means the Notification hook never fires (confirmed upstream, won't fix), so you won't get input needed notifications.

You will still get:

• Task complete notifications (via the Stop hook)
• Permission request notifications (via the PermissionRequest hook)

Smart suppression and click-to-focus work the same as in the integrated terminal.

Does it work with the Claude desktop app?

Partially. Claude Desktop's Code tab works with ClaudeNotifier because it runs the same Claude Code engine (hooks fire normally).

The Chat and Cowork tabs are not supported. ClaudeNotifier hooks into Claude Code's lifecycle events (Notification/Stop hooks), which only fire when the Claude Code engine is running. Chat and Cowork tabs don't use Claude Code's hook system, and the Electron-based desktop app doesn't expose an API or observable event for detecting when a response completes.

This would require Anthropic to add native notification support or expose hooks for prompt completion in those modes.