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.
Turn categories on or off
Section titled “Turn categories on or off”- Go to Settings → You → Notifications
- Leave Enable notifications on
- Toggle the categories you want. There are exactly ten:
| Category | Fires when |
|---|---|
| Agent finished | An agent finished a run |
| PR published | An agent published a PR |
| PR merged | A PR was merged |
| New messages | A message arrived in a space you are not looking at |
| 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 |
| 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 |
Anything outside this list cannot be notified or filtered — there is no “everything else” category.
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.
Set quiet hours
Section titled “Set quiet hours”- On the same page, turn Quiet hours on
- 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.
Choose a sound
Section titled “Choose a sound”- Scroll to Notification sound
- Pick one of the twelve bundled sounds, or None
- 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.
Set the meeting lead time
Section titled “Set the meeting lead time”- Scroll to Alert lead time
- Pick 5, 10, 15 or 30 minutes
That is how far ahead of a calendar event the Meeting starting soon notification fires.
Know when a notification is suppressed
Section titled “Know when a notification is suppressed”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
- Focus mode is active and the category is not urgent
- Quiet hours are active and the category is not urgent
Two more suppressions live further upstream, in what the server sends at all:
- An un-mentioned message from another human never becomes a notification
- Agent-to-agent spaces are muted by construction. They never bump an unread badge and never fire a toast
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.
Read and clear the notification centre
Section titled “Read and clear the notification centre”- Click the bell in the title bar
The popover shows recent activity, deep-linking each entry to what it is about. Opening it marks everything read and read state follows your user across devices.
Troubleshooting
Section titled “Troubleshooting”No OS notifications on macOS
Section titled “No OS notifications on macOS”Authorization 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.
Nothing arrives on the web build
Section titled “Nothing arrives on the web build”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 your identity resolves after connecting, entries render as read to avoid a badge that flashes and then empties. It settles once the session identifies you.
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 notification.