Hark

notifications-demo.1.mp4

Hark turns webhooks into clean, source-branded iPhone notifications. Connect CI jobs, agents, scripts, monitoring tools, or anything else that can send an HTTP request.

Website | Documentation

Quick Start

Requires Node.js 22 or newer.

1. Install the Hark skill for your agent:

   npx skills add R44VC0RP/hark --skill hark --global

2. Install the CLI:

   npm install -g harkctl

3. Authenticate it with your Hark account:

   harkctl auth login

4. Ask your agent:

   What can Hark do?
   

Your agent can now notify your iPhone, request approvals or text replies, show task progress with Live Activities, and create webhook services for external systems.

What Hark Does

• Sends rich iOS notifications from a simple webhook.
• Gives each service its own name, avatar, destination URL, and secret endpoint.
• Tracks delivery attempts and registered devices in a web dashboard.
• Supports approvals and text replies for agent workflows.
• Shows stateful task progress with Live Activities on the Lock Screen and Dynamic Island.
• Supports multiple devices and targeted delivery with Hark Pro.

Webhook Setup

1. Sign in at hark.ryan.ceo.
2. Register your iPhone with the Hark app.
3. Create a service and copy its secret webhook URL.
4. Send it a JSON request.

Send a Notification

curl -X POST 'https://hark.ryan.ceo/hooks/whk_your_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "GitHub",
    "body": "Production deployed successfully.",
    "url": "https://github.com/acme/app/actions"
  }'

Only body is required.

Field	Description
body	Notification text.
title	Optional sender-name override.
imageUrl	Optional public HTTPS avatar URL.
url	Optional destination opened when tapped.
deviceIds	Optional Pro routing to specific devices.

Successful requests return an event ID and the number of push requests accepted for delivery:

{
  "ok": true,
  "eventId": "evt_...",
  "delivered": 1
}

Use an Idempotency-Key header when retrying requests to prevent duplicate notifications.

Live Activities

Start a stateful Live Activity using the same service webhook token:

curl -X POST 'https://hark.ryan.ceo/hooks/whk_your_token/live-activities' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Deploy #184",
    "status": "Building",
    "progress": 0.25,
    "symbol": "build",
    "accentColor": "#FF9F0A"
  }'

The response includes an activityId. Use it to update or end the activity:

PATCH /hooks/:token/live-activities/:activityId
POST  /hooks/:token/live-activities/:activityId/end

Updates accept partial state such as status, detail, progress, symbol, and accentColor. Hark allows one active Hark Live Activity per device; pass replace: true on start to silently end whatever occupies the device and take the slot. Starting an activity may alert the user, but progress updates are silent by default. High-priority updates control delivery speed, not sound or haptics.

To contribute a genuinely new Live Activity layout, including no-simulator testing and every public API, widget, CLI, and docs touchpoint, see Contributing a Live Activity template.

Agent Workflows

The harkctl CLI can send one-shot notifications, ask for approvals or short replies, and manage Live Activities from scripts or AI agents.

harkctl auth login
harkctl notify "Deploy finished ✅" --title "Deploy bot"
harkctl notify ask "Deploy production?" --approval --wait
harkctl activity start --title "Release" --status "Building" --progress 0.1

The installable hark agent skill follows the open Agent Skills format used by skills.sh and supports OpenCode, Claude Code, Codex, Cursor, and other compatible agents.

License

Hark is source-available under the PolyForm Noncommercial License 1.0.0. Commercial use is not permitted without a separate license from the licensor.