Developers

Put anything live at the top of your Mac.

The notchpulse CLI and the local Live Activity API let scripts, CI jobs, git hooks and AI agents create activities that look and behave like built-in ones.

Coming in v1 Free The CLI ships inside the app and is part of NotchPulse Free. Commands below reflect the current development build and may still change before 1.0.

The CLI

Notify once, or create an activity and drive it to completion. Exit codes are script-friendly, and the CLI never slows down the tool that calls it.

notchpulse exit codes
Exit code	Meaning
`0`	OK
`1`	API error
`2`	Usage error
`3`	NotchPulse is not running

zsh

$ notchpulse notify "Tests passed"
$ id=$(notchpulse activity create --title "Deploying production" --progress 0.35 --type deployment)
$ notchpulse activity update "$id" --progress 0.8
$ notchpulse activity complete "$id"        # plays the deployment rocket
$ notchpulse activity fail "$id" --subtitle "Migration 0042 failed"
$ notchpulse react celebration
$ notchpulse run --title "Running tests" -- swift test   # completes/fails on exit status

Install the command

The CLI lives inside the app bundle. Link it onto your PATH once:

zsh

$ sudo ln -sf /Applications/NotchPulse.app/Contents/Helpers/notchpulse /usr/local/bin/notchpulse

Claude Code hooks

Add this to .claude/settings.json so Claude’s requests for input and its completions show up in the notch. Hooks run locally; NotchPulse receives only the fixed titles below — never your prompts, code or transcript.

.claude/settings.json

{
  "hooks": {
    "Notification": [{ "hooks": [{ "type": "command",
      "command": "notchpulse notify 'Claude needs your input' --source claudeCode --priority important" }] }],
    "Stop": [{ "hooks": [{ "type": "command",
      "command": "notchpulse notify 'Claude finished' --source claudeCode" }] }]
  }
}

A dedicated notchpulse hooks install claude command with session-aware activities is planned for v1. See the Claude Code integration.

The local API

Under the CLI is a small, versioned protocol: newline-delimited JSON over a Unix domain socket. Anything that can open a socket can use it.

NDJSON · IPC v1

# one JSON object per line over ~/Library/Application Support/NotchPulse/notchpulse.sock
{ "v": 1, "id": "req-1", "method": "activity.create",
  "params": { "title": "Deploying production", "type": "deployment", "progress": 0.35 } }

{ "v": 1, "id": "req-1", "ok": true, "result": { "id": "6f1c…" } }

IPC v1 methods
Method	What it does
`ping`	Returns the API version.
`activity.create`	Creates an activity. Supplying your own `id` makes it idempotent.
`activity.update`	Updates title, subtitle, state, progress or priority.
`activity.complete` · `activity.fail`	Finishes an activity; the right reaction plays.
`activity.dismiss` · `activity.list`	Removes one activity; lists current activities.
`notify`	A one-off notice with optional priority and source.
`react`	`celebration`, `success`, `failure`, `rocket`, `coins` or `merge`.

Activity fields include title (up to 120 characters), subtitle, source, type, state, progress (0–1), priority, expires_in, a primary action url, workspace and privacy.

Security by construction

The socket directory is private to your user (0700) and the socket is 0600. Connections from other user IDs are rejected.
Messages are capped at 64 KiB, connections at 16, and each connection is rate-limited.
Strings are length-limited and stripped of control characters. Action links must be https: or they’re dropped.
Activities sent through the API are labeled as coming via the CLI, so a script can’t pass itself off as a verified integration.
The optional HTTP API binds to 127.0.0.1 only, needs a bearer token from your Keychain, rejects browser-originated requests and is off by default.

Coming later

Shortcuts actions and triggers, plus thin Swift, JavaScript/TypeScript and Python SDKs, are on the roadmap Roadmap. A plugin system will come only once the Activity model and API have proven stable in real use.

Build your own live activities.

The CLI and local Live Activity API are free — included in NotchPulse Free, forever.

Get NotchPulse Explore features