diff --git a/docs/custom-node.md b/docs/custom-node.md
index a26ee599..990a09f5 100644
--- a/docs/custom-node.md
+++ b/docs/custom-node.md
@@ -119,4 +119,4 @@ The warning "changes being made to the file will invalidate the code signature"
 - The custom Node.js build process takes 10-20 minutes on first run
 - Cross-compilation is not supported - you must build on the target platform
 - The custom build excludes some features that may be needed by certain npm packages
-- Native module compatibility issues may occur when mixing Node.js versions
\ No newline at end of file
+- Native module compatibility issues may occur when mixing Node.js versions
diff --git a/docs/push-notification.md b/docs/push-notification.md
new file mode 100644
index 00000000..a66df2ca
--- /dev/null
+++ b/docs/push-notification.md
@@ -0,0 +1,76 @@
+# 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.
+
+## 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.