cc-notifier

cc-notifier 🔔

Notifications for Claude Code that take you back to the exact window you left.

When Claude Code finishes a task or needs your permission while you're working in another window, cc-notifier shows a macOS notification. Click it and you're back in the original terminal or IDE window, even on another Space (and the same tab, in iTerm2). Away from your desk? It sends a push notification to your phone instead, which can reopen the session there.

Features

- 🎯 Click-to-focus across Spaces. Returns you to the exact window, not just the app, and to the original iTerm2 tab.
- 🧠 Only when you've looked away. Local notifications fire only if you switched windows, iTerm2 tabs, or tmux sessions. Over SSH, cc-notifier checks whether you're idle instead.
- 📲 Push when you're away. Optional Pushover notifications when you've been idle at your desk; the main channel over SSH.
- 📱 Phone handoff (optional). Tap the push notification to resume the same session in Blink Shell.
- ⚡ Never blocks Claude Code. Hooks return immediately and the work runs in the background.
- 🪶 Small and dependency-free. One standard-library Python file plus a bash wrapper, tested in CI on Python 3.9 through 3.14.

How It Works

💻 Desktop Mode

1. Session Start → Captures your focused window ID
2. Task Completion → Compares current window vs original window
3. Smart Notification:
   - 🪟 Switched windows? → Local notification with click-to-focus
   - 🗂️ Switched iTerm2 tabs in same window? → Local notification with tab-aware click-to-focus
   - 💤 Idle at desk? → Optional push notification via Pushover
4. Click Notification → Hammerspoon restores your exact window across Spaces; iTerm2 sessions also restore the original tab

🌐 Remote Mode (SSH)

1. Auto-Detection → Detects SSH via…