Agent Notifications

Built using Universal Agent Plugins

                 

Desktop notifications for Claude, Codex CLI, OpenCode, Gemini CLI, Cursor CLI, Qoder and Pi on macOS, Linux and Windows. Supported architectures and events vary by agent; see the support table and linked guides. Claude, Codex and Pi provide OS-dependent terminal focus where qualified. Qoder CLI, Gemini CLI and Cursor CLI have a separate guarded, explicit opt-in for the originating terminal window on verified local Linux/X11; unsupported or unverified origins remain informational-only. This is window focus, not exact desktop-chat navigation, and installed authenticated CLI-to-click E2E remains unqualified. OpenCode, Gemini and Cursor offer an optional OS-default sound cue; Qoder includes five built-in MP3 assets with separate native audio qualification.

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, Qoder, Cursor CLI, Pi, or a combination. Install the selected agent CLIs first and make them available on PATH. Pi requires its official standalone distribution; on Windows, use the real pi.exe, not an npm pi.cmd shim. The installer also requires curl, Bash, and a working python3 or node on PATH; see agent/platform prerequisites. Run the same command to update.

All seven agents use the common installer with one product selection and channel confirmation, with UAP managing each integration. Fresh OpenCode/Gemini/Qoder/Cursor/Pi installs default to desktop on and webhooks off; updates without channel flags preserve each agent's saved choice, including disabled channels. Cursor CLI sends informational Stop alerts on qualified Linux amd64, macOS arm64 and Windows amd64 hosts; see its profile requirements and limits.

Qoder includes StopFailure error/rate-limit alerts and five bundled MP3s. Native audible qualification remains tracked in #562.

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: restart Gemini to reload its hooks.
• Qoder: install the Qoder CLI first, then reload Qoder to activate its native plugin.
• Cursor CLI: restart Cursor CLI to load its informational Stop observer.
• Pi: restart Pi or run /reload. Desktop sounds and click-to-focus use the originating local terminal; setup, modes and settings.

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)

Add ,gemini, ,qoder, ,cursor or ,pi to --products, or select one agent with --product. Each integration keeps its own desktop/webhook consent. Fresh installs default 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. Use --desktop=false --webhook=false to disable these channels while retaining the integration. Webhook destinations need separate configuration. These flags do not change Claude/Codex channels.

For Pi, use --product pi --desktop or add ,pi to a combined --products selection. Pi has its own desktop/webhook consent and uses the same common installer. Pi setup and event meanings.

Claude/Codex setup also installs the agent-notifications 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 and any selected Cursor integration for that run; it neither removes existing registrations nor records a permanent opt-out. Qoder, OpenCode, Gemini and Pi are unaffected. 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: Claude/Codex/Pi use their existing OS-dependent terminal/editor routes. Qoder/Gemini/Cursor use guarded Linux/X11 window focus only after explicit per-agent consent and verified local origin; per-CLI authenticated click qualification is still outstanding. Other hosts retain informational alerts. Requirements and configuration
• Sounds: Claude/Codex/Pi support their configured audio where qualified; Qoder bundles five MP3s (native audible qualification pending). OpenCode/Gemini/Cursor can request the OS-default cue with notifications.desktop.systemSound=true and the master sound switch. Sound consent never grants window focus. 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 Code	Completions, reviews, questions, plans, session limits and API errors	Yes	Terminal/editor, OS-dependent	Notification types
Codex CLI	Turn completion and tool permissions; experimental question hooks and final-message question/error detection	Yes	Terminal/editor where supported; separately configured Codex desktop chat route	Setup and limits
OpenCode	Root-session completion, questions, permissions and errors	Opt-in OS-default cue	No	Setup and limits
Gemini CLI	Turn completion and tool permissions	Opt-in OS-default cue	Guarded Linux/X11 window, explicit opt-in; CLI-to-click E2E pending	Cross-platform setup and limits
Cursor CLI	Agent loop stopping; fixed informational text	Opt-in OS-default cue	Guarded Linux/X11 window, explicit opt-in; CLI-to-click E2E pending	Qualified hosts and setup
Qoder	Completion, question, permission, plan and subagent hooks; StopFailure errors/rate limits since v1.50.0	Configured; five MP3s bundled, native audible proof pending	Guarded Linux/X11 window, explicit opt-in; no exact-chat focus; CLI-to-click E2E pending	Native hooks and setup
Pi	Final completed activity, blocking extension UI questions and final API errors	Yes, local TUI	Originating local terminal; native qualification varies by OS	Common installation, modes, sound and terminal focus

Detailed support matrix — event coverage, sounds, terminal vs exact-chat navigation, currently unshipped Copilot work, evidence limits and effort estimates.

For Qoder/Gemini/Cursor, guarded focus requires an active managed installation, a schema-2 selected config with agents.<id>.notifications.desktop.clickToFocus: true and terminalClickConsentVersion: 1, and a verified local X11 window. It never follows a guessed title or an old window; a revoked consent or unverified host leaves a normal banner without a focus action. Enable guarded focus.

Pi's process/lifecycle acceptance uses 27 cases per OS on Linux, macOS and Windows in isolated TEST profiles. Those checks do not establish full native macOS/Windows desktop acceptance; remaining coverage is tracked in #561.

OpenCode, Gemini and Cursor's optional OS-default cue (systemSound) is independent of navigation. OpenCode has no click-to-focus route; Gemini/Cursor require separate explicit Linux/X11 terminal-click consent.

OpenCode V1 and V2 use one installed plugin. The installer does not restrict agent CLI versions. See OpenCode setup, release reports and delivery limits for qualification of specific versions and platforms.

Gemini CLI versions are not restricted by the installer. 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.

Pi uses shared configuration with optional schema 2 agents.pi overrides. Its desktop route is local-TUI-only; explicitly enabled webhooks also work in JSON, print, RPC and remote sessions. Pi configuration.

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.