Skip to content

In App Notifications

Jump to bottom
Sia edited this page Jun 2, 2026 · 1 revision

In-App Notifications

A top-right notification bell appears on every admin page (v1.88.0+). It surfaces build, Claude-task, usage and system events without leaving the current screen, and each event kind can be toggled on/off (v1.89.0+).

Bell + mini-panel

  • Bell icon is fixed at the top-right of every chrome page (hidden on the login / setup pages and inside iframe-embedded inner pages).
  • A red badge shows the unread count (capped at 99+). No badge when there are none.
  • Clicking the bell opens a mini-panel that lists the newest notifications first, color-coded by kind, each with a title, optional body and a relative timestamp.
  • Clicking an item navigates to its deepLink (console / build detail / usage) and marks it read.
  • The panel's bottom-right "Clear all" button acknowledges every unread item.
  • The bell polls GET /api/notifications every 30 seconds; the list is re-rendered only while the panel is open.

The UI is inlined into the page shell (no separate static asset), so it is unaffected by service-worker / ?v caching.

Notification kinds

kind When Color
build.success A Gradle build succeeds green
build.failed A build fails red
claude.turn_done A console turn (task) completes blue
claude.stopped A task is cancelled by the user amber
claude.error The Claude process crashes red
usage.threshold Claude usage hits the configured threshold amber
system General / system notices grey

Claude turn events (claude.turn_done / claude.stopped / claude.error) are emitted for manual turns only — automation runs (which fire many turns back-to-back) and ghost projects (__scratch__, chat ghosts) are excluded.

Choosing what to receive

Settings → Notifications (/settings/notifications, listed as In-app alerts in the Notifications category) shows a checkbox per kind. Unchecking a kind makes NotificationService.emit skip persisting it — it will no longer accrue in the bell or list.

  • Stored at <workspace>/.vibecoder/notification-prefs.json and applied immediately (no restart).
  • Opt-out model: any kind not present in the file defaults to on, so newly added kinds are received until explicitly disabled.

REST API

All endpoints authenticate via Authorization: Bearer <token> or the vibe_session cookie. See REST API Reference for full request/response shapes.

Method Path Purpose
GET /api/notifications Unread list + unreadTotal
POST /api/notifications/ack Acknowledge specific ids ({"ids":[...]})
POST /api/notifications/ack-all Acknowledge all unread (the "Clear all" button)

Acknowledge is a soft operation (sets ackedAt, kept for audit); a daily retention job hard-deletes rows acked more than 30 days ago.

Related

Clone this wiki locally