Skip to content

[Feat] Add native OS notifications for background task events#157

Merged
samzong merged 2 commits intomainfrom
feat/desktop-notifications
Mar 24, 2026
Merged

[Feat] Add native OS notifications for background task events#157
samzong merged 2 commits intomainfrom
feat/desktop-notifications

Conversation

@samzong
Copy link
Copy Markdown
Collaborator

@samzong samzong commented Mar 24, 2026

Summary

Add native OS notifications via Electron Notification API so users don't miss task completions and approval requests when the app is backgrounded or minimized.

Type of change

  • [Feat] new feature

Why is this needed?

When ClawWork is minimized or unfocused, users have no way to know a task finished or an approval is pending. The existing in-app sonner toasts are invisible when the window isn't visible. The tray icon updates status but never pushes OS-level alerts.

What changed?

  • New notifications.ts service in main process wrapping Electron Notification with isDestroyed/isMinimized guards matching the tray pattern
  • New notification-handlers.ts IPC handler (notification:send) registered alongside existing handlers
  • Preload bridge: sendNotification (invoke) + onNotificationNavigateTask (event listener)
  • maybeNotify() helper in useGatewayDispatcher — async settings check with .catch(), called at three event points: task completion (state === 'final'), approval request (exec.approval.requested), gateway disconnect
  • Shared navigateToTask callback in App.tsx for both tray and notification click-to-navigate
  • NotificationConfig added to AppConfig and AppSettings with three boolean toggles (all default to enabled via !== false)
  • Data-driven notification toggle UI in GeneralSection using existing Toggle + SettingRow components
  • i18n keys added to both en.json and zh.json

Architecture impact

  • Owning layer: main (notification service + IPC handler), preload (bridge), renderer (dispatcher + settings UI)
  • Cross-layer impact: yes — new IPC channel notification:send (invoke) and notification:navigate-task (event from main to renderer). Follows the same pattern as existing tray IPC channels.
  • Invariants touched from docs/architecture-invariants.md: none. Message persistence is not affected — notifications are fire-and-forget side effects triggered after finalizeStream, not part of the write path.
  • Why those invariants remain protected: notification calls are placed after existing store mutations and sync calls, not interleaved with them.

Linked issues

N/A

Validation

  • pnpm lint
  • pnpm test
  • pnpm build
  • Manual smoke test
  • Not run

Commands, screenshots, or notes:

pnpm check  # lint + architecture guardrails + format:check + typecheck + test — all pass

Screenshots or recordings

Settings UI adds a "Notifications" card below "General" with three toggles:

┌─ Notifications ────────────────────────┐
│ 🔔 Task completion      [ON/OFF]      │
│ 🔔 Approval requests    [ON/OFF]      │
│ 🔔 Gateway disconnection [ON/OFF]     │
└────────────────────────────────────────┘

Release note

  • No user-facing change. Release note is NONE.
  • User-facing change. Release note is included below.
Add native desktop notifications for task completion, approval requests, and gateway disconnection. Notifications appear when the app is backgrounded or the user is viewing a different task. Click a notification to jump directly to the relevant task. Toggle each notification type independently in Settings → General → Notifications.

Checklist

  • The PR title uses at least one approved prefix: [Feat], [Fix], [UI], [Docs], [Refactor], [Build], or [Chore]
  • The summary explains both what changed and why
  • Validation reflects the commands actually run for this PR
  • Architecture impact is described and references any touched invariants
  • Cross-layer changes are explicitly justified
  • The release note block is accurate

@github-actions
Copy link
Copy Markdown
Contributor

Hi @samzong,
Thanks for your pull request!
If the PR is ready, use the /auto-cc command to assign Reviewer to Review.
We will review it shortly.

Details

Instructions for interacting with me using comments are available here.
If you have questions or suggestions related to my behavior, please file an issue against the gh-ci-bot repository.

@samzong samzong merged commit 5533381 into main Mar 24, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant