mirror of
https://github.com/samsonjs/vibetunnel.git
synced 2026-03-26 09:35:52 +00:00
85 lines
4 KiB
Markdown
85 lines
4 KiB
Markdown
# Push Notifications in VibeTunnel
|
|
|
|
Push notifications in VibeTunnel allow you to receive real-time alerts about your terminal sessions, even when the web interface isn't active or visible. This keeps you informed about important events like completed commands, session exits, or system alerts.
|
|
|
|
## User Guide
|
|
|
|
1. **Enable Notifications**: Click the notification status indicator in the web interface (typically shows as red when disabled)
|
|
2. **Grant Permission**: Your browser will prompt you to allow notifications - click "Allow"
|
|
3. **Configure Settings**: Choose which types of notifications you want to receive
|
|
|
|
VibeTunnel supports several types of notifications:
|
|
|
|
- **Bell Events**: Triggered when terminal programs send a bell character (e.g., when a command completes)
|
|
- **Session Start**: Notified when a new terminal session begins
|
|
- **Session Exit**: Alerted when a terminal session ends
|
|
- **Session Errors**: Informed about session failures or errors
|
|
- **System Alerts**: Receive server status and system-wide notifications
|
|
|
|
Access notification settings by clicking the notification status indicator:
|
|
|
|
- **Enable/Disable**: Toggle notifications on or off entirely
|
|
- **Notification Types**: Choose which events trigger notifications (Session Exit and System Alerts are enabled by default)
|
|
- **Behavior**: Control sound and vibration settings
|
|
- **Test**: Send a test notification to verify everything works
|
|
|
|
Note that just because you can configure something, does not mean your browser will support it.
|
|
|
|
## Push and Claude
|
|
|
|
Claude code by default tries auto detection for terminal bells which can cause issues. You can force it
|
|
to emit a bell with this command:
|
|
|
|
```
|
|
claude config set --global preferredNotifChannel terminal_bell
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
- **Not receiving notifications**: Check that notifications are enabled both in VibeTunnel settings and your browser permissions
|
|
- **Too many notifications**: Adjust which notification types are enabled in the settings
|
|
- **Missing notifications**: Ensure your browser supports Service Workers and the Push API (most modern browsers do)
|
|
|
|
## Technical Implementation
|
|
|
|
VibeTunnel's push notification system uses rather modern web standards:
|
|
|
|
- **Web Push API**: For delivering notifications to browsers
|
|
- **Service Workers**: Handle notifications when the app isn't active
|
|
- **VAPID Protocol**: Secure authentication between server and browser
|
|
- **Terminal Integration**: Smart detection of bell characters and session events
|
|
|
|
### Bell Detection
|
|
|
|
The system intelligently detects when terminal programs send bell characters (ASCII 7):
|
|
|
|
- **Smart Filtering**: Ignores escape sequences that end with bell characters (not actual alerts)
|
|
- **Process Context**: Identifies which program triggered the bell for meaningful notifications (best effort)
|
|
|
|
## Subscription State
|
|
|
|
VibeTunnel stores push notification data in the `~/.vibetunnel/` directory:
|
|
|
|
```
|
|
~/.vibetunnel/
|
|
├── vapid/
|
|
│ └── keys.json # VAPID public/private key pair
|
|
└── notifications/
|
|
└── subscriptions.json # Push notification subscriptions
|
|
```
|
|
|
|
**VAPID Keys** (`~/.vibetunnel/vapid/keys.json`):
|
|
- Contains the public/private key pair used for VAPID authentication
|
|
- File permissions are restricted to owner-only (0o600) for security
|
|
- Keys are automatically generated on first run if not present
|
|
- Used to authenticate push notifications with browser push services
|
|
- Don't delete this or bad stuff happens to existing subscriptions.
|
|
|
|
**Subscriptions** (`~/.vibetunnel/notifications/subscriptions.json`):
|
|
- Stores active push notification subscriptions from browsers
|
|
- Each subscription includes endpoint URL, encryption keys, and metadata
|
|
- Automatically cleaned up when subscriptions become invalid or expired
|
|
- Synchronized across all active sessions for the same user
|
|
- If you get duplicated push notifications, you can try to delete old sessions here.
|
|
|
|
The subscription data is persistent across application restarts and allows VibeTunnel to continue sending notifications even after the server restarts.
|