Agent Notifications

Notifications for Claude Code and Codex CLI (beta), with sounds, git branch display, and webhook integrations. See Codex support and limitations for differences between products.

Compatibility: the product and repository are now named Agent Notifications / agent-notifications. Existing executable names, Claude plugin commands, installation directories, environment variables, and configuration paths keep their claude-notifications* names during the migration, so current installations continue to update without manual changes.

Boost your productivity — check out the advanced task manager for Claude with a convenient UI, from the creator of this plugin.

Table of Contents

• Features
• Installation
  • Prerequisites
  • Quick Install (Recommended)
  • Manual Install
  • Updating
• Supported Notification Types
• Codex CLI Support (beta)
• Platform Support
  • Click-to-Focus (macOS & Linux)
• Configuration
  • Manual Configuration
  • Sound Options
  • Test Sound Playback
• Manual Testing
• Contributing
• Troubleshooting
• Documentation
• License

Features

• Cross-platform: macOS (Intel & Apple Silicon), Linux (x64 & ARM64), Windows 10+ (x64)
• Claude notification types: Task Complete, Review Complete, Question, Plan Ready, Session Limit, API Error
• Click-to-focus (macOS, Linux): click notification to focus the exact project window and tab — Ghostty, VS Code, iTerm2, Warp, kitty, WezTerm, Alacritty, Hyper, Apple Terminal, GNOME Terminal, Konsole, Tilix, Terminator, XFCE4 Terminal, MATE Terminal
• Multiplexers: tmux (including iTerm2 -CC integration mode), zellij, WezTerm, kitty — click switches to the correct session/pane/tab
• Git branch in title: ✅ Completed main [cat]
• Sounds: MP3/WAV/FLAC/OGG/AIFF, volume control, audio device selection
• Webhooks: Slack, Discord, Telegram, Lark/Feishu, Microsoft Teams, ntfy.sh, PagerDuty, Zapier, n8n, Make, custom — with retry, circuit breaker, rate limiting (docs)
• Plugin compatibility: works with double-shot-latte and other plugins that spawn background Claude instances

Installation

Prerequisites

• Claude Code and/or Codex CLI for the products you select
• Windows users: Git Bash (included with Git for Windows)
• macOS/Linux users: No additional software required

Quick Install (Recommended)

Prefer a guided setup? Open the installation guide to choose your agent, OS and task.

One command to install or update the notifications plugin for Claude Code, Codex, or both. The interactive menu asks you to choose:

curl -fsSL https://raw.githubusercontent.com/777genius/agent-notifications/main/bin/bootstrap.sh | bash

Windows users: open Git Bash from the Start menu and run this command there. Do not run the curl ... | bash command from PowerShell or Windows Terminal if bash opens WSL, because that targets Linux paths and binaries instead of Windows.

For automation or terminals without a controlling TTY, choose explicitly:

curl -fsSL https://raw.githubusercontent.com/777genius/agent-notifications/main/bin/bootstrap.sh | bash -s -- --product codex

Use claude, codex, or both. This installs the notifications plugin; the selected Claude Code / Codex CLI must already be on PATH.

After installation:

• Claude: restart Claude Code. Optionally run /claude-notifications-go:settings to configure sounds.
• Codex: start Codex, run /hooks, then review and trust the installed hooks. The installer registers them automatically; no JSON editing or manual registration command is needed. Trust approval remains yours.
• Both: complete both steps above.

Codex requires a published stable plugin release v1.42.0 or newer. The installer downloads matching source and binaries, respects CODEX_HOME, and keeps a permanent runtime copy there. It reports an error if no supported release is published yet.

If installation fails, use manual Claude installation or manual Codex registration, depending on the product.

Manual Install

Run these slash commands in the Claude Code chat, not in your system terminal:

# 1) Add marketplace
/plugin marketplace add 777genius/agent-notifications
# 2) Install plugin
/plugin install claude-notifications-go@claude-notifications-go
# 3) Restart Claude Code
# 4) Download binary
/claude-notifications-go:init
# 5) (Optional) Configure sounds and settings
/claude-notifications-go:settings

Having issues with installation? See Troubleshooting.

Updating

Run the same command and choose the product(s) you want to update:

curl -fsSL https://raw.githubusercontent.com/777genius/agent-notifications/main/bin/bootstrap.sh | bash

For Claude, restart Claude Code. For Codex, restart Codex and inspect /hooks; changed hook definitions may need trust approval again. The installer refreshes the Codex runtime and registration automatically. Existing foreign hooks and shared settings in ~/.claude/claude-notifications-go/config.json are preserved.

Claude Code also periodically checks for plugin updates automatically. Binaries are updated on the next hook invocation when a version mismatch is detected.

To update manually via Claude Code UI:

1. Run /plugin, select Marketplaces, choose claude-notifications-go, then select Update marketplace
2. Select Installed, choose claude-notifications-go, then select Update now

If the binary auto-update didn't work (e.g. no internet at the time), run /claude-notifications-go:init to download it manually. If hook definitions changed in the new version, restart Claude Code to apply them.

Supported Notification Types

The Claude triggers are listed below. Codex uses a different event mapping, described in Codex support.

Codex CLI Support (beta)

The same binary can notify for OpenAI Codex CLI sessions.

Setup

Use the one-command installer and choose Codex or both.
It downloads matching release source and binaries, registers the hooks, and keeps a stable
runtime copy. Then start Codex and approve the entries in /hooks.

Manual Codex registration

Skip this section if you used the one-command installer. For manual setup, download a
matching release bundle and binary (v1.42.0 or newer). The Go registration command needs
no jq and is not automatically added to your PATH.

From the bundle directory:

./bin/claude-notifications setup-codex --plugin-root .

On Windows, run the downloaded claude-notifications-windows-amd64.exe in PowerShell:

.\bin\claude-notifications-windows-amd64.exe setup-codex --plugin-root .

Run these commands in the bundle directory. If you have explicitly added the binary to
PATH, claude-notifications setup-codex --plugin-root <bundle-directory> also works.

It installs a self-contained copy of the plugin at ~/.codex/claude-notifications-go and writes
the hook entries into ~/.codex/hooks.json. Existing foreign hook definitions and unknown fields are preserved,
and every run saves a uniquely named backup of the previous file next to it.

Then start Codex, run /hooks, review the entries and trust them.

Useful flags: --dry-run shows what would change, --print outputs the JSON so you can merge it
yourself, --codex-home and --plugin-root override the paths.

For manual updates, run the registration command again to refresh the installed copy.
Unchanged hook definitions retain trust; changed definitions require review again.
The one-command installer handles this registration step automatically.

Claude Code installation and updates continue to use the existing installation steps.
Both products share settings at ~/.claude/claude-notifications-go/config.json; installing
Codex does not require installing Claude Code. Keep your existing settings file when updating.

setup-codex registers user hooks explicitly, using a stable runtime directory independent
of the plugin cache. This is the setup path covered by this project's installer tests.
The bundle also includes a Codex plugin manifest. Codex versions can differ in plugin-hook
loading; follow the current Codex hooks documentation
for native plugin setup. Use one registration path to avoid duplicate hooks, and inspect
/hooks after installation.

Codex includes the command string in its trust hash, so the registration deliberately points at
the stable ~/.codex/claude-notifications-go copy rather than a versioned plugin cache
directory — that is what keeps the trust valid across updates.

What works today:

• Stop - a turn finishes; the status comes from the final assistant message: short failure
  reports map to the API Error / Session Limit statuses, a trailing question mark maps to
  Question, otherwise Task Complete. The Codex rollout transcript is not parsed (it is an
  internal, unstable format).
• Question payloads (experimental) - if Codex emits PreToolUse for request_user_input,
  the plugin delivers the question/header text. Options, ids, and secret fields are excluded.
  Live firing of this tool hook is not yet qualified; do not rely on it for every question.
• PermissionRequest - Codex is waiting for your approval of a tool call; delivered as the
  time-sensitive Permission Request status. Only the tool name is shown, never the tool input.
• SubagentStop (opt-in) - with notifyOnSubagentStop: true and suppressForSubagents: false,
  subagent completions notify with the subagent's final message.

Known limitations:

• PermissionRequest cannot fire when Codex never asks for approval (bypassPermissions,
  --ask-for-approval never, headless codex exec).
• The error statuses for Codex come from a text heuristic over the final message (short messages
  with failure phrasing), not from structured error data - false negatives are possible.
• The request_user_input question hook is limited to the modes where Codex exposes that tool.
• Windows support for the Codex route is not declared until the Windows launcher is proven.
• Codex hooks require a trust review (/hooks inside Codex); changed definitions require review again.

Both products share one config file (~/.claude/claude-notifications-go/config.json).

Platform Support

Supported platforms:

• macOS (Intel & Apple Silicon)
• Linux (x64 & ARM64)
• Windows 10+ (x64)

No additional dependencies:

• ✅ Binaries auto-download from GitHub Releases
• ✅ Pure Go - no C compiler needed
• ✅ All libraries bundled
• ✅ Works offline after first setup

Windows-specific features:

• Native Toast notifications (Windows 10+)
• After installation, notifications work in PowerShell, CMD, Git Bash, or WSL
• MP3/WAV/OGG/FLAC audio playback via native Windows APIs
• System sounds not accessible - use built-in MP3s or custom files

Click-to-Focus (macOS & Linux)

Clicking a notification activates your terminal window. Auto-detects terminal and platform.

macOS — via AX API with bundle ID detection:

Linux — via D-Bus daemon with automatic compositor detection:

Linux focus methods (tried in order): GNOME extension, GNOME Shell Eval, GNOME FocusApp, wlrctl (Sway/wlroots), kdotool (KDE), xdotool (X11).

Multiplexers (both platforms): tmux (including iTerm2 -CC integration mode), zellij, WezTerm, kitty — click switches to the correct pane/tab.

iTerm2 note: to open the exact iTerm2 tab or split pane, enable iTerm2 > Settings > General > Magic > Enable Python API. If you just toggled it, restart iTerm2 once. Without the Python API, the plugin falls back to app-level iTerm activation instead of exact tab targeting.

Windows — clicking a notification raises the originating terminal window (Windows Terminal, VS Code, conhost, …) via a protocol-activated toast. Window-level only: tab/split-pane targeting isn't possible (one window hosts all tabs), and picking among multiple WT windows in one process is best-effort. See the guide for details.

See Click-to-Focus Guide for configuration details.

Configuration

Run /claude-notifications-go:settings to configure sounds, volume, webhooks, and other options via an interactive wizard. You can re-run it anytime to reconfigure.

Manual Configuration

Config file location:

Edit the config file directly:

{
  "notifications": {
    "desktop": {
      "enabled": true,
      "sound": true,
      "volume": 1.0,
      "audioDevice": "",
      "clickToFocus": true,
      "terminalBundleId": "",
      "showSessionLabel": true,
      "appIcon": "${CLAUDE_PLUGIN_ROOT}/claude_icon.png"
    },
    "webhook": {
      "enabled": false,
      "preset": "slack",
      "url": "",
      "chat_id": "",
      "format": "json",
      "headers": {},
      "payloadFields": {}
    },
    "suppressQuestionAfterTaskCompleteSeconds": 12,
    "suppressQuestionAfterAnyNotificationSeconds": 7,
    "notifyOnSubagentStop": false,
    "suppressForSubagents": true,
    "notifyOnTextResponse": true,
    "respectJudgeMode": true,
    "notifyOnlyWhenUnfocused": false,
    "notifyDelaySeconds": 0,
    "suppressFilters": [
      {
        "name": "Suppress ClaudeProbe completions (remote-control)",
        "status": "task_complete",
        "gitBranch": "",
        "folder": "ClaudeProbe"
      }
    ]
  },
  "statuses": {
    "task_complete": {
      "title": "✅ Completed",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/task-complete.mp3"
    },
    "review_complete": {
      "title": "🔍 Review",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/review-complete.mp3"
    },
    "question": {
      "title": "❓ Question",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/question.mp3"
    },
    "plan_ready": {
      "title": "📋 Plan",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/plan-ready.mp3"
    },
    "session_limit_reached": {
      "title": "⏱️ Session Limit Reached",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/error.mp3"
    },
    "api_error": {
      "title": "🔴 API Error: 401",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/error.mp3"
    },
    "api_error_overloaded": {
      "title": "🔴 API Error",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/error.mp3"
    }
  }
}

Each status can be individually disabled by adding "enabled": false.

You can also override individual channels per status:

{
  "statuses": {
    "question": {
      "title": "❓ Question",
      "sound": "${CLAUDE_PLUGIN_ROOT}/sounds/question.mp3",
      "desktop": { "enabled": true },
      "webhook": { "enabled": false }
    }
  }
}

statuses.<name>.enabled is still the master switch for both channels. Use
desktop.enabled and webhook.enabled when you want one channel on and the
other off for the same status.

Focus-Aware & Delayed Notifications

Two independent options cut notification noise when you're already watching the terminal:

• notifyOnlyWhenUnfocused - skip the desktop notification only when the focused terminal window can be matched to the current Claude Code session.
• notifyDelaySeconds - wait N seconds before delivering, so a quick task can finish before any banner appears (capped at 25s to stay within the hook timeout).

They compose: with both set, the plugin waits, then notifies only if the terminal still isn't focused - "tell me once I've looked away."

{
  "notifications": {
    "notifyOnlyWhenUnfocused": true,
    "notifyDelaySeconds": 10
  }
}

Both apply to desktop notifications only - webhook delivery is never delayed or suppressed. Focus detection is best-effort and degrades safely by notifying when unsure:

• macOS: Ghostty can be matched by exact terminal/session metadata; other terminal apps require the frontmost window title to match the project folder and existing Screen Recording access.
• Linux: X11 sessions compare $WINDOWID to the active window. Wayland or terminals without $WINDOWID are treated as unknown.
• Windows: the foreground window must belong to the hook process ancestry and its title must contain the project folder. Ambiguous multi-window or multi-tab terminal hosts are treated as unknown.

Unknown means "show the notification", not "suppress it".

Sound Options

Built-in sounds (included):

• ${CLAUDE_PLUGIN_ROOT}/sounds/task-complete.mp3
• ${CLAUDE_PLUGIN_ROOT}/sounds/review-complete.mp3
• ${CLAUDE_PLUGIN_ROOT}/sounds/question.mp3
• ${CLAUDE_PLUGIN_ROOT}/sounds/plan-ready.mp3
• ${CLAUDE_PLUGIN_ROOT}/sounds/error.mp3

System sounds:

• macOS: /System/Library/Sounds/Glass.aiff, /System/Library/Sounds/Hero.aiff, etc.
• Linux: /usr/share/sounds/**/*.ogg (varies by distribution)
• Windows: Use built-in MP3s (system sounds not easily accessible)

Supported formats: MP3, WAV, FLAC, OGG/Vorbis, AIFF

List Available Sounds

See all available notification sounds on your system:

# List all sounds (built-in + system)
bin/list-sounds

# Output as JSON
bin/list-sounds --json

# Preview a sound
bin/list-sounds --play task-complete

# Preview at specific volume
bin/list-sounds --play Glass --volume 0.5

Or use the skill command: /claude-notifications-go:sounds

Audio Device Selection

Route notification sounds to a specific audio output device instead of the system default:

# List available audio devices
bin/list-devices

# Output:
#   0: MacBook Pro-Lautsprecher
#   1: Babyface (23314790) (default)
#   2: Immersed

Then add the device name to your ~/.claude/claude-notifications-go/config.json:

{
  "notifications": {
    "desktop": {
      "audioDevice": "MacBook Pro-Lautsprecher"
    }
  }
}

Leave audioDevice empty or omit it to use the system default device.

Test Sound Playback

Preview any sound file with optional volume control:

# Test built-in sound (full volume)
bin/sound-preview sounds/task-complete.mp3

# Test with reduced volume (30% - recommended for testing)
bin/sound-preview --volume 0.3 sounds/task-complete.mp3

# Test macOS system sound at 30% volume
bin/sound-preview --volume 0.3 /System/Library/Sounds/Glass.aiff

# Test custom sound at 50% volume
bin/sound-preview --volume 0.5 /path/to/your/sound.wav

# Show all options
bin/sound-preview --help

Volume flag: Use --volume to control playback volume (0.0 to 1.0). Default is 1.0 (full volume).

Manual Testing

The plugin is invoked automatically by Claude Code hooks. To test manually:

# Test PreToolUse hook
echo '{"session_id":"test","transcript_path":"/path/to/transcript.jsonl","tool_name":"ExitPlanMode"}' | \
  claude-notifications handle-hook PreToolUse

# Test Stop hook
echo '{"session_id":"test","transcript_path":"/path/to/transcript.jsonl"}' | \
  claude-notifications handle-hook Stop

Contributing

See CONTRIBUTING.md for development setup, testing, building, and submitting changes.
For local plugin workflows and real-claude smoke/manual E2E testing, see docs/LOCAL_DEVELOPMENT.md.

Troubleshooting

See Troubleshooting Guide for common issues:

• Ubuntu 24.04: EXDEV: cross-device link not permitted during /plugin install (TMPDIR workaround)
• Windows: install issues related to %TEMP% / %TMP% location
• Windows / Git Bash: GitHub Releases download fails because of proxy / TLS inspection / certificate revocation

Documentation

• Architecture - Plugin architecture, directory structure, data flow

• Local Development And E2E - Local marketplace testing, real Claude smoke tests, manual click-to-focus validation

• Click-to-Focus - Configuration, supported terminals, platform details

• Volume Control Guide - Customize notification volume

  • Configure volume from 0% to 100%
  • Logarithmic scaling for natural sound
  • Per-environment recommendations

• Interactive Sound Preview - Preview sounds during setup

  • Interactive sound selection
  • Preview before choosing

• Plugin Compatibility - Integration with other Claude Code plugins

• Troubleshooting - Common install/runtime issues

  • Ubuntu 24.04 EXDEV during /plugin install (TMPDIR workaround)

• Webhook Integration Guide - Complete guide for webhook setup

  • Slack - Slack integration with color-coded attachments
  • Discord - Discord integration with rich embeds
  • Telegram - Telegram bot integration
  • Lark/Feishu - Lark/Feishu integration with interactive cards
  • Custom Webhooks - Any webhook-compatible service
  • Configuration - Retry, circuit breaker, rate limiting
  • Monitoring - Metrics and debugging
  • Troubleshooting - Common issues and solutions

License

GPL-3.0 - See LICENSE file for details.