README
¶
Agent Notifications
 |
Desktop notifications and sounds for Claude Code and Codex CLI. Know when a task finishes, an agent needs input, or a tool needs approval. Click a notification to return to work.
Features
- Task and attention alerts: completions, reviews, questions, plans, session limits and API errors for Claude; completions and permission requests for Codex, with opt-in subagent alerts. Event details
- Click-to-focus: return to the originating terminal or editor, with exact tab/pane targeting for supported integrations including Ghostty, iTerm2, Warp, tmux, kitty and WezTerm. Supported terminals
- Useful context: project, git branch and session labels in notifications.
- Custom sounds: built-in or custom MP3, WAV, FLAC, OGG and AIFF, with volume control, previews and audio output selection.
- Less noise: focus-aware delivery, optional delay, duplicate-question suppression and filters by status, branch or folder.
- Your settings per agent: shared configuration with separate Claude and Codex overrides; control desktop and webhook delivery per status. Agent settings
- Webhooks: Slack, Discord, Telegram, Lark/Feishu and custom endpoints, including Teams, ntfy, PagerDuty, Zapier, n8n and Make. Retries, rate limits and circuit breakers are built in. Integrations
- Cross-platform: macOS (Intel/Apple Silicon), Linux (x64/ARM64) and Windows 10+ (x64). Platform details
Codex setup and event behavior
Install Or Update
Requires Claude Code and/or Codex CLI, plus Python 3.6+ (python3) or Node.js (node) for the installer. Python is used when both are present. On Windows, use Git Bash with native Windows Python or Node. A Microsoft Store or WSL python3 stub is skipped when Node is available.
(set -o pipefail; curl -fsSL https://raw.githubusercontent.com/777genius/agent-notifications/a512deb5819c3f8c7c3be8335f713cc8bb734fc3/bin/setup.sh | bash)
The command uses a commit-pinned setup loader and reports download failures. The small setup script resolves the latest stable release and downloads both installer scripts from its exact commit. Release lookup and validation happen automatically. Choose Claude, Codex, or both. For non-interactive setup, append -s -- --product claude, codex, or both after bash, before the closing ).
- Claude: restart Claude Code.
- Codex: restart Codex, open
/hooks, then review and trust the installed hooks.
Run the same command to update. Guided installer · Manual installation, updates and removal
Settings
In Claude Code, run /claude-notifications-go:settings for the configuration wizard or /claude-notifications-go:sounds to browse and preview sounds.
The primary CLI is agent-notifications. Use agent-notifications config path to locate your settings and agent-notifications config inspect --json to inspect them safely. The claude-notifications alias and Claude slash-command namespace remain compatible with existing installations.
Configuration reference · Per-agent overrides · Sound previews
Documentation
GPL-3.0-or-later. See LICENSE.
Human pull requests must be signed under the Contributor License Agreement before merge. You keep copyright. Until you sign, GitHub's Terms of Service license the pull request under GPL-3.0-or-later only. The CLA lets the project owner sublicense signed work under additional terms (for example a commercial license) while keeping the GPL-3.0-or-later grant from the submission date.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
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. |
|
internal
|
|
|
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. |
|
daemon
ABOUTME: Client library for communicating with the notification daemon.
|
ABOUTME: Client library for communicating with the notification daemon. |
|
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. |
|
testenv
Package testenv provides a complete disposable environment for filesystem tests.
|
Package testenv provides a complete disposable environment for filesystem tests. |
|
warpfocus
ABOUTME: Warp session deep-link capture for click-to-focus.
|
ABOUTME: Warp session deep-link capture for click-to-focus. |
|
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
|
|