> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibetunnel.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Push notification

# 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:
  ```bash
  claude config set --global preferredNotifChannel terminal_bell
  ```