Installation

For Humans

macOS (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

For LLM Agents

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

Usage

| 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.

How It Works

Code-Notify uses the hook systems built into AI coding tools:

• Claude Code: ~/.claude/settings.json
• Codex: ~/.codex/config.toml
• Gemini CLI: ~/.gemini/settings.json

For 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" }
        ]
      }
    ]
  }
}

Alert Types

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.

Troubleshooting

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.

Project Structure

code-notify/
├── bin/           # Main executable
├── lib/           # Library code
├── scripts/       # Install scripts
├── docs/          # Documentation
└── assets/        # Images

Links

• Installation Guide
• Hook Configuration
• Contributing
• GitHub Issues

License

MIT License - see LICENSE