ai-agent-notifier

Desktop & phone notifications for AI coding agents
One tool. One config. Every agent. Never miss when your AI finishes or needs input.

           

---

Quick Start

npx ai-agent-notifier setup

That's it. The setup wizard detects your platform and installed AI tools, wires the hooks, and optionally configures phone push notifications. Restart your AI tools to activate.

Features

• Desktop toast notifications -- Windows (BurntToast), macOS (Notification Center), Linux (libnotify)
• Phone push notifications -- Android & iOS via ntfy (free, no account required)
• Click-to-focus -- click the toast to jump back to the terminal or VS Code window (Windows)
• Per-tool branded icons -- each tool gets its own logo in the notification
• One unified config -- shared ~/.ai-agent-notifier/config.json across all tools
• Atomic deduplication -- prevents double notifications (e.g. Cursor's duplicate hook fires)
• Zero dependencies -- pure Node.js built-ins only, no npm production packages

Supported Tools

Tool	VS Code	CLI	Task Complete	Needs Input
Claude Code	Native	Native	Stop	Notification
Codex CLI	Native	Native	Stop	PermissionRequest
Cursor	Native	--	stop	--
Gemini CLI	--	Native	AfterAgent	Notification

All four tools are wired automatically by the setup wizard. No manual config editing needed.

VS Code Native Support

Claude Code, Codex, and Cursor all run inside VS Code. ai-agent-notifier hooks directly into each tool's native hook system -- no VS Code extension required. The setup wizard detects installed tools and patches their configs automatically. Click a notification toast to jump straight back to your VS Code window.

Installation

npm (recommended)

# One-shot setup (no install needed)
npx ai-agent-notifier setup

# Or install globally
npm i -g ai-agent-notifier
ai-agent-notifier setup

Claude Code Plugin

/install-plugin https://github.com/DevinoSolutions/ai-agent-notifier

Hooks auto-register. Use /ai-agent-notifier:setup to wire other tools.

Standalone (no npm)

Windows (PowerShell):

irm https://raw.githubusercontent.com/DevinoSolutions/ai-agent-notifier/main/setup/install.ps1 | iex

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/DevinoSolutions/ai-agent-notifier/main/setup/install.sh | bash

CLI Commands

ai-agent-notifier setup          # First-time setup wizard
ai-agent-notifier status         # Show wired tools, config, backends
ai-agent-notifier test [channel] # Fire test notification (toast | ntfy | both)
ai-agent-notifier config         # Interactive settings menu
ai-agent-notifier uninstall      # Remove hooks from all tools

Configuration

Config lives at ~/.ai-agent-notifier/config.json:

{
  "ntfy": {
    "enabled": true,
    "server": "https://ntfy.sh",
    "topic": "ai-agent-notifier-<random>"
  },
  "toast": {
    "enabled": true,
    "clickToFocus": true
  },
  "events": {
    "task_complete": { "sound": "IM", "ntfyPriority": "default" },
    "needs_input": { "sound": "Reminder", "ntfyPriority": "urgent" },
    "session_start": { "sound": "Default", "ntfyPriority": "low" }
  }
}

ntfy -- Phone Push Notifications

ntfy sends free push notifications to your phone -- no account needed.

1. Install the ntfy app (Android / iOS)
2. Subscribe to your topic (shown during setup)
3. All your AI tools' notifications appear in one stream

Per-Event Settings

Event	Default Sound	ntfy Priority	Description
task_complete	IM	default	Agent finished its task
needs_input	Reminder	urgent	Agent needs your input or permission
session_start	Default	low	New session started (disabled by default)

How It Works

Each AI tool's hook system pipes event data to notify.mjs:

Hook fires (stdin JSON + --source flag)
  -> parse-input.mjs   (normalize across tools)
  -> router.mjs        (map event to notification type)
  -> platform toast    (Windows / macOS / Linux)
  -> ntfy push         (phone notification)

Platform Details

Windows

• BurntToast PowerShell module for rich toast notifications
• Click-to-focus via custom agentfocus:// URI protocol
• BurntToast auto-installed during setup if missing
• Requires PowerShell 7+ (pwsh)

macOS

• Uses built-in osascript -- zero additional dependencies
• Falls back to terminal-notifier for richer features if available

Linux

• Uses notify-send (libnotify) -- available on most desktop distributions
• Fails silently on headless or WSL systems without a GUI

Requirements

Requirement	Details
Node.js	>= 18.0.0 (already present for all supported AI tools)
Windows	PowerShell 7+ (pwsh)
macOS	osascript (built-in)
Linux	notify-send (optional, for desktop toasts)

Uninstall

ai-agent-notifier uninstall

Removes all managed hooks from every tool's config. Original configs are backed up at ~/.ai-agent-notifier/backups/.

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

License

AGPL-3.0 -- Copyright (c) 2026 DevinoSolutions