claude-notifications-go

Smart notifications for Claude Code with click-to-focus, git branch display, and webhook integrations.

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
• 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)
• 6 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
• Windows users: Git Bash (included with Git for Windows)
• macOS/Linux users: No additional software required

Quick Install (Recommended)

One command to install everything:

curl -fsSL https://raw.githubusercontent.com/777genius/claude-notifications-go/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.

Then restart Claude Code and optionally run /claude-notifications-go:settings to configure sounds.

The binary is downloaded once and cached locally. You can re-run /claude-notifications-go:settings anytime to reconfigure.

If the bootstrap script doesn't work for your environment, use the Manual Install steps below inside Claude Code.

Manual Install

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

# 1) Add marketplace
/plugin marketplace add 777genius/claude-notifications-go
# 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 as for installation — it will update both the plugin and the binary:

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

Then restart Claude Code to apply the new version. Your settings in ~/.claude/claude-notifications-go/config.json are preserved across updates.

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

Codex CLI Support (beta)

The same binary can notify for OpenAI Codex CLI sessions.

Setup

The registration command is implemented in Go and does not require jq. You need a Codex-capable release (v1.42.0 or later) and its plugin bundle; an older binary cannot run setup-codex. The command is not automatically added to your PATH by the Claude plugin.

For a Codex-only installation, download a bundle and its platform binary first. In a terminal with Git and Bash (Git Bash on Windows), run:

git clone --depth 1 https://github.com/777genius/claude-notifications-go.git
cd claude-notifications-go
CN_PRODUCT=codex bash bin/install.sh

This downloads the notification binary; it does not install Claude Code. Keep this source directory for updates. The Codex registration below installs a separate stable runtime copy.

From an already downloaded plugin bundle, run the binary by its path:

./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 — Codex asks once.

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.

After updating the plugin, run the command again to refresh the installed copy. The registration itself does not change, so Codex does not ask you to trust the hooks again. For the Git checkout above, update with git pull --ff-only, run CN_PRODUCT=codex bash bin/install.sh --force, then repeat the appropriate setup-codex command. Existing Claude plugin users can update their source bundle using the usual Claude plugin update process before repeating setup.

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.