​
Push Notifications in VibeTunnel

VibeTunnel provides real-time alerts for terminal events via native macOS notifications and web push notifications. The system is primarily driven by the Session Monitor, which tracks terminal activity and triggers alerts.

​
How It Works

The Session Monitor is the core of the notification system. It observes terminal sessions for key events and dispatches them to the appropriate notification service (macOS or web).

​
Key Monitored Events

  • Session Start/Exit: Get notified when a terminal session begins or ends.
  • Command Completion: Alerts for long-running commands.
  • Errors: Notifications for commands that fail.
  • Terminal Bell: Triggered by programs sending a bell character (^G).
  • Claude “Your Turn”: A special notification when Claude AI finishes a response and is awaiting your input.

​
Native macOS Notifications

The VibeTunnel macOS app provides the most reliable and feature-rich notification experience.
  • Enable: Go to VibeTunnel Settings > General and toggle Show Session Notifications.
  • Features: Uses the native UserNotifications framework, respects Focus Modes, and works in the background.

​
Web Push Notifications

For non-macOS clients or remote access, VibeTunnel supports web push notifications.
  • Enable: Click the notification icon in the web UI and grant browser permission.
  • Technology: Uses Service Workers and the Web Push API.

​
Troubleshooting

  • No Notifications: Ensure they are enabled in both VibeTunnel settings and your OS/browser settings.
  • Duplicate Notifications: You can clear old or duplicate subscriptions by deleting ~/.vibetunnel/notifications/subscriptions.json.
  • Claude Notifications: If Claude’s “Your Turn” notifications aren’t working, you can try forcing it to use the terminal bell: 
    claude config set --global preferredNotifChannel terminal_bell