Skip to content

Configure notifications

This guide shows you how to configure notifications and what each setting really controls.

Notifications arrive on two surfaces. The notification centre — the bell in the title bar — reads a durable per-workspace feed on the server. OS toasts are a separate, desktop-only path fed by live frames pushed from the server.

  1. Go to Settings → You → Notifications
  2. Leave Enable notifications on
  3. Toggle the categories you want. There are exactly seventeen:
Category Fires when
Agent finished An agent replied in a run you started, or the run failed
Agent waiting on you An agent needs your approval, asked you a question, or is parked on a credential
PR published An agent published a PR
PR merged A PR was merged
New messages Someone mentioned you in a space
Mentioned in pull request GitHub’s notification poll saw you mentioned on a PR
Review requested Your review was actually requested on a non-draft PR
Review out of date New commits landed on a pull request you already reviewed
Ready to merge A pull request you authored became mergeable, or stopped being
Review decisions A reviewer approved, requested changes, or had an approval dismissed
Checks CI failed on a pull request you authored, or recovered
Review threads Someone replied in or resolved a thread you are in
Ticket assigned A ticket was assigned
Ticket status changed A ticket changed status
Meeting starting soon A calendar meeting is inside your lead window
Calendar disconnected A connected calendar’s OAuth token expired
Enclosure updates An enclosure was taken over, reclaimed or failed

Anything outside this list cannot be notified or filtered — there is no “everything else” category.

Agent waiting on you fires when a wait starts: a pending approval (including sandbox exec grants and Claude Code tool approvals), an ask_user question, or a run held because its credential cannot serve it. It opens the space where you answer, and stays quiet while you are already looking at that space.

On the desktop, these notifications behave differently from the rest:

  • They are time-sensitive. On macOS they can break through a Focus that allows time-sensitive notifications from Control Center.
  • An approval can be answered from the notification. Approve and Deny send your answer without opening the app. The server checks it in the same way as the in-app card. To approve for a set period instead, open the card.
  • An unanswered wait reminds you. If nobody answers, the notification comes back as Still waiting: … 3, 10, 25 and 45 minutes after the wait started. Each reminder replaces the previous notification rather than adding another. Reminders are skipped while a Control Center window has focus, because the approval card and the bell are already in front of you.
  • It disappears when the wait ends, however it was answered, so you never press a button on a request that has already been settled.

These preferences follow your user across devices, so a phone and a laptop stay in step. Volume is the deliberate exception and stays per device.

  1. On the same page, turn Quiet hours on
  2. Type a start and an end time in HH:MM (the default window is 22:00–08:00)

During quiet hours, non-urgent notifications are dropped — not queued and replayed later.

Two categories are urgent and always deliver, bypassing quiet hours and focus mode: Meeting starting soon and PR published. A meeting alert you only see afterwards is worthless, which is the reason.

  1. Scroll to Notification sound
  2. Pick one of the eleven bundled sounds, or None
  3. Press the test button to hear it and set the volume with the slider

The app plays the sound itself; the OS notification is delivered silently so you never hear it twice.

  1. Scroll to Alert lead time
  2. Pick 5, 10, 15 or 30 minutes

That is how far ahead of a calendar event the Meeting starting soon notification fires. The default is 5 minutes.

A notification is dropped, silently, when any of these is true:

  • Notifications are globally off, or its category is off
  • You are already on the route it would take you to — and, for a message, already in that space
  • A focus session with Block notifications on is running and the category is not urgent
  • Quiet hours are active and the category is not urgent

Those checks apply to OS toasts. The durable bell still records the event.

Two more suppressions live further upstream, in what the server sends at all:

  • An un-mentioned message from another human never becomes a notification
  • In a shared space, an agent’s reply pings whoever started that run, not every member
  • Agent-to-agent spaces are muted in the sidebar, so they never bump the human unread badge

Within a space there is no quiet corner: every conversation notifies equally, threads included. Read state is space-scoped, so unread aggregates across a space’s conversations rather than being tracked per conversation.

  1. Click the bell in the title bar

The popover shows recent activity, deep-linking each entry to what it is about. Opening it does not mark everything read — use Mark all as read in the header, or mark a single row. Read state follows your user across devices.

Authorisation is requested natively when the app launches. If you declined it, re-enable Control Center under System Settings → Notifications; there is no in-app prompt to re-trigger it.

I keep missing approval notifications on macOS

Section titled “I keep missing approval notifications on macOS”

By default, macOS shows Control Center’s notifications as banners, and a banner disappears after a few seconds. To keep them on screen until you act, set Control Center’s alert style to Persistent under System Settings → Notifications. An unanswered approval also comes back as a reminder (see Turn categories on or off).

Expected — the web build has no OS-notification pipeline. Use the bell.

The bell badge shows zero but there is clearly new activity

Section titled “The bell badge shows zero but there is clearly new activity”

Until the read-mark stream resolves after connecting, entries render as read to avoid a badge that flashes and then empties. It settles once the mark loads.

An agent’s run finished but nothing pinged me

Section titled “An agent’s run finished but nothing pinged me”

Check that you were not already on the space it happened in — an active route suppresses its own OS toast. In a shared space, a run someone else started pings them, not you. A turn that ended with no reply and no error sends nothing.