Add OS notifications for turn completions

[malekelkssas]

• New setting to enable/disable notifications when turns finish
• Tracker detects thread state transitions (running → idle/error/stopped)
• Notifications only show when tab is unfocused; fallback to in-app toast when focused
• Handles permission requests and restricted contexts gracefully

What Changed

Added system-level (OS) notifications that fire when a turn finishes and the
user is not actively focused on the app. Includes a toggle in Settings → General.

• New enableTurnCompletionNotifications client setting (off by default)
• Tracks thread session transitions (running → idle/ready/error/stopped/interrupted)
• Fires native OS notification via the Notification API when the page loses focus
• Falls back to an in-app toast when the tab is actively focused
• Automatically prompts for browser notification permission when toggled on
• Seeds tracker from snapshot so page refreshes mid-turn still detect completion

Why

When running long agent tasks, users often switch to another app (terminal, IDE,
browser tab) while waiting. There was no way to know the turn finished without
manually checking back. This adds an ambient signal through the OS notification
system so the user gets notified wherever they are — same as any other desktop
notification on their system (Linux, macOS, Windows).

UI Change

Notification setting

video record for the notification trigger

Screencast_._.webm

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Adds new client setting and hooks notification logic into the root orchestration event pipeline; behavior depends on browser Notification permissions/focus detection and could introduce noisy or missed notifications if tracking is wrong.

Overview
Adds opt-in OS-level notifications when an orchestration turn completes, driven by a new enableTurnCompletionNotifications client setting (default off).

Introduces turnCompletionNotifier.ts to track running threads from snapshots and thread.session-set events, request notification permission, and emit browser Notifications only when the page isn’t actively focused (with graceful fallback).

Wires the notifier into __root.tsx’s event-batch processing to detect running→non-running transitions and either show an OS notification or fall back to an in-app toast; also adds a Settings toggle (with reset support) that prompts for permission when enabled.

^{Reviewed by Cursor Bugbot for commit 08b67ff. Configure here.}

Note

Add OS notifications for thread turn completions

• Adds a new enableTurnCompletionNotifications boolean to settings.ts (default false) and a toggle in the General Settings panel that requests browser Notification permission on enable.
• Adds turnCompletionNotifier.ts with utilities to track running threads, detect turn-completion transitions from event batches, and fire OS notifications when the page is not focused.
• The event router in __root.tsx calls these utilities on each event batch, falling back to in-app toasts when OS notifications are unavailable or permission is denied.
• Behavioral Change: enabling the setting will trigger a browser permission prompt; OS notifications are only sent when the page is not focused.

^{Macroscope summarized 08b67ff.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: a200676f-4412-4b74-a9d3-557d1e8536ed

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[malekelkssas]

@cursor review

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new user-facing feature (OS browser notifications for turn completions) with ~190 lines of new logic, including state tracking and browser API integration. While the feature is gated behind a setting that defaults to off and is well-structured, new features introducing new user-facing behavior warrant human review regardless of how self-contained they are.

^{You can customize Macroscope's approvability policy. Learn more.}

[malekelkssas]

@cursor review

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 08b67ff. Configure here.}

[cursor]

Tracker state becomes stale when notifications are disabled

Low Severity

When notificationsEnabledRef.current is false, extractTurnCompletions is entirely skipped. This function has a critical side effect: it maintains the runningThreadIds module-level tracker by adding IDs on "running" events and removing them on completion events. Skipping it when notifications are disabled means stale "running" entries accumulate and are never cleaned up. If a thread was tracked as "running" before notifications were toggled off, and the thread completes during the disabled period, its ID stays in the set. When notifications are re-enabled, any subsequent non-running session-set for that thread could trigger a spurious completion notification. The tracker update logic needs to run unconditionally, independent of whether notifications are shown.

Additional Locations (1)

• apps/web/src/turnCompletionNotifier.ts#L96-L117

 

^{Reviewed by Cursor Bugbot for commit 08b67ff. Configure here.}