Code-Notify

Official downloads: https://github.com/mylee04/code-notify/releases

Homebrew: brew install mylee04/tools/code-notify

npm: npm install -g code-notify

Desktop notifications for AI coding tools - get alerts when tasks complete or input is needed.

Latest: Advance Usage Reset Reminders

On macOS/Linux (including WSL), Code-Notify can now remind you before Codex or Claude usage resets, using the existing usage watcher and notification channels.

• Default schedule: Weekly reminders at 48h, 24h, 12h, 6h, 2h, and 30m; 5h windows use 2h and 30m
• Once per reset cycle: Full-quota observations do not erase previously sent reminders
• Quiet catch-up: Missed stages collapse into the most urgent reminder for each window
• Configurable: Choose your own schedule with cn usage reset-reminders set 24,6,1, or disable it with cn usage reset-reminders off

Update and verify the installed version:

cn update
code-notify version

v1.13.1 maintenance fix: cn status no longer reports REPAIR NEEDED for the current Claude ask_user hook format, while genuine legacy hooks remain repairable.

Usage alerts remain opt-in: start with cn usage setup --watch. Existing enabled usage configs without a reset_reminders setting use the default reminder schedule. After updating, restart any running watcher with cn usage watch restart (include your provider and interval options if customized).

Voice samples: Daily reset · Weekly reset

What's New in v1.13.1

• Accurate Claude status: Current ask_user hooks using PreToolUse claude are recognized as enabled instead of legacy
• No repair loop: Re-running cn on claude is no longer suggested for a configuration Code-Notify just installed
• Legacy compatibility retained: Older PreToolUse commands without the Claude tool argument are still detected for repair

Features

• Multi-tool support - Claude Code, OpenAI Codex, Google Gemini CLI, Oh My Pi (omp)
• Works everywhere - Terminal, VSCode, Cursor, or any editor
• Cross-platform - macOS, Linux, Windows
• Native notifications - Uses system notification APIs
• macOS click-through control - Choose which app notification clicks activate
• Sound notifications - Play custom sounds on task completion
• Voice announcements - Hear when tasks complete (macOS, Windows)
• Slack/Discord delivery - Mirror notifications to incoming webhooks
• Usage alerts - Opt-in Codex/Claude 20%, 10%, advance reset reminders, and reset notifications (macOS/Linux)
• Tool-specific messages - "Claude completed the task", "Codex completed the task", "omp completed the task"
• Project-specific settings - Different configs per project
• Quick aliases - cn and cnp for fast access

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 AI Coding Agents

Paste this to your AI coding agent (Claude Code, Codex, Cursor, Gemini CLI, etc.):

Install code-notify using npm only. Prefer npm over curl or git clone.

npm install -g code-notify
cn on all
cn test
cn status

Expected result:

• cn test shows a desktop notification.
• cn status shows enabled tools.

If npm is unavailable, use the fallback installer in docs/installation.md.

Agent-friendly command block:

npm install -g code-notify
cn on all
cn test

npm packages are published with GitHub Actions Trusted Publisher and npm provenance. The npm postinstall script only performs global-install bootstrap tasks: on macOS/Linux it quietly repairs legacy Claude hook paths, and on Windows it bootstraps the local PowerShell wrapper. Set CODE_NOTIFY_SKIP_POSTINSTALL=1 to skip those install-time helpers.

Usage

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
• Oh My Pi (omp): ~/.omp/agent/extensions/code-notify.js

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. On macOS, when a Codex session runs through T3 Code, Code-Notify uses the payload's thread-id to resolve the matching title from T3 Code's local state. If T3 Code is unavailable or no matching thread exists, it falls back to the workspace name.

For omp, Code-Notify writes a small managed extension module to ~/.omp/agent/extensions/code-notify.js, because omp loads extension modules instead of reading hook commands from a config file. The extension forwards omp's agent_end event to the same notifier.sh, so sound, voice, Slack/Discord channels, click-through, the global mute switch, and rate limiting all work unchanged. Like Codex, omp currently exposes completion events; approval and idle prompts are not yet wired.

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" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "notify.sh SubagentStop 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 n