agent-notifications: desktop alerts for Claude Code and Codex CLI sessions
🔔 Cross-platform smart notifications for Claude and Codex. Desktop alerts, sounds, click-to-focus, and webhooks on macOS, Linux, and Windows.
At a glance
- What is it?
- A Go plugin that turns Claude Code and Codex CLI lifecycle events into desktop notifications, sounds and webhooks. It solves the problem of watching a terminal while an agent works, and it does so with a per-platform focus mechanism that is the most interesting and most fragile part of the design.
- Who is it for?
- Adopt it if you run Claude Code in a terminal or tmux and lose track of which session finished, and if you want Slack or ntfy webhooks without writing your own hook scripts. Do not adopt it if you are on Codex and need the same feature set, since the README labels Codex support beta and points to its own limitations section.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is knowing which of your agent sessions just stopped
Agent CLI sessions run for minutes and end quietly. A Claude Code task finishes, prints a summary, and waits. If you started it in a tmux pane and switched to another window, that completion is invisible until you look. The same applies to a question the agent asks mid-task: the session blocks until you answer, and nothing on screen tells you. agent-notifications exists to close that gap. It hooks into Claude Code and Codex CLI events and pushes them out through the operating system notification layer, optionally with a sound and optionally to a chat service. The README lists six Claude notification types: Task Complete, Review Complete, Question, Plan Ready, Session Limit and API Error. That list is the scope of the project. It is not a general desktop notification daemon, and it does not try to summarise what the agent did. It tells you an event happened and, where the platform allows it, takes you back to the exact window and tab that produced it. The audience is narrow and specific: developers who already run Claude Code or Codex CLI, usually more than one session at a time, often inside tmux or a terminal that supports tabs, and who want the terminal to behave like an IDE that can interrupt them.
Click-to-focus is the mechanism worth understanding
Most of this project is plumbing. The part that carries real design weight is click-to-focus, and the README is explicit that it works on macOS and Linux only, not Windows. When a notification arrives, clicking it is supposed to focus the project window and tab that generated the event. The README names the terminals it supports: Ghostty, VS Code, iTerm2, Warp, kitty, WezTerm, Alacritty, Hyper, Apple Terminal, GNOME Terminal, Konsole, Tilix, Terminator, XFCE4 Terminal and MATE Terminal. It also names the multiplexers: tmux, including iTerm2's -CC integration mode, plus zellij, WezTerm and kitty, where clicking switches to the correct session, pane or tab. That is a long support matrix, and it is the source of both the project's value and its fragility. Focusing a specific pane inside tmux is not a notification API call. It requires the hook to know which terminal emulator is running, which multiplexer session and pane the agent occupies, and how to drive that emulator's window activation. Each entry in that list is a separate integration path. The practical consequence is that the feature you care about most is the one most likely to break when you change terminal or upgrade one. The README does not describe fallback behaviour when the terminal is not recognised. If your emulator is not on the list, the notification should still appear, but the click behaviour is undocumented. The README also notes a compatibility concern: the plugin is stated to work with double-shot-latte and other plugins that spawn background Claude instances. That matters because background instances generate their own events, and a notification system that cannot distinguish them will spam you.
Installing it, and the Python dependency that trips people up
The recommended path is a single bootstrap script. The README gives this command: curl -fsSL https://raw.githubusercontent.com/777genius/agent-notifications/main/bin/bootstrap.sh | bash. The script presents an interactive menu asking which product to install for. For automation, or terminals without a controlling TTY, the README shows passing the product explicitly: curl -fsSL https://raw.githubusercontent.com/777genius/agent-notifications/main/bin/bootstrap.sh | bash -s -- --product codex, with claude, codex or both as valid values. The prerequisite that causes the most friction is Python 3.6 or newer, available as python3 on PATH. The README states it is required for installer metadata and checksum validation, and suggests checking with python3 --version. On Windows the requirement is stricter: Git Bash from Git for Windows, plus native Windows Python reachable as python3 from inside Git Bash. The README warns that a python or py command alone is insufficient, and that WSL Python will not do. It also warns against running the curl pipe from PowerShell or Windows Terminal if bash resolves to WSL, because that targets Linux paths and binaries. After install, Claude Code needs a restart, and the optional settings slash command is /claude-notifications-go:settings. Codex needs a different step: start Codex, run /hooks, then review and trust the installed hooks. The installer registers them, but the README is clear that trust approval remains with you. There is also a manual path inside Claude Code using /plugin marketplace add 777genius/agent-notifications, /plugin install claude-notifications-go@claude-notifications-go, then /claude-notifications-go:init to download the binary. Note the ordering: the manual route runs slash commands in the Claude Code chat, not in your system terminal.
Webhooks, sounds and the configuration surface
Beyond desktop alerts, the plugin can forward events to Slack, Discord, Telegram, Lark/Feishu, Microsoft Teams, ntfy.sh, PagerDuty, Zapier, n8n, Make and custom endpoints. The README links a separate webhooks document and states that delivery includes retry, a circuit breaker and rate limiting. Those three mechanisms are the right ones for this problem, because a chat webhook that fails silently is worse than no webhook at all, and an agent that fires an event per step will happily exceed a service's rate limit. The README does not give the default retry count, the circuit breaker threshold or the rate limit values, so if you route to PagerDuty or Teams you will need to read docs/webhooks/README.md before trusting the defaults. Sound support is broader than most terminal notification tools: MP3, WAV, FLAC, OGG and AIFF, with volume control and audio device selection. The README includes a dedicated test sound playback section, which is the right instinct, since audio device selection is one of those settings that looks correct in a config file and produces silence in practice. Notification titles carry the git branch, with the README's example being a checkmark, the word Completed, the branch name main, and a bracketed category cat. That single line is a good design decision: it makes a stack of notifications scannable without opening any of them. Codex support is where the configuration story gets thinner. The README labels it beta and directs readers to a Codex support and limitations section for the differences between products, and it states that Codex requires a published stable plugin release of v1.42.0 or newer. The most recent releases listed are v1.41.0, v1.40.1 and v1.40.0, so the version the Codex path depends on is not among them. The README anticipates this: the installer reports an error if no supported release is published yet.
Where it is the wrong tool
The clearest limitation is Codex. It is beta, it depends on a release version that the listed releases do not include, and the README itself defers to a limitations section rather than claiming parity. If Codex is your primary agent, you are adopting a path the maintainer describes as beta and that may not be installable at all depending on what is published. The second limitation is click-to-focus on Windows, which the README excludes. Windows users get notifications and sounds but not the jump-to-window behaviour, which is the feature that makes the tool more than a noisemaker. The third is the Python 3.6+ and python3-on-PATH requirement. This is an installer dependency, not a runtime one, but it is unusual enough that the README repeats it for both platforms and spells out the Windows edge cases. A machine with only python (no python3) will fail at install, and on Windows a WSL python3 will fail in a way that looks like a path problem rather than a missing dependency. The fourth is the terminal support matrix. Fifteen terminals and four multiplexers is a lot of surface area for a small project, and each integration is a place where an upgrade can silently change behaviour. The README does not document what happens when your terminal is unrecognised, so the graceful-degradation path is unknown. Finally, the licence. The repository metadata reports NOASSERTION, which means GitHub could not map the licence file to a known identifier. The README has a License section but the supplied text does not include its contents. Before using this inside a company, read the actual licence file rather than relying on the metadata. This is not legal advice, just a note that NOASSERTION is a signal to look.
What you would use instead, and how it differs
The obvious alternative is writing your own Claude Code hooks. Claude Code supports hooks, and a shell script that calls notify-send on Linux, osascript on macOS or a PowerShell toast on Windows is perhaps twenty lines. That approach has one advantage this project cannot match: it does exactly what you wrote and nothing else, and it has no installer, no Python dependency and no support matrix. It also has a real disadvantage. Click-to-focus across tmux panes and fifteen terminal emulators is the part that is tedious to build and easy to get subtly wrong, and it is precisely the part you would be reimplementing. Webhook delivery with retry, a circuit breaker and rate limiting is the second such part. So the honest comparison is not features versus no features. It is whether the focus and delivery logic is worth an external dependency. If you run one Claude Code session in a plain terminal and only want a sound, a hook script is the smaller commitment. If you run several sessions in tmux and want clicking a notification to land you in the right pane, the custom script becomes a project. On the webhook side, a generic tool such as ntfy.sh can receive a curl from a hook and forward to your phone, but the retry and circuit-breaker behaviour described in this project's webhooks documentation would be yours to add. The README also points to a companion project from the same author, an advanced task manager for Claude with a UI, which is a different category of tool: it manages tasks rather than notifying about them.
Maintenance cost and what to check before adopting
The release cadence visible in the supplied data shows v1.40.0 in June, v1.40.1 in July and v1.41.0 in August, with a push to main in September. That is frequent enough that you should expect to rerun the bootstrap script periodically rather than install once. Updating is the same command as installing, and the README notes that for Claude you restart Claude Code afterwards. That restart is the real cost: it interrupts running sessions. The dependency chain is the second maintenance item. The installer fetches source and binaries, validates checksums with Python, and for Codex keeps a permanent runtime copy under CODEX_HOME. That means your installed version is tied to what the bootstrap script resolves at run time, not to a version you pinned. If reproducibility matters in your environment, the manual Claude path with /plugin install pins the plugin through the marketplace, but the binary still arrives via /claude-notifications-go:init. The third item is the licence. NOASSERTION in the repository metadata means the terms are not machine-identifiable, and the supplied material does not include the licence text. Read the LICENSE file before you ship this in a product or an internal image. The fourth is the Codex release gate. The README requires stable plugin release v1.42.0 or newer for Codex, and the newest release in the supplied list is v1.41.0. Check what is actually published before planning a Codex rollout, because the installer will error out rather than fall back.
Editorial conclusion
Adopt it if you run Claude Code in a terminal or tmux and lose track of which session finished, and if you want Slack or ntfy webhooks without writing your own hook scripts. Do not adopt it if you are on Codex and need the same feature set, since the README labels Codex support beta and points to its own limitations section. Before installing, verify three things: that python3 is on PATH in the shell you will run the installer from, that the selected agent is already on PATH, and for Codex that release v1.42.0 or newer is published, because the installer reports an error when no supported release exists.
Community notes