by mylee04
Cross-platform desktop notifications for Claude Code, Codex, and Gemini CLI. Install via Homebrew, npm, or script.
# Add to your Claude Code skills
git clone https://github.com/mylee04/code-notifyOfficial downloads: https://github.com/mylee04/code-notify/releases
Homebrew:
brew install mylee04/tools/code-notifynpm:
npm install -g code-notify
Desktop notifications for AI coding tools - get alerts when tasks complete or input is needed.
cn on claude no longer treats arbitrary Notification or Stop entries as if code-notify were already installedNo comments yet. Be the first to share your thoughts!
cn and cnp for fast accessmacOS (Homebrew)
brew tap mylee04/tools
brew install code-notify
cn on
macOS (Homebrew, Already Installed)
cn update
code-notify version
If you were using the older claude-notify hook layout, supported upgrades now repair those Claude hooks automatically. On Windows, that repair also covers older notify.ps1 hook layouts and alternate Claude settings locations such as %USERPROFILE%\.config\.claude\settings.json. Existing unrelated Claude hooks are preserved during enable/disable operations.
Linux / WSL
curl -sSL https://raw.githubusercontent.com/mylee04/code-notify/main/scripts/install.sh | bash
npm (macOS / Linux / Windows)
npm install -g code-notify
cn on
Windows
irm https://raw.githubusercontent.com/mylee04/code-notify/main/scripts/install-windows.ps1 | iex
Paste this to your AI agent (Claude Code, Cursor, etc.):
Install code-notify by following:
https://raw.githubusercontent.com/mylee04/code-notify/main/docs/installation.md
Or fetch directly:
curl -s https://raw.githubusercontent.com/mylee04/code-notify/main/docs/installation.md

| Command | Description |
| -------------------- | -------------------------------------------- |
| cn on | Enable notifications for all detected tools |
| cn on all | Explicit alias for enabling all detected tools |
| cn on claude | Enable for Claude Code only |
| cn on codex | Enable for Codex only |
| cn on gemini | Enable for Gemini CLI only |
| cn off | Disable notifications |
| cn off all | Explicit alias for disabling all tools |
| cn test | Send test notification |
| cn status | Show current status |
| cn update | Update code-notify |
| cn update check | Check the latest release and show the update command |
| cn click-through | Show current macOS click-through mappings |
| cn click-through add <app> | Add a macOS click-through mapping |
| cn alerts | Configure which events trigger notifications |
| cn sound on | Enable sound notifications |
| cn sound set <path>| Use custom sound file |
| cn voice on | Enable voice (macOS, Windows) |
| cn voice on claude | Enable voice for Claude only |
| cnp on | Enable for current project only |
When enabling project notifications with cnp on, Code-Notify warns if Claude project trust does not appear to be accepted yet.
Project-scoped Claude hooks override the global mute file, so cn off will not suppress a project where cnp on is enabled.
all is also accepted as an explicit alias for global commands such as cn on all, cn off all, and cn status all.
Code-Notify uses the hook systems built into AI coding tools:
~/.claude/settings.json~/.codex/config.toml~/.gemini/settings.jsonFor Codex, Code-Notify configures notify = ["/absolute/path/to/notifier.sh", "codex"] and reads the JSON payload Codex appends on completion.
Codex currently exposes completion events through notify; approval and request_permissions prompts do not currently arrive through this hook.
When enabled, it adds hooks that call the notification script when tasks complete:
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [{ "type": "command", "command": "notify.sh stop claude" }]
}
],
"Notification": [
{
"matcher": "idle_prompt",
"hooks": [
{ "type": "command", "command": "notify.sh notification claude" }
]
}
]
}
}
By default, notifications only fire when the AI is idle and waiting for input (idle_prompt). You can customize this:
cn alerts # Show current config
cn alerts add permission_prompt # Also notify on tool permission requests
cn alerts remove permission_prompt # Remove permission notifications
cn alerts reset # Back to default (idle_prompt only)
| Type | Description |
| -------------------- | -------------------------------------- |
| idle_prompt | AI is waiting for your input (default) |
| permission_prompt | AI needs tool permission (Y/n) |
| auth_success | Authentication success |
| elicitation_dialog | MCP tool input needed |
Alert-type matching currently applies to Claude Code and Gemini CLI notification hooks. Codex currently uses completion events from notify, so permission_prompt and idle_prompt settings do not change Codex behavior.
Command not found?
exec $SHELL # Reload shell
No notifications?
cn status # Check if enabled
cn test # Test notification
brew install terminal-notifier # Better notifications (macOS)
Notification click opens the wrong macOS app?
cn click-through add PhpStorm
cn test
Installed with npm?
cn update # Runs: npm install -g code-notify@latest
Too many last_notification_* files in ~/.claude/notifications?
Generated rate-limit state files are stored under ~/.claude/notifications/state/ instead of cluttering the root notifications folder.
code-notify/
├── bin/ # Main executable
├── lib/ # Library code
├── scripts/ # Install scripts
├── docs/ # Documentation
└── assets/ # Images
MIT License - see LICENSE