Feature: Add browser push notification support #488
Description
🚀 Feature Description
Is your feature request related to a problem?
As a user, sometimes I navigate away from Ambient to multitask on something else and miss when the agent is ready for me to provide input again. Sometimes this can be many minutes later. I'd like to be notified via an opt-in push notification.
Describe the solution you'd like
Add support for native web browser push notification APIs to ping the user's system when Ambient has completed a task.
💡 Proposed Solution
Detailed Description: Use the native browser push notification APIs to ping the user when the agent is finished with their last message.
User Experience: User clicks a bell icon in the Settings menu of a chat session (in chat area) to view its menu, clicks "Notification settings" to display a modal, and then can adjust their notification settings.
API Changes: That's for Amber to decide.
🎯 Use Cases
Primary Use Case: Any user with long-running sessions they may forget about.
User Stories:
- As a software developer, I want browser notifications when my agent completes tasks so that I can efficiently multitask without constantly checking the Ambient tab
- As a team lead, I want to be notified when review-ready sessions complete so that I can promptly provide feedback without blocking the team
- As a remote worker, I want desktop notifications for session status changes so that I can work across multiple applications while staying informed
🔧 Technical Considerations
Component: Frontend (Ambient Agentic Runner UI)
Implementation Approach:
- Implement using the Web Notifications API with browser permission requests
- Add notification settings to session-level UI (extending the existing Settings dropdown in
MessagesTab.tsx) - Store user preferences in localStorage or as part of project settings (similar to existing secrets/settings in
settings-section.tsx) - Trigger notifications based on session phase transitions (e.g., when phase changes from "running" to "waiting_for_input" or "completed")
- Integrate with existing
useAGUIStreamhook to detect agent completion states - Support notification configuration levels: off, session completion only, agent waiting for input, all status changes
Dependencies:
- No new npm packages required (native Web Notifications API)
- Requires HTTPS or localhost for browser notification permissions to function
- May benefit from adding a notification permission utility/hook for centralized management
Breaking Changes: No breaking changes. This is an additive opt-in feature with no impact on existing functionality.
📊 Success Metrics
How will we measure the success of this feature?
- Adoption rate: % of active users who enable notifications within 30 days of feature release
- Engagement improvement: Reduction in average response time when agent is waiting for user input (comparing before/after for users with notifications enabled)
- User feedback: Qualitative feedback from user surveys/interviews indicating improved workflow efficiency and reduced context switching costs
🔄 Alternatives Considered
Alternative 1: Email notifications
- Description: Send email alerts when sessions complete or need input
- Rejected because: Introduces more complexity (requires backend email service integration), higher latency than browser notifications, less suitable for real-time awareness during active work sessions
Alternative 2: In-app notification center/badge
- Description: Visual indicators within the application (e.g., badge count on favicon or tab title)
- Rejected because: Only works when user has the tab open/visible, doesn't solve the core problem of users working in other applications
Alternative 3: Slack/Teams integration for notifications
- Description: Send notifications through workplace chat platforms
- Rejected because: Adds external dependencies and setup complexity, not all users have these integrations, browser notifications are more universal and lower friction
Do nothing: Users continue to miss agent responses, leading to reduced productivity, longer session turnaround times, and frustration with perceived "waiting" when the agent has actually completed work and is ready for the next step. This degrades the overall user experience and perceived responsiveness of the system.
📋 Additional Context
Screenshots/Mockups:
- Notification settings modal should follow existing design patterns from
settings-section.tsxand other modals in the session page - Settings menu icon (gear or bell) should be added to the existing Settings dropdown in
MessagesTab.tsx(lines 380-399, 720-734) - Browser notification preview: Standard OS notification with "Ambient" title, session name, and status message
Related Issues: None currently identified
External References:
- MDN Web Notifications API
- Web.dev Push Notifications Guide
- Similar implementations: GitHub (PR review notifications), Linear (issue updates), Notion (page mentions)
✅ Acceptance Criteria
- Feature requirements clearly defined
- Technical design reviewed and approved
- User can request notification permissions from session UI
- User can configure notification preferences (off/completion/waiting/all)
- Notifications trigger appropriately based on session phase changes
- Notification settings persist across browser sessions
- Browser permission state is properly handled (denied/granted/default)
- Graceful fallback when notifications are blocked or unsupported
- Implementation completed and tested across major browsers (Chrome, Firefox, Safari, Edge)
- Documentation updated (user guide for enabling notifications)
- User acceptance testing passed
- Accessibility considerations addressed (alternative indicators for users who cannot use notifications)
- Performance impact measured (minimal overhead from notification logic)
🏷️ Labels
- Priority: medium
- Effort: M (Medium - ~2-3 days)
- Component: frontend
- Type: new-feature