Metadata-Version: 2.4
Name: agent-ntfy
Version: 0.1.8
Summary: Cross-platform notification system for AI agents (Claude Code, Gemini CLI) with ntfy.sh support
Project-URL: Homepage, https://github.com/DavidFrazer/agent-notifier
Project-URL: Repository, https://github.com/DavidFrazer/agent-notifier
Project-URL: Documentation, https://github.com/DavidFrazer/agent-notifier#readme
Author: David Frazer <david.frazer336@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai-agent,claude,desktop-notification,gemini,notification,ntfy,push-notification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-ntfy>=0.10.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: release
Requires-Dist: build>=1.0.0; extra == 'release'
Requires-Dist: twine>=8.0.0; extra == 'release'
Description-Content-Type: text/markdown

# Agent Notifier

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

## Supported Agents

| Agent | Config Location | Hook Event |
|-------|---------------|------------|
| Claude Code | `~/.claude/settings.json` | `Notification` |
| Gemini CLI | `~/.gemini/settings.json` | `Notification` |
| OpenCode | `~/.config/opencode/plugins/agent-ntfy.mjs` | Event-based |
| Cursor CLI | `~/.cursor/hooks.json` | `stop` |
| Codex CLI | `~/.codex/config.toml` | `notify` |

## 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

```bash
pip install agent-ntfy
```

## Quick Start

```bash
# 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`:
   ```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](https://docs.ntfy.sh/))

2. **Add server URL to config**:
   ```json
   {
     "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**:
   ```json
   {
     "ntfy_topic": "my-agent-notify",
     "ntfy_server": "https://ntfy.sh",
     "ntfy_token": "tk_your_token_here",
     "ntfy_enabled": true
   }
   ```

### ntfy.sh Configuration Options

```json
{
  "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
}
```

| Option | Default | Description |
|--------|---------|-------------|
| `ntfy_topic` | (required) | Unique topic identifier |
| `ntfy_server` | `https://ntfy.sh` | ntfy server URL |
| `ntfy_token` | none | Access token for private topics |
| `ntfy_priority` | `default` | Priority: `low`, `default`, `high`, `urgent` |
| `ntfy_tags` | `["robot"]` | Tags shown in notifications |
| `ntfy_enabled` | `true` | Enable/disable ntfy notifications |

## Configuration

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

```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:

```bash
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

```bash
# 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

```bash
# 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

```python
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?

```bash
# 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
