cc-notify

cc-notify

Native macOS notifications + click-to-focus for Claude Code.

When Claude needs your attention or finishes a turn, you get a macOS banner. Click it and you jump to the exact Terminal.app window, Aerospace workspace, and tmux session/window/pane where Claude is waiting.

Quickstart

cc-notify is a Claude Code plugin — there's nothing to run; it fires automatically via hooks. Setup:

/plugin marketplace add FarisHijazi/claude-plugins   # in Claude Code
/plugin install cc-notify@farishijazi-plugins

brew install vjeantet/tap/alerter                     # the notifier (required)

That's the whole core — you'll now get clickable banners. Optional extras:

1. VS Code / Cursor terminal-pane focus + live status tabs — run "$HOME/.claude/plugins/marketplaces/farishijazi-plugins/plugins/cc-notify/bin/cc-install-editor-extension", then reload the editor window. (details)
2. Keyboard hotkey to "click" the latest banner — Karabiner rule.
3. Outcome emojis (✅/❌/👍/👎/💬 on the banner + tab) — add the token instruction to ~/.claude/CLAUDE.md.

To verify / debug: bin/cc-notify-doctor. After a plugin update, re-run bin/cc-install-editor-extension if you use the extension.

Install (via marketplace)

/plugin marketplace add FarisHijazi/claude-plugins
/plugin install cc-notify@farishijazi-plugins

Then install the notifier binary (one-time):

brew install vjeantet/tap/alerter

That's it. The plugin's hooks/hooks.json registers the Notification and Stop hooks automatically.

First click triggers two macOS Automation permission prompts ("Terminal would like to control Terminal", "System Events"). Allow them once.

Optional: keyboard hotkey to "click" the latest banner

macOS doesn't natively let you click a notification banner with the keyboard. The plugin ships bin/cc-banner-click — a small script that finds the most recent route file and triggers the same focus action as clicking. Bind it to any hotkey.

Karabiner-Elements example (Option+Shift+A): add this rule to ~/.config/karabiner/karabiner.json under profiles[0].complex_modifications.rules:

{
  "description": "Focus most-recent Claude Code notification with Option+Shift+A (cc-notify)",
  "manipulators": [
    {
      "type": "basic",
      "from": {
        "key_code": "a",
        "modifiers": { "mandatory": ["option", "shift"], "optional": ["any"] }
      },
      "to": [
        {
          "shell_command": "\"$HOME/.claude/plugins/marketplaces/farishijazi-plugins/plugins/cc-notify/bin/cc-banner-click\""
        }
      ]
    }
  ]
}

The script exits non-zero if no route file exists or focus didn't fire, and the wrapper only dismisses the banner (via alerter --remove) on success — so the hotkey is safe to mash.

Optional: focus the exact VS Code / Cursor terminal pane

By default, clicking a notification from a VS Code / Cursor session focuses the right window. To also jump to the exact integrated terminal pane Claude is running in, install the bundled editor extension (one-time):

"$HOME/.claude/plugins/marketplaces/farishijazi-plugins/plugins/cc-notify/bin/cc-install-editor-extension"

Then reload the window in each editor (Cmd+Shift+P → "Developer: Reload Window").

This is the only way to focus a specific integrated terminal — VS Code/Cursor expose no CLI flag, vscode://command: URI, or terminal escape sequence for it. The extension (editor-extension/) registers a vscode://farishijazi.cc-notify-focus/focus?pids=… URI handler and calls terminal.show() on the terminal whose shell pid matches. See LESSONS.md gotcha #13.

Per-session color & name

cc-notify reflects two pieces of Claude Code session identity:

• Color — /color sets agentColor in the transcript; cc-notify maps it to a colored emoji (🔴🟠🟡🟢🔵🟣🩷🩵) and prefixes the banner subtitle with it (the same color your statusline / tmux already show). No /color → no emoji.
• Name — /rename sets customTitle (falls back to Claude's auto aiTitle, then the project folder).

Terminal tab renaming (needs the editor extension): on VS Code / Cursor, cc-notify renames the integrated terminal tab to <status> <color> <session name> (e.g. 👀 🟠 cc-notify) so you can tell sessions apart — and see their state — at a glance. The status emoji tracks the session:

State	Emoji
fresh session (startup)	⏸️
working (turn in progress)	⏳
needs permission	🔐
asking you / input	❓
multiple-choice menu open (AskUserQuestion)	🔀
done (no outcome token)	ℹ️