AI Agent Notifications

curl -fsS --max-time 5 -X POST https://app.alphorn.dev/n/V1StGXR8_Z5jdHi6B-myT \
  -H "Authorization: Bearer $ALPHORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Claude Code - my-app", "message": "Needs permission to run tests", "priority": 4, "tags": ["ai-agent", "claude-code", "permission"]}'

export ALPHORN_WEBHOOK_URL="https://app.alphorn.dev/n/V1StGXR8_Z5jdHi6B-myT"
export ALPHORN_API_KEY="alp_..."

## Notifications

Notify the user with Alphorn when a long-running task finishes or fails, or when you
are blocked on a decision and the user may not be watching. Do not notify for routine steps.

```bash
curl -fsS --max-time 5 -X POST "$ALPHORN_WEBHOOK_URL" \
  -H "Authorization: Bearer $ALPHORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg t "<short title>" --arg m "<what happened, what you need>" \
        '{title: $t, message: $m, priority: 3, tags: ["ai-agent"]}')"
```

- priority: 2 = finished, 3 = needs input, 4 = blocked or failed
- Start the title with the project name. Never include secrets in the message.

---
name: alphorn-notify
description: Send the user a notification through Alphorn. Use when the user asks to be notified, pinged, or alerted, when a long-running task finishes or fails, or when you are blocked and the user may be away.
---

# Notify the user with Alphorn

Requires ALPHORN_WEBHOOK_URL and ALPHORN_API_KEY in the environment, plus jq and curl.

```bash
curl -fsS --max-time 5 -X POST "$ALPHORN_WEBHOOK_URL" \
  -H "Authorization: Bearer $ALPHORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg t "$TITLE" --arg m "$MESSAGE" --argjson p 3 \
        '{title: $t, message: $m, priority: $p, tags: ["ai-agent"]}')"
```

- Title: project name plus a few words, e.g. "my-app - tests passing".
- Message: what happened and what you need from the user, in one or two sentences.
- Priority: 2 = finished, 3 = needs input, 4 = blocked or failed.
- A 201 response means the notification was accepted.
- 401: the Authorization header is missing or malformed, or the API key is wrong. Check that ALPHORN_API_KEY is set.
- 400: invalid JSON body. 403: webhook disabled. 404: wrong webhook URL. 413: body too large (over 1 MiB). 429: quota exceeded, don't retry right away. 508: loop detected.
- Never include secrets, tokens, or file contents in the message.

import os
import requests

WEBHOOK = os.environ["ALPHORN_WEBHOOK_URL"]
HEADERS = {"Authorization": "Bearer " + os.environ["ALPHORN_API_KEY"]}

def notify(event, message, priority=3):
    requests.post(WEBHOOK, json={
        "title": f"Agent - {event}",
        "message": message,
        "priority": priority,
        "tags": ["ai-agent", event],
    }, headers=HEADERS, timeout=5)

# When the agent needs human input
notify("waiting", "Agent is blocked and needs your decision")

# When a task completes
notify("completed", f"Finished in {duration}m: {summary}", priority=2)

# When something goes wrong
notify("error", f"{error}", priority=4)

# Cost tracking
notify("cost", f"${cost:.2f} spent of ${budget:.2f} budget",
       priority=4 if cost > budget * 0.8 else 2)