Agent Notifications for Claude Code and Codex CLI: Cross-Platform Desktop Alerts With Click-to-Focus

What Agent Notifications solves for Claude Code and Codex CLI users

Long agent runs are quiet. You start Claude Code on a refactor, switch to email, and come back twenty minutes later to find the session stopped at a question or hit a session limit. Agent Notifications exists to close that gap: it listens for agent events and raises a desktop notification, plays a sound, and optionally posts to a webhook.

The README lists the Claude notification types it handles: Task Complete, Review Complete, Question, Plan Ready, Session Limit and API Error. That list is the real scope of the tool. It is not a general monitoring system, and it does not inspect what the agent produced. It reacts to lifecycle events the agent already emits.

The intended user is a developer running Claude Code or Codex CLI locally, often in a terminal multiplexer, who wants the window to come forward when something needs attention. The click-to-focus feature is the part that distinguishes it from a plain `notify-send` script: clicking the notification focuses the exact project window and tab, and the README names Ghostty, VS Code, iTerm2, Warp, kitty, WezTerm, Alacritty, Hyper, Apple Terminal, GNOME Terminal, Konsole, Tilix, Terminator, XFCE4 Terminal and MATE Terminal as supported terminals.

How the notification pipeline works, from hook to desktop alert

The repository is a Go module (`github.com/777genius/agent-notifications`, Go 1.22) with a `cmd/` directory holding at least three binaries: `claude-notifications`, `sound-preview` and `list-sounds`. The Makefile builds all three into `bin/`.

Notification delivery is not written from scratch. The dependency list shows platform-specific libraries: `git.sr.ht/~jackmordaunt/go-toast` for Windows toasts, `github.com/esiqveland/notify` plus `github.com/godbus/dbus/v5` for Linux desktop notifications over D-Bus, and `github.com/gen2brain/beeep` as a cross-platform fallback. Audio goes through `github.com/gen2brain/malgo` and `github.com/gopxl/beep`, with decoders for MP3, OGG/Vorbis, FLAC and AIFF pulled in as indirect dependencies. That matches the README's claim of MP3, WAV, FLAC, OGG and AIFF support.

The plugin side is less visible. There is a `.claude-plugin/` directory, a `.codex-plugin/` directory, a `hooks/` directory and a `commands/` directory, and the README describes running `/claude-notifications-go:settings` and, for Codex, `/hooks`. The README also refers to a plugin SDK dependency, `github.com/777genius/plugin-kit-ai/sdk`. Beyond that, the README does not document the internal event schema or how a hook payload maps to a notification type.

Webhook delivery is the one part with its own documentation file, `docs/webhooks/README.md`. The README states that webhooks support retry, circuit breaker and rate limiting, and lists Slack, Discord, Telegram, Lark/Feishu, Microsoft Teams, ntfy.sh, PagerDuty, Zapier, n8n, Make and custom endpoints. Those three reliability mechanisms are a design signal: the author expects webhook endpoints to fail or rate-limit, and chose to absorb that inside the plugin rather than surface every failure to the user.

Installing Agent Notifications and sending a first notification

The README's recommended path is a bootstrap script. It requires Python 3.6 or newer available as `python3` on PATH, which the installer uses for metadata and checksum validation. On Windows the README is specific: use Git Bash, and use native Windows Python reachable as `python3` from Git Bash, not WSL Python.

The interactive installer asks which product to configure:

curl -fsSL https://raw.githubusercontent.com/777genius/agent-notifications/main/bin/bootstrap.sh | bash

For automation, or terminals without a controlling TTY, pass the product explicitly. The accepted values are `claude`, `codex` or `both`:

curl -fsSL https://raw.githubusercontent.com/777genius/agent-notifications/main/bin/bootstrap.sh | bash -s -- --product codex

After that, the two products diverge. For Claude, restart Claude Code, then optionally run the settings command to configure sounds:

/claude-notifications-go:settings

For Codex, start Codex, run `/hooks`, and review and trust the installed hooks. The README says the installer registers them automatically and that no JSON editing or manual registration command is needed, but trust approval stays with you.

If the bootstrap fails, the README points to a manual Claude path using slash commands inside the Claude Code chat, starting with `/plugin marketplace add 777genius/agent-notifications` and `/plugin install claude-notifications-go@claude-notifications-go`, followed by `/claude-notifications-go:init` to download the binary. The README also documents a `Makefile` target named `build` that compiles the binaries locally with `go build`.

Codex CLI support is beta, and the README says so

The README marks Codex CLI support as beta in the heading of its own section and again in the top summary, and it tells readers to check that section for differences between products. That is a real limitation, not a formality.

The concrete constraint is versioning. Codex requires a published stable plugin release v1.42.0 or newer. The installer downloads matching source and binaries, respects `CODEX_HOME`, and keeps a permanent runtime copy there. If no supported release is published, the installer reports an error rather than falling back.

The most recent releases listed are v1.41.0 (2026-08-30), v1.40.1 (2026-07-16) and v1.40.0 (2026-06-22). None of those meets the v1.42.0 threshold the README states for Codex. So the Codex path depends on a release that is not in the release list provided, and a user following the Codex instructions should verify availability before assuming the installer will succeed. The Claude path has no equivalent version gate in the README.

There is a second, quieter limitation. The README's feature list is written around Claude notification types (Task Complete, Review Complete, Question, Plan Ready, Session Limit, API Error). Which of those map onto Codex hooks is exactly the kind of difference the beta section is meant to cover, and the README does not enumerate it.

Where Agent Notifications is the wrong tool

This plugin is a local convenience layer. It assumes an agent process is running on the same machine and emitting events. If you want notifications when a remote build finishes, when a CI job fails, or when a scheduled task runs without an agent session, this is not the tool: nothing in the README describes a server, a daemon that outlives the agent, or a way to trigger a notification from an arbitrary command.

Click-to-focus is also narrower than it sounds. The README limits it to macOS and Linux, and it depends on the terminal emulator being one of the listed ones. If you run your agent inside something not on that list, or inside a multiplexer arrangement the README does not cover, you still get the alert but lose the reason to prefer this over a shell one-liner.

Finally, the installer's Python dependency is easy to miss. A machine with only a `python` or `py` command, or a Windows setup where the shell resolves to WSL Python, will fail the checksum step. The README calls this out, but it is the kind of prerequisite that surfaces as an opaque install failure rather than a clear message.

How it compares with terminal-notifier and a plain notify-send hook

The obvious alternative is wiring the agent's own hook to a system notifier: `terminal-notifier` on macOS, `notify-send` on Linux, or a PowerShell toast on Windows. That approach has no install step beyond the notifier itself and no Python prerequisite, and it is trivial to read and modify.

The difference in approach is what happens after the alert appears. A `notify-send` call produces a notification with no knowledge of which project, which terminal, or which tmux pane generated it. Agent Notifications carries that context: the README shows the git branch embedded in the title, and it documents click-to-focus across terminals plus tmux, zellij, WezTerm and kitty, including iTerm2 `-CC` integration mode.

The other difference is delivery breadth. A shell hook gives you one channel. Agent Notifications adds sounds with volume and audio device selection, and webhooks to Slack, Discord, Telegram, Lark/Feishu, Microsoft Teams, ntfy.sh, PagerDuty, Zapier, n8n, Make or a custom endpoint, with retry, circuit breaker and rate limiting handled inside the plugin. If you only ever want a desktop popup, the shell hook is less machinery. If you want the right tab to come forward, the shell hook cannot do it.

Maintenance, updates and what the licence leaves open

The repository is not archived, and the last push was on 2026-09-10. Releases have been frequent: v1.40.0 in June 2026, v1.40.1 in July, v1.41.0 in August, with a wide gap between v1.40.0 and v1.40.1 that suggests the cadence is not fixed.

Updating is the same command as installing. The README says to run the bootstrap again and choose the products to update, then restart Claude Code for Claude and restart Codex for Codex. There is no documented rollback procedure, no version pinning flag in the README, and no documented way to stay on an older release. If an update breaks your setup, the README does not describe a path back.

The licence is the least settled part. The repository metadata reports `NOASSERTION`, meaning GitHub could not map the `LICENSE` file to a known identifier, and the README's Licence section is not included in the README text available here. Before adopting this in a commercial environment, read the `LICENSE` file in the repository root yourself and, if the terms matter to your organisation, have someone qualified review them. Nothing here should be read as legal advice.

Editorial conclusion

Adopt it if you run Claude Code or Codex CLI in long unattended sessions and want a desktop alert that focuses the right terminal tab, and if you already have python3 on PATH because the installer requires it. Skip it if you need notification routing that survives a reboot without a running agent, or if you cannot accept beta-quality Codex support. Before installing, verify your python3 version and, for Codex, confirm that the plugin release you are pulling is v1.42.0 or newer.

Frequently asked questions

Official sources

1. 777genius/agent-notifications on GitHub
2. Issues
3. Project website
4. README
5. Releases