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.

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.

(set -o pipefail; curl -fsSL https://agent-notifications.com/install.sh | bash -s -- --product codex)

(set -o pipefail; curl -fsSL https://agent-notifications.com/install.sh | bash -s -- --products claude,codex,opencode --desktop)

Manual installation · Manual Codex registration · Uninstall · Troubleshooting

• 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

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.

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

• 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.

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.