notification-service

A tiny macOS service that listens on http://127.0.0.1:11270 and pops up a centered modal window in response to an HTTP POST. Pure Swift + AppKit, no third-party dependencies.

Build

swift build -c release      # or: just build

Quick test

With the service running (just install or just run):

just test                                   # pop a default notification
just show "Deploy done" "Build #42 passed"  # pop a custom one

Run (foreground)

.build/release/NotificationService run      # or: just run

Install as a login item

Installs a per-user LaunchAgent so the service starts at login and stays alive:

.build/release/NotificationService install   # or: just install

• Binary → ~/Library/Application Support/NotificationService/notification-service
• LaunchAgent → ~/Library/LaunchAgents/com.hattergit.notification-service.plist
• Logs → /tmp/notification-service.log, /tmp/notification-service.err

Remove it with:

.build/release/NotificationService uninstall   # or: just uninstall

API

POST /api/v1/show

Pops up a modal window centered on the active screen.

curl -X POST http://127.0.0.1:11270/api/v1/show \
  -H 'Content-Type: application/json' \
  -d '{"title":"Hello","content":"World"}'

• title — window title (defaults to "Notification" if empty/omitted)
• content — body text (defaults to empty)

Response:

{"status":"queued"}

The window is queued and shown immediately; if a window is already on screen, the new one is shown as soon as the current one is dismissed. Each window has:

• Dismiss — close it.
• Remind Me — snooze: re-show the same title/content after a delay you pick (default 5 minutes, range 1–120 via the field/stepper). Snoozed reminders are persisted to ~/Library/Application Support/NotificationService/snoozed.json and survive a service restart; anything already overdue is shown immediately on next launch.

Other paths/methods return 404 / 405; invalid JSON returns 400.

Notes

• Bound only to the loopback interface — not reachable from the network.
• Runs as a background (accessory) app: no Dock icon, no menu bar entry.
• The alert's app icon is the bell logo (bell-logo.avif), with the bottom black bar removed and the bell centered on a transparent square. To regenerate the embedded icon (e.g. after changing the logo), run just icon — see Scripts/gen_icon.sh.