agent-notifications

module

v1.48.7 Latest Latest Go to latest Published: Oct 11, 2026 License: GPL-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/777genius/agent-notifications

Links

Open Source Insights

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.

macOS, Windows, Linux (left to right)

Install Or Update

Guided installer or run:

(set -o pipefail; 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 and make them available on PATH. The installer also requires curl, Bash, and a working python3 or node on PATH; see agent/platform prerequisites. 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 release from the platform channels for your OS and architecture. See that page for current versions and the release notes for validation details and known limitations.

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.

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. Fresh OpenCode/Gemini setup defaults to desktop notifications with webhooks off; updates preserve saved channel choices when no channel flags are supplied. Explicit flags replace the channel pair: --desktop enables desktop only, --webhook enables webhooks only, and both enable 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. When an existing managed MCP installation or binding is detected, automatic setup keeps absent clients off; use --agent-notify to add them explicitly. Use --skip-agent-notify to skip their setup for that run; it neither removes an existing MCP installation nor records a permanent opt-out. 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): focus the originating terminal or editor where supported; choose built-in or custom sounds, volume and audio output. Supported terminals · Sound settings
Useful context: Claude/Codex desktop alerts 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 (Claude/Codex): optional focus-aware desktop delivery, delays, filters and subagent alerts. Plugin-level Do Not Disturb detection is Linux-only. 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; experimental question hooks and final-message question/error 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

OpenCode V1 and V2 use one installed plugin. The installer accepts stable V1 >= 1.18.29 and V2 >= 2.0.0; prereleases and unknown API generations are rejected. This compatibility range does not mean every version has been tested. See OpenCode setup, release reports and delivery limits for qualification of specific versions and platforms.

The installer requires exactly Gemini CLI 0.62.0. See the Gemini guide for platform evidence and limits. A completed Gemini turn does not necessarily mean task success or a final answer. Gemini alerts and OpenCode webhooks use generic text; OpenCode desktop alerts may include native session titles and current question text. Gemini's built-in notifications can cause duplicate desktop alerts; choose one desktop source or use Agent Notifications for webhooks only.

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. You can request sound previews during the wizard.

For Claude/Codex, 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

Claude/Codex share settings, with optional per-agent overrides after an explicit upgrade to configuration schema 2. The claude-notifications alias and Claude's existing slash-command names remain supported.

Managed OpenCode uses a separate settings target:

agent-notifications config path --target opencode --json
agent-notifications config inspect --target opencode --json

Use the executable and control root reported by its installer. See OpenCode settings and Gemini settings for agent-specific configuration and channel consent.

Configuration reference · Per-agent overrides · Sound previews

Documentation

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 ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

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.
config 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.
analyzer
audio
benchmark
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.
codexcommand Package codexcommand contains only the frozen Codex hook command codec.	Package codexcommand contains only the frozen Codex hook command codec.
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.
config
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.
dedup
errorhandler
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.
hooks
installprogress Package installprogress presents shell-owned installer state.	Package installprogress presents shell-owned installer state.
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.
logging
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.
platform
sessionname
sounds
state
strictjson Package strictjson validates bounded JSON without normalizing strings.	Package strictjson validates bounded JSON without normalizing strings.
summary
teamstate
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.
webhook
windowsacl
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
jsonl
scripts 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.
skills 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.