Notifications & Agent Reminders

Notifications & Agent Reminders

How Prowl tells you an agent finished or needs you — system notifications, the bell/unread indicators, and Dock badge/bounce.

Keywords:notificationagent reminderbellunreadcommand finisheddock badgedock bouncesoundalertfinished

Related: agent-detection · active-agents · terminal · settings

What it is#

Prowl watches your panes and surfaces three kinds of alerts so you can leave the screen and come back exactly when you’re needed:

  1. Agent reminders — when an agent in an unfocused worktree rings the bell or emits a desktop notification (e.g. on finishing), Prowl flags that worktree (bell/unread) and can notify.
  2. Command-finished notifications — when a long-running command completes.
  3. Terminal bell / desktop notifications — bell (BEL) and explicit terminal notifications increment unread indicators.

When a notification fires#

Command finished posts a notification only when all hold:

  • commandFinishedNotificationEnabled is on,
  • the command ran longer than commandFinishedNotificationThreshold (default 10 s),
  • it wasn’t a user-initiated exit (Ctrl-C → exit 130, SIGTERM → 143),
  • you didn’t type in that pane within the last ~3 seconds.

Custom commands also post a success toast when they exit 0.

Whether these become macOS system banners depends on systemNotificationsEnabled; in-app alerts depend on inAppNotificationsEnabled. A standalone sound (notificationSound — a picker offering Never, the macOS system sounds, and the bundled Prowl Classic chime) plays only when system notifications are disabled — when banners are on, the banner carries its own sound.

Where unread shows up#

  • Sidebar: an orange bell next to a worktree with unseen notifications.
  • Toolbar: a bell button follows the Agents control in the leading area in Normal, Shelf, and Canvas. When an app update is available, its indicator appears in the same control immediately after the bell. The bell badge shows the unread count; opening the popover marks items read.
  • Shelf: orange highlight on the relevant tab slot + a dot on the spine.
  • Canvas: the card’s title bar turns orange.
  • Dock: an optional numeric badge (count of worktrees with unseen notifications).

Unread clears when you focus the relevant worktree/surface or view the notification. moveNotifiedWorktreeToTop floats a freshly notified worktree to the top of its section. Jump to Latest Unread (⌘⌥U) takes you straight to it.

Dock behavior#

  • Badge: showNotificationDotOnDock shows an unread count on the Dock icon. Requires macOS notification permission + “Badge app icon” enabled; Prowl disables the toggle if the system doesn’t allow it.
  • Bounce: dockBounceMode — off, once (single bounce), or continuous (bounces until you bring Prowl forward).

Settings (Settings → Notifications)#

  • inAppNotificationsEnabled — in-app alerts / bell indicators.
  • systemNotificationsEnabled — macOS system banners.
  • notificationSound — which sound to play (never, a system sound such as hero, or supacodeClassic = Prowl Classic, the default). Selecting a sound previews it. Replaces the legacy notificationSoundEnabled toggle (true → supacodeClassic, false → never on migration).
  • muteNotificationsForActiveSurface (default on) — skip the banner, sound, and dock bounce when the notification comes from the pane you’re already looking at (selected worktree, focused pane, key + visible window). Sidebar reordering still happens. Workflow status-edge notices are worktree-level rather than pane- level, so the selected worktree in a key, visible window counts as currently viewed.
  • moveNotifiedWorktreeToTop — float notified worktree to top.
  • commandFinishedNotificationEnabled + commandFinishedNotificationThreshold — long-command notifications and their minimum duration.
  • showNotificationDotOnDock, dockBounceMode — Dock badge & bounce.
  • Agent Island — an opt-in (agentIslandEnabled, default off) top-of-screen projection of Active Agents. Settings → Agents → Display selects Automatic placement or a fixed display; see agent-island.

Full field detail: reference/settings-fields.md.

Gotchas for agents#

  • The notification that matters most for human attention pairs with the Blocked agent state (a prompt waiting on the human) — see agent-detection.
  • Unread state is transient — focusing a worktree clears it; it isn’t a durable inbox.