Code-Notify CLI
Code-Notify sends a desktop notification when Claude Code, Codex or Gemini CLI finishes a task or waits for your input
- 291 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Edits Claude Code, Codex and Gemini CLI configuration: it adds hooks that run a script on each agent event
- Notification texts go to Slack or Discord once a webhook is enabled
- The npm `postinstall` script changes Claude hook paths on macOS and Linux during install
Install
- Works in
Manual install
npm install -g code-notifyWorks on macOS, Linux and Windows. Then `cn on all`, `cn test` and `cn status`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Edits Claude Code, Codex and Gemini CLI configuration: it adds hooks that run a script on each agent event
- Notification texts go to Slack or Discord once a webhook is enabled
- The npm `postinstall` script changes Claude hook paths on macOS and Linux during install
This is third-party code. Review the repository files before installing.
What it does
Code-Notify is a command-line utility `cn` (also `code-notify`). It hooks into Claude Code, Codex, Gemini CLI and Oh My Pi and shows a system notification when the agent finishes or waits for input. `cn on` enables every detected tool, `cn on claude` just one, and `cnp on` the current project. By default the alert fires when the agent sits idle waiting for an answer (`idle_prompt`). The `cn alerts` command adds permission prompts, agent questions (`ask_user`) and subagent completion. A notification can also play a sound, speak an announcement on macOS and Windows and mirror to Slack or Discord through incoming webhooks. A separate feature for macOS and Linux covers usage limits. `cn usage setup --watch` follows the Codex and Claude quota and alerts at 20 and 10 percent left. Before the weekly limit resets it sends reminders 48, 24, 12, 6 and 2 hours and 30 minutes ahead, and `cn usage reset-reminders set 24,6,1` changes the schedule.
Who it is for. People who run agents in a terminal or editor and work in other windows while a long task runs.
Good fit when
- A long task runs in Claude Code or Codex while you read mail or write code in another window
- The agent is stuck on a permission prompt and the idle time costs you: the `permission_prompt` type signals at once
- Notifications are wanted in one project only: `cnp on` enables them locally and leaves the rest alone
- You want task status in a team Slack or Discord channel through an incoming webhook
- The weekly Codex or Claude quota is running out and you need to act before the limit resets
Not a fit when
- You want Codex permission prompts in notifications: it passes the hook only a completion event
- You need control over what the agent does: the utility reports events and blocks nothing
- You want limit alerts on Windows: `cn usage` works on macOS and Linux, including WSL
- You want a spoken announcement on Linux: it exists only on macOS and Windows
Example request
Install Code-Notify, enable notifications for Claude Code and Codex and confirm with cn test that a message appears on the desktop.Limitations
- Codex passes the hook only a completion event, so Codex permission prompts and `request_permissions` do not arrive as notifications.
- Limit alerts work on macOS and Linux, including WSL, and are enabled separately with `cn usage setup --watch`.
- Spoken announcements are available on macOS and Windows.
- Installation edits agent configuration: `~/.claude/settings.json`, `~/.codex/config.toml`, `~/.gemini/settings.json`. The npm `postinstall` script on macOS and Linux quietly repairs legacy Claude hook paths.
How to disable. `cn off` disables notifications for every tool and `cn off claude` for one. Remove the utility itself with the package manager you installed it with, npm or Homebrew.
FAQ
How do I enable notifications for Claude Code and Codex?
Install the package with `npm install -g code-notify` and run `cn on`: the utility finds installed tools and writes the hooks. `cn test` shows a test notification and `cn status` lists the enabled tools.
Do permission prompts produce notifications?
In Claude Code yes, once you add the type with `cn alerts add permission_prompt`. In Codex no: it passes the hook only a completion event.
Can messages go to Slack or Discord?
Yes, through incoming webhooks. The `cn channels` command sets up delivery and events are mirrored to the chosen channel.
How do I check that the hooks are on?
`cn status` shows the enabled tools and `cn test` sends a test notification. Hooks from the older claude-notify layout are repaired automatically by supported upgrades.
Which events can be enabled?
By default the alert fires when the agent is idle (`idle_prompt`). `cn alerts` shows the current settings and `cn alerts add` adds `permission_prompt`, `ask_user` and `SubagentStop`.
Discussion
No questions or reviews yet.
Related
CLI toolsClaude Code hooks for macOS: a notification returns you to the original terminal window, and a push reaches your phone when idle.
Agent Notifications is an alert plugin that includes project and branch context in Claude Code and Codex desktop messages.
Hook-driven sounds for coding agents: starts, failures, completions and even individual Bash commands each get their own cue
A limits and token spend monitor for Claude Code, Codex, Antigravity and Grok CLI: macOS menu bar, Windows tray, HTML reports
A Windows and Linux tray app shows Claude rate limits and reports the remaining quota to an agent via a built-in MCP server.
CodeKanban gathers terminals and Claude Code and Codex sessions on one page, and codekanban-cli drives them from an agent
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Code-Notify (this card) | no | 291 | |
| peon-ping | no | 5,108 | voice lines from games for events, no Slack mirroring and no limit reminders |
| Agent Notifications | no | 826 | a plugin that adds the project and branch to Claude Code and Codex messages for parallel tasks |
README in short
The README opens with links to downloads, Homebrew and npm, then covers the latest feature, usage reset reminders, and the utility's capabilities. After that come installation for humans and a ready block for AI agents, a command table, how the hooks work, alert types and sound, voice and channel settings.