agent-notify

Agent Notify

Desktop notifications for AI coding agents — never miss a completion, approval, or error again.

Quick Start • Features • Why agent-notify? • Compatibility • Usage • Configuration • FAQ

Quick Start

Homebrew (macOS)

Manual install (macOS / Linux / Windows WSL)

Platform recommendations & individual agent setup

Configure agents individually:

Platform-specific packages:

Restart your agent after setup and run a task to verify notifications are working.

macOS click-to-focus requires terminal-notifier (brew install terminal-notifier). For per-window focus (focusing the correct VS Code window, not just VS Code), grant accessibility access to terminal-notifier.app in System Settings → Privacy & Security → Accessibility.

Features

Core

- Multi-agent — Codex CLI, Claude Code, and Gemini CLI out of the box.
- Cross-platform — macOS, Linux, and Windows (WSL / Git Bash).
- Zero dependencies — pure Bash + Python 3 (already on your system).
- One-command setup — agent-notify --setup configures all detected agents.
- Homebrew installable — brew install agent-notify.
- Self-update — agent-notify --update pulls the latest release.

Smart Notifications

- Event categories — completion, approval, question, error, and auth events with distinct sounds.
- Git branch display — shows current branch in notification subtitle.
- Duration display — shows how long the task took.
- Long-run threshold — only notify if the task exceeded N seconds (CODEX_NOTIFY_MIN_DURATION).
- Rich titles/messages extracted from agent JSON payloads.
- Clean, grouped notifications per session/thread.

Terminal Integration

- Click-to-focus — auto-detects your terminal and focuses the right window on click. Supports 10 terminals: VS Code, iTerm2, Ghostty, Warp, kitty,…