Skip to main content

Push Notification Implementation Plan

This document outlines the comprehensive plan for improving VibeTunnel’s notification system through two major initiatives:
  1. Creating a dedicated Notifications tab in macOS settings
  2. Migrating SessionMonitor from the Mac app to the server for unified notifications

Overview

Currently, VibeTunnel has inconsistent notification implementations between the Mac and web clients. The Mac app has its own SessionMonitor while the web relies on server events. This leads to:
  • Different notification behaviors between platforms
  • Missing features (e.g., notification settings parity between platforms)
  • Duplicate code and maintenance burden
  • Inconsistent descriptions and thresholds

Part 1: macOS Settings Redesign

Current State

  • Notification settings are cramped in the General tab
  • No room for descriptive text explaining each notification type
  • Settings are already at 710px height (quite tall)
  • Missing helpful context that exists in the web UI

Proposed Solution: Dedicated Notifications Tab

1. Add Notifications Tab to SettingsTab enum

2. Create NotificationSettingsView.swift

3. Create Reusable NotificationToggleRow Component

4. Update SettingsView.swift

5. Update GeneralSettingsView.swift

Remove all notification-related settings to free up space.

Standardized Notification Descriptions

Use these descriptions consistently across Mac and web:

Part 2: Server-Side SessionMonitor Migration

Current Architecture

Proposed Architecture

Implementation Steps

1. Create Server-Side SessionMonitor

2. Enhance Event Types

3. Integrate with PtyManager

4. Update Server WS v3 Hub

5. Update Mac NotificationService

6. Update Web Notification Service

Migration Strategy

Phase 1: Preparation (Non-breaking)

  1. Implement server-side SessionMonitor alongside existing system
  2. Add new event types to shared types

Phase 2: Server Enhancement (Non-breaking)

  1. Deploy enhanced server with SessionMonitor
  2. Server emits both old and new event formats
  3. Test with web client to ensure compatibility

Phase 3: Mac App Migration

  1. Update Mac app to consume server events
  2. Keep fallback to local monitoring if server unavailable
  3. Remove local SessionMonitor once stable

Phase 4: Cleanup

  1. Remove old event formats from server
  2. Remove local SessionMonitor code from Mac
  3. Document new architecture

Testing Plan

Unit Tests

  • Event threshold calculations
  • Activity state transitions

Integration Tests

  • Server events reach both Mac and web clients
  • Notification preferences are respected
  • Bell character detection

Manual Testing

  • Test each notification type on both platforms
  • Verify descriptions match
  • Test with multiple clients connected
  • Test offline Mac app behavior

Success Metrics

  1. Consistency: Same notifications appear on Mac and web for same events
  2. Performance: No noticeable lag in notifications
  3. Reliability: No missed notifications
  4. Maintainability: Single codebase for monitoring logic

Timeline Estimate

  • Week 1: Implement macOS Notifications tab
  • Week 2: Create server-side SessionMonitor
  • Week 3: Integrate and test with web client
  • Week 4: Migrate Mac app and testing
  • Week 5: Polish, documentation, and deployment

Risks and Mitigations

Conclusion

This two-part implementation will:
  1. Provide a better UI for notification settings on macOS
  2. Create a unified notification system across all platforms
  3. Reduce code duplication and maintenance burden
  4. Ensure consistent behavior for all users
The migration is designed to be non-breaking with careful phases to minimize risk.