README
¶
Agent Notifications
Desktop notifications for Claude, Codex CLI and OpenCode, plus Gemini CLI on Linux/Windows. Know when a task finishes, an agent needs input, or a tool needs approval. Claude and Codex also support sounds and click-to-focus.
Install Or Update
Guided installer or run:
curl -fsSL https://agent-notifications.com/install.sh | bash
Choose Claude, Codex CLI, OpenCode, Gemini CLI (Linux/Windows), or a combination. Install the selected agent CLIs first. Run the same command to update.
Windows: use Git Bash, not WSL, for a native Windows installation.
After setup:
- Claude: restart Claude.
- Codex: restart Codex, then review and trust the installed hooks in
/hooks. - OpenCode: restart OpenCode; on macOS, grant notification permission.
- Gemini CLI (Linux/Windows): restart Gemini to reload its hooks.
The installer selects a verified complete release for your platform:
| Platform | Version | Agents |
|---|---|---|
| Linux amd64 / arm64 | 1.48.1 | Claude, Codex, OpenCode, Gemini |
| Windows amd64 | 1.48.1 | Claude, Codex, OpenCode, Gemini |
| macOS amd64 / arm64 | 1.48.3 | Claude, Codex, OpenCode |
Run the command once to migrate a normal Claude marketplace installation to its platform channel. Claude's plugin updater then follows that channel; rerun setup to update a standalone Codex bundle. Explicitly pinned/custom marketplace sources are retained.
macOS 1.48.3 includes Intel and Apple Silicon binaries, portable packages and the signed, notarized ClaudeNotifier.app helper. Linux and Windows remain on 1.48.1. GitHub's global Latest stays 1.46.1 for older installers; the current installer selects the release from platform channels.
Non-interactive installation and optional notification tools
For Codex only:
(set -o pipefail; curl -fsSL https://agent-notifications.com/install.sh | bash -s -- --product codex)
Use --product claude or --product both for Claude or Claude + Codex. For Claude, Codex and OpenCode on any supported platform:
(set -o pipefail; curl -fsSL https://agent-notifications.com/install.sh | bash -s -- --products claude,codex,opencode --desktop)
On Linux/Windows, add ,gemini to --products for all four agents, or use --product gemini for Gemini only. For OpenCode/Gemini, choose --desktop, --webhook, or both; webhook destinations need separate configuration. These flags do not change Claude/Codex channels.
Claude/Codex setup also installs the agent-notify MCP server and agent-notifications skill so an agent can notify you during a task. Open a new session after setup. Use --skip-agent-notify for hooks only. Setup and recovery details.
Manual installation · Manual Codex registration · Uninstall · Troubleshooting
Features
- Task and attention alerts: completions, questions, tool approvals and more, depending on the agent. See the table below.
- Click-to-focus and sounds (Claude/Codex): return to the originating terminal or editor; choose built-in or custom sounds, volume and audio output. Supported terminals · Sound settings
- Useful context: Claude/Codex show project, git branch and native session names, with generated labels as fallback. OpenCode desktop alerts show native session names when available. Question alerts show the current question when supplied by the host. OpenCode webhooks retain generic text. Session context · OpenCode context
- Less noise: focus-aware delivery, delays, filters and optional subagent alerts. Configuration · Do Not Disturb
- Webhooks: Slack, Discord, Telegram, Lark/Feishu and custom endpoints. Integration guides
- Cross-platform: macOS (Intel/Apple Silicon), Linux (x64/ARM64) and Windows 10+ (x64). Agent and delivery limits are listed below. Platform details
Supported Agents
| Agent | Alerts | Sounds / click-to-focus | Details |
|---|---|---|---|
| Claude | Completions, reviews, questions, plans, session limits and API errors | Yes | Notification types |
| Codex CLI | Turn completion and tool permissions; questions and errors depend on host events or final-message detection | Yes | Setup and limits |
| OpenCode | Root-session completion, questions, permissions and errors | No | Setup and limits |
| Gemini CLI | Turn completion and tool permissions | No | Linux/Windows setup and qualification |
Agent Notifications 1.48.1 on Linux/Windows and 1.48.3 on macOS supports OpenCode V1 and V2 with one installed plugin. Linux/Windows release qualification covers V1 1.18.33 and V2 2.0.21, plus V1 1.18.34 on Linux amd64. macOS has four installed basic-business/lifecycle checks across V1 1.18.33 and V2 2.0.21: Apple Silicon ran natively, while Intel binaries ran under Rosetta. These checks do not prove physical Intel execution, full native E2E or visible OpenCode banners for this release.
The self-contained bundle incorporates SDK 0.3.0 from its reviewed vendored tarball; separate SDK publication is not required. Setup, release reports and delivery limits. Gemini is tested with 0.62.0; a completed turn does not necessarily mean task success or a final answer. OpenCode/Gemini alerts require explicit desktop/webhook consent. Gemini alerts and OpenCode webhooks use generic text. OpenCode desktop alerts may include bounded native session titles and current question text.
For OpenCode on stock Windows V1, the original event age is not always independently verifiable. A delayed completion may notify once and recur after the 24-hour claim lifetime; filters, provenance, deduplication and limits still apply. One-shot opencode run delivery at host shutdown is best effort; use a persistent host for sustained delivery.
Settings
In Claude, run /claude-notifications-go:settings for the settings wizard or /claude-notifications-go:sounds to preview sounds.
Use the installed launcher to find or safely inspect settings. The commands below assume agent-notifications is on your PATH; otherwise, use its full path.
agent-notifications config path
agent-notifications config inspect --json
Settings are shared, with optional per-agent overrides. The claude-notifications alias and Claude's existing slash-command names remain supported.
Configuration reference · Per-agent overrides · Sound previews
Documentation
- Installation, updates and removal
- Notification types and click-to-focus
- Webhooks
- Troubleshooting and plugin compatibility
- Architecture and local development
- Changelog
Built with Universal Agent Plugins. Build plugins for multiple AI agents.
Contributing
See CONTRIBUTING.md for development and testing. Pull requests are subject to the Contributor License Agreement; contributors keep copyright.
GPL-3.0-or-later. See LICENSE and third-party notices.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
build-portable-package
command
Command build-portable-package writes the version-bound Agent Notify portable zip for one GOOS/GOARCH using the already-built release executable.
|
Command build-portable-package writes the version-bound Agent Notify portable zip for one GOOS/GOARCH using the already-built release executable. |
|
claude-notifications
command
|
|
|
list-devices
command
|
|
|
list-sounds
command
|
|
|
sound-preview
command
ABOUTME: CLI tool for previewing notification sounds with optional device selection.
|
ABOUTME: CLI tool for previewing notification sounds with optional device selection. |
|
Package configtemplate owns the packaged default document used by future Store initialization.
|
Package configtemplate owns the packaged default document used by future Store initialization. |
|
install
|
|
|
uapinstaller
Package uapinstaller is a compatibility import path for Notifications.
|
Package uapinstaller is a compatibility import path for Notifications. |
|
internal
|
|
|
agentnotify
Package agentnotify orchestrates explicit notifications over injected ports.
|
Package agentnotify orchestrates explicit notifications over injected ports. |
|
agentnotify/cli
Package cli implements the bounded, one-shot notify command, without global initialization.
|
Package cli implements the bounded, one-shot notify command, without global initialization. |
|
agentnotify/clientsetup
Package clientsetup persists one managed MCP registration, without activation.
|
Package clientsetup persists one managed MCP registration, without activation. |
|
agentnotify/journal
Package journal implements durable admission only.
|
Package journal implements durable admission only. |
|
agentnotify/mcp
Package mcp provides an independently composed, bounded SDK adapter.
|
Package mcp provides an independently composed, bounded SDK adapter. |
|
agentnotify/origin
Package origin contains transport-supplied identity and pure routing helpers.
|
Package origin contains transport-supplied identity and pure routing helpers. |
|
agentnotify/portable
Package portable selects an explicitly registered installed runtime.
|
Package portable selects an explicitly registered installed runtime. |
|
agentnotify/portableasset
Package portableasset builds and extracts the version-bound Agent Notify portable package.
|
Package portableasset builds and extracts the version-bound Agent Notify portable package. |
|
agentnotify/portablesetup
Package portablesetup binds a UAP materialization to the existing-installer kernel and private locator.
|
Package portablesetup binds a UAP materialization to the existing-installer kernel and private locator. |
|
agentnotify/registration
Package registration performs pure, bounded managed MCP configuration edits.
|
Package registration performs pure, bounded managed MCP configuration edits. |
|
agentnotify/runtime
Package runtime composes explicit notifications.
|
Package runtime composes explicit notifications. |
|
agentnotify/setup
Package setup is the trusted existing-installer opt-in use case.
|
Package setup is the trusted existing-installer opt-in use case. |
|
agentnotify/setupwizard
Package setupwizard is the P6 application service for setup-notifications wizard.
|
Package setupwizard is the P6 application service for setup-notifications wizard. |
|
claudesource
Package claudesource adapts legacy Claude Code hook input through the typed plugin-kit-ai Claude SDK.
|
Package claudesource adapts legacy Claude Code hook input through the typed plugin-kit-ai Claude SDK. |
|
codexsetup
Package codexsetup registers this plugin's hooks with the Codex CLI.
|
Package codexsetup registers this plugin's hooks with the Codex CLI. |
|
codexsource
Package codexsource is the only product package that imports plugin-kit-ai/sdk.
|
Package codexsource is the only product package that imports plugin-kit-ai/sdk. |
|
copilotvscodeevent
Package copilotvscodeevent owns Local admission, fixed informational copy and private observation claims.
|
Package copilotvscodeevent owns Local admission, fixed informational copy and private observation claims. |
|
copilotvscodeinstall
Package copilotvscodeinstall owns binding-scoped Local consent and effect authority.
|
Package copilotvscodeinstall owns binding-scoped Local consent and effect authority. |
|
copilotvscodesource
Package copilotvscodesource is the only Local SDK boundary.
|
Package copilotvscodesource is the only Local SDK boundary. |
|
cursorevent
Package cursorevent owns Cursor admission, fixed informational copy and private observation claims.
|
Package cursorevent owns Cursor admission, fixed informational copy and private observation claims. |
|
cursorinstall
Package cursorinstall supplies only the vendor mechanics for the explicitly selected Cursor user Stop route.
|
Package cursorinstall supplies only the vendor mechanics for the explicitly selected Cursor user Stop route. |
|
cursorsource
Package cursorsource is the Cursor public SDK boundary.
|
Package cursorsource is the Cursor public SDK boundary. |
|
daemon
ABOUTME: Client library for communicating with the notification daemon.
|
ABOUTME: Client library for communicating with the notification daemon. |
|
geminievent
Package geminievent owns Gemini's business admission and fixed delivery copy.
|
Package geminievent owns Gemini's business admission and fixed delivery copy. |
|
geminiinstall
Package geminiinstall owns the explicit Gemini notification lifecycle.
|
Package geminiinstall owns the explicit Gemini notification lifecycle. |
|
geminisource
Package geminisource keeps SDK inputs and private native text inside the typed source boundary.
|
Package geminisource keeps SDK inputs and private native text inside the typed source boundary. |
|
installruntime
Package installruntime owns the shared installation transaction primitives.
|
Package installruntime owns the shared installation transaction primitives. |
|
linuxcallback
Package linuxcallback owns the installed Linux portal callback, not producer policy.
|
Package linuxcallback owns the installed Linux portal callback, not producer policy. |
|
notification
Package notification defines the agent-independent delivery boundary.
|
Package notification defines the agent-independent delivery boundary. |
|
notification/observation
Package observation bounds notification work with a same-boot continuous clock.
|
Package observation bounds notification work with a same-boot continuous clock. |
|
notifier
ABOUTME: terminal-bell delivery on Unix-likes — write BEL to /dev/tty, with a ABOUTME: tmux pane-tty fallback for hook subprocesses that lack a controlling tty.
|
ABOUTME: terminal-bell delivery on Unix-likes — write BEL to /dev/tty, with a ABOUTME: tmux pane-tty fallback for hook subprocesses that lack a controlling tty. |
|
notifier/nativeprotocol
Package nativeprotocol validates the versioned native helper replies.
|
Package nativeprotocol validates the versioned native helper replies. |
|
opencodecodec
Package opencodecodec contains pure private composition comparisons.
|
Package opencodecodec contains pure private composition comparisons. |
|
opencodeevent
Package opencodeevent consumes the bounded, neutral OpenCode observer wire.
|
Package opencodeevent consumes the bounded, neutral OpenCode observer wire. |
|
opencodeinstall
Package opencodeinstall owns the explicit OpenCode notification lifecycle.
|
Package opencodeinstall owns the explicit OpenCode notification lifecycle. |
|
opencodeplugin
Package opencodeplugin embeds the exact, self-contained OpenCode product plugin.
|
Package opencodeplugin embeds the exact, self-contained OpenCode product plugin. |
|
strictjson
Package strictjson validates bounded JSON without normalizing strings.
|
Package strictjson validates bounded JSON without normalizing strings. |
|
testenv
Package testenv provides a complete disposable environment for filesystem tests.
|
Package testenv provides a complete disposable environment for filesystem tests. |
|
thirdpartynotices
Package thirdpartynotices provides the canonical terminal dependency notices for the executable and its distribution packages.
|
Package thirdpartynotices provides the canonical terminal dependency notices for the executable and its distribution packages. |
|
warpfocus
ABOUTME: Warp session deep-link capture for click-to-focus.
|
ABOUTME: Warp session deep-link capture for click-to-focus. |
|
windowscallback
Package windowscallback owns the retained Windows callback contract.
|
Package windowscallback owns the retained Windows callback contract. |
|
winfocus
ABOUTME: Windows click-to-focus support — encodes the terminal window to raise ABOUTME: into a toast protocol-activation URI, decoded when the notification is clicked.
|
ABOUTME: Windows click-to-focus support — encodes the terminal window to raise ABOUTME: into a toast protocol-activation URI, decoded when the notification is clicked. |
|
pkg
|
|
|
This E2E fixture makes the disposable sandbox inherit the installer's private ACL.
|
This E2E fixture makes the disposable sandbox inherit the installer's private ACL. |
|
Package skills exposes the canonical skill compiled into the verified installer.
|
Package skills exposes the canonical skill compiled into the verified installer. |
|
tests
|
|
|
integration/gemini_frame_classifier
command
The TEST orchestrator supplies already captured synthetic frames.
|
The TEST orchestrator supplies already captured synthetic frames. |
|
integration/navigation_linux_vendor_verify_probe
command
TEST-only read-only measurement; process collection belongs to the guest driver.
|
TEST-only read-only measurement; process collection belongs to the guest driver. |