cc-notifier CLI
Claude Code hooks for macOS: a notification returns you to the original terminal window, and a push reaches your phone when idle.
- 113 ★ on the repository
- Last commit
Extended access
Why this level
- The hooks run commands on your machine on every Claude Code event.
- Hammerspoon gets the macOS Accessibility permission, and Pushover receives the project directory name.
Install
- Works in
Manual install
git clone https://github.com/trentmcnitt/cc-notifier.git
cd cc-notifier
./install.shInstall Hammerspoon and `terminal-notifier` through `brew` first, then add the hooks to `~/.claude/settings.json`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The hooks run commands on your machine on every Claude Code event.
- Hammerspoon gets the macOS Accessibility permission, and Pushover receives the project directory name.
This is third-party code. Review the repository files before installing.
What it does
cc-notifier plugs into Claude Code through the `SessionStart`, `Stop`, `Notification` and `SessionEnd` hooks. At session start it remembers the focused window, and when the agent finishes a task or waits for permission it compares the current window with the original. If you moved to another window, an iTerm2 tab or a tmux session, a macOS notification appears. Clicking it through Hammerspoon returns you to the same window, even on another Space, and in iTerm2 to the same tab. Over SSH the script checks terminal idle time and sends a Pushover push with a link that reopens the session on a phone in Blink Shell. Hooks return immediately and the work runs in the background. The code is a single Python file with a bash wrapper.
Who it is for. Claude Code users on macOS who work in other windows in parallel and do not want to check the terminal by hand.
Good fit when
- A long task runs in the terminal while you read mail or documentation in another window.
- Claude Code stopped at a permission prompt and the notification should take you straight to the right window.
- The session runs on a remote machine over SSH and the alert should reach a phone.
- Several sessions run in different iTerm2 tabs and you need to get back to your own.
Not a fit when
- The work machine is not macOS: local mode uses Hammerspoon and macOS notifications.
- Claude Code runs unattended on a schedule: hooks for such runs are switched off with `CC_NOTIFIER_DISABLE=1`.
- Granting Hammerspoon Accessibility access is undesirable under your security policy.
Example request
Run the tests and print only the result, I will handle mail meanwhile: send a notification when you finish.Limitations
Local mode needs macOS, Python 3.9 or newer, Hammerspoon with the Accessibility permission and `terminal-notifier`. Without the permission, returning to the window and detecting that you left it do not work. Remote mode over SSH works only with Pushover, which receives the directory name and a link. Hooks are added to `~/.claude/settings.json` by hand, and `init` remembers the window that was focused when the session started. Over SSH no window is tracked.
How to disable. Run `uninstall.sh` from the repository and remove the hooks from `~/.claude/settings.json`. For individual runs `CC_NOTIFIER_DISABLE=1` is enough.
FAQ
When does cc-notifier show a notification?
When Claude Code finishes a task or waits for permission and you switched to another window, iTerm2 tab or tmux session. If the window is focused, there is no notification.
Is Pushover required?
Not on the desktop, where it only adds a push when you are idle. In SSH mode Pushover is required because it is the only notification channel.
Which hooks do I register?
`SessionStart` with `init`, `Stop` and `Notification` with `notify`, and `SessionEnd` with `cleanup`, all from `$HOME/.cc-notifier/cc-notifier`.
How do I turn on a debug log?
Add the `--debug` flag to the hook commands: the log goes to `~/.cc-notifier/cc-notifier.log` and notifications get a debug mark.
Can I set a custom notification title?
Yes, the `CC_NOTIFIER_TITLE_FORMAT` variable accepts a template such as `{hostname}: {dir}`.
Discussion
No questions or reviews yet.
Related
CLI toolsCode-Notify sends a desktop notification when Claude Code, Codex or Gemini CLI finishes a task or waits for your input
Agent Notifications is an alert plugin that includes project and branch context in Claude Code and Codex desktop messages.
A macOS menu bar indicator that shows whether Claude Code is thinking, waiting for your permission and how long the current turn has run
Hook-driven sounds for coding agents: starts, failures, completions and even individual Bash commands each get their own cue
Local voice layer for Claude Code and Codex on macOS: when the agent finishes or fails, it says in a sentence or two what happened
tmux-claude-hatch: Claude Code in a tmux popup
tmux-claude-hatch
A tmux plugin that runs a Claude Code session in a popup for each project and shows the status of every agent in an fzf picker
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| cc-notifier (this card) | no | 113 | |
| Code-Notify | no | 291 | sends a notification when a task ends; cc-notifier also returns you to the same window and tab and sends a phone push |
| Agent Notifications | no | 826 | a plugin that labels messages with project and branch; cc-notifier handles leaving a window and returning to it |
README in short
Installation goes in two steps: dependencies through `brew` plus `./install.sh` from the cloned repository, then hooks in Claude Code settings. Tables of flags and environment variables, a phone mode and a troubleshooting section follow. The repository passes CI on Python 3.9 through 3.14.