agent-ntfy

Agent Notifier

Cross-platform notification system for AI coding agents with ntfy.sh push notification support.

Supported Agents

Features

• Terminal Notifications: OSC 9 protocol for Ghostty, iTerm2, Kitty, VSCode, Windows Terminal
• OS-Native Notifications: BurntToast (Windows), osascript (macOS), notify-send (Linux)
• ntfy.sh Push Notifications: Get notifications on your phone, desktop, or any device
• Multiple Channels: All channels attempted in parallel for maximum reach
• Self-Contained: No external plugin dependencies required

Installation

pip install agent-ntfy

Quick Start

# 1. Initialize configuration
agent-ntfy-setup --init

# 2. Edit config to add your ntfy.sh topic (see ntfy.sh Setup below)
notepad $env:USERPROFILE\.agent-ntfy\config.json

# 3. Install hooks for your agents
agent-ntfy-setup --all

ntfy.sh Setup

ntfy.sh is a free, open-source notification service. You can use the public server or self-host.

Option 1: Public ntfy.sh (Quickest)

1. Choose a topic name - Any unique string like my-agent-notify or maravedi-dev
2. Add to config - Edit ~/.agent-ntfy/config.json:

   {
     "ntfy_topic": "my-agent-notify",
     "ntfy_enabled": true
   }
   

3. Subscribe on your devices:
   • iOS/Android: Install the ntfy app, tap "Subscribe", enter your topic name
   • Desktop: Open https://ntfy.sh/my-agent-notify in your browser
   • CLI: curl -s ntfy.sh/my-agent-notify/json | jq

Option 2: Self-Hosted ntfy Server

1. Run your own ntfy server (see ntfy.sh docs)

2. Add server URL to config:

   {
     "ntfy_topic": "my-agent-notify",
     "ntfy_server": "https://ntfy.example.com",
     "ntfy_enabled": true
   }
   

Option 3: Private Topic with Access Token

1. Create a topic at ntfy.sh or your self-hosted server
2. Generate an access token in the topic settings
3. Add to config:

   {
     "ntfy_topic": "my-agent-notify",
     "ntfy_server": "https://ntfy.sh",
     "ntfy_token": "tk_your_token_here",
     "ntfy_enabled": true
   }
   

ntfy.sh Configuration Options

{
  "ntfy_topic": "your-unique-topic-name",
  "ntfy_server": "https://ntfy.sh",
  "ntfy_token": "tk_optional_access_token",
  "ntfy_priority": "default",
  "ntfy_tags": ["robot", "notification"],
  "ntfy_enabled": true
}

Configuration

Configuration file: ~/.agent-ntfy/config.json

{
  "ntfy_topic": "your-topic-name",
  "ntfy_server": "https://ntfy.sh",
  "ntfy_enabled": true,
  "terminal_enabled": true,
  "os_native_enabled": true,
  "log_level": "INFO"
}

Environment Variables

Override any config setting:

export AGENT_NOTIFY_NTFY_TOPIC=my-topic
export AGENT_NOTIFY_NTFY_SERVER=https://ntfy.sh
export AGENT_NOTIFY_NTFY_ENABLED=true
export AGENT_NOTIFY_TERMINAL_ENABLED=true
export AGENT_NOTIFY_OS_NATIVE_ENABLED=true

CLI Commands

agent-notify

# Send a notification
agent-notify --title "Claude Code" --message "Task complete!"

# Send via stdin (JSON)
echo '{"title":"Alert","message":"Error occurred"}' | agent-notify

# Disable specific channels
agent-notify --title "Silent" --message "No sound" --no-ntfy

# Test your setup
agent-notify --title "Test" --message "agent-notifier is working!"

agent-ntfy-setup

# Initialize config (creates ~/.agent-ntfy/config.json)
agent-ntfy-setup --init

# Install all agent hooks
agent-ntfy-setup --all

# Install specific agents
agent-ntfy-setup --install-claude    # Claude Code
agent-ntfy-setup --install-gemini     # Gemini CLI
agent-ntfy-setup --install-opencode  # OpenCode
agent-ntfy-setup --install-cursor    # Cursor CLI
agent-ntfy-setup --install-codex     # Codex CLI

# Check prerequisites
agent-ntfy-setup --check

# Uninstall all hooks
agent-ntfy-setup --uninstall

Programmatic API

from agent_notifier import notify

# Simple notification
notify(title="Claude Code", message="Task complete!")

# Custom topic
notify(title="Alert", message="Error!", ntfy_topic="my-custom-topic")

# Self-hosted server
notify(title="Alert", message="Error!", ntfy_topic="my-topic", ntfy_server="https://ntfy.example.com")

Agent-Specific Notes

Claude Code

Uses Notification hook in ~/.claude/settings.json. Notifies when the agent needs user input or completes work.

Gemini CLI

Uses Notification hook in ~/.gemini/settings.json. Notifies on tool permission requests.

OpenCode

Uses a local plugin at ~/.config/opencode/plugins/agent-ntfy.mjs. Handles: session.idle, session.error, permission.asked, subagent.complete

Cursor CLI

Uses stop hook in ~/.cursor/hooks.json. Notifies when a task completes.

Codex CLI

Uses notify command in ~/.codex/config.toml. Notifies on agent-turn-complete and approval-requested events.

Architecture

┌─────────────────────────────────────────────────────────┐
│              AI Agent (any supported)                  │
└─────────────────────────┬───────────────────────────────┘
                          │ Hook/Event
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   agent-notify                          │
│  (CLI entry point for all notifications)                │
└──────────┬──────────────────────┬──────────────────────┘
           │                      │
           ▼                      ▼
┌──────────────────┐    ┌─────────────────────────────┐
│ Terminal (OSC 9) │    │   ntfy.sh Push              │
│ Supported:        │    │   ┌─────────────────────┐   │
│ • Ghostty        │    │   │ Your Devices        │   │
│ • iTerm2         │    │   │ • Phone (app)       │   │
│ • Kitty          │    │   │ • Browser           │   │
│ • VSCode         │    │   │ • CLI (curl)        │   │
│ • Windows Terminal│   │   └─────────────────────┘   │
└──────────────────┘    └─────────────────────────────┘
           │
           ▼
┌──────────────────┐
│ OS Native        │
│ • Windows: BurntToast
│ • macOS: osascript
│ • Linux: notify-send
└──────────────────┘

Requirements

• Python 3.11+
• python-ntfy (installed automatically)
• For OS notifications:
  • Windows: BurntToast PowerShell module (Install-Module BurntToast)
  • macOS: Built-in osascript
  • Linux: notify-send (apt install libnotify-bin)

Troubleshooting

Notifications not working?

# Check prerequisites
agent-ntfy-setup --check

# Test manually
agent-notify --title "Test" --message "Hello!"

# Enable verbose logging
agent-notify --title "Test" --message "Debug" --verbose

# Check log file
cat ~/.agent-ntfy/notifier.log

ntfy not receiving notifications?

1. Verify your topic name is correct in config
2. Make sure your topic isn't rate-limited (try a different name)
3. For private topics, verify your access token

License

MIT