Notifications
Push notification types, what each one means, and configuration in iOS Settings.
What vmuxPhone notifies you about
vmuxPhone posts local notifications — the iPhone fires them on its own, without a server push — for events that happen on connected sessions while the app is in the background. There are three categories:
| Category | When it fires | What you see |
|---|---|---|
| Bell | The remote shell or a program emits the bell character. | A notification with the host label and the working directory or window title. Plus a haptic. |
| Command completed | A shell command finishes (preexec / postcmd boundary, exit code captured). | A notification with the command, the exit code, and the last few lines of output. |
| Disconnected | A session disconnects or fails. | A notification with the host label and the disconnect reason. |
These notifications are anchored to the iPhone you are using. They do not sync to other Apple devices.
Bell notifications
When the remote shell prints the BEL byte (\x07, also known as \a), vmuxPhone:
- Plays a notification haptic on the iPhone.
- If the app is in the background or the screen is locked, posts a local notification with:
- Title — the host's display label.
- Body — the working directory if shell integration has reported one; otherwise the current window title.
- Sound — the default notification sound.
- Sets the alert badge on the matching Live Activity.
Bell notifications are throttled to one per 5 seconds per session. A burst of bells (a chatty IRC client, an apt mid-progress) does not flood your Lock Screen.
When the app is in the foreground, the notification is suppressed — vmuxPhone shows you the bell directly through the renderer (a haptic and a brief tint flash) instead.
Command-completed notifications
vmuxPhone uses shell-integration markers to detect when a command starts (__VP_CMD__) and finishes (__VP_DONE__). When a finish event arrives:
- The terminal event detector captures the last 5 non-empty output lines (capped at 200 characters).
- The notification service is invoked with a
CommandCompletedEventcarrying the command, exit code, summary, host label, and timestamp. - The system posts a notification.
The notification is informational. It does not allow you to reply or take action in this release. The command-completed flow requires shell integration on the remote — vmux ships an integration script for bash, zsh, and fish that exports the markers vmuxPhone listens for.
Without shell integration, you still get bell and disconnect notifications; only command-completed needs the integration.
Disconnect notifications
A disconnect or failure posts a notification with:
- Title — host label.
- Body — the reason (
Session disconnected,Connection failed: timeout, etc.).
The disconnect notification fires once. You will not get repeated alerts when vmuxPhone tries to reconnect — only the final state is announced.
Suppressed in foreground
Whenever vmuxPhone is in the foreground and the matching window is visible, the in-app status line, bell flash, and Live Activity update absorb the event. The local notification path is skipped because you are already looking at the terminal.
When a different vmuxPhone window is selected (i.e., the event happened on an inactive window), notifications still fire — you might be looking at one host while another rings the bell.
Granting permission
vmuxPhone asks for notification permission the first time the workspace activates, with the standard iOS prompt:
"vmux" Would Like to Send You Notifications. Notifications may include alerts, sounds, and icon badges.
Tap Allow. If you tap Don't Allow, you can change your mind later in Settings → vmux → Notifications.
Configuration in iOS Settings
The full set of switches is in Settings → Notifications → vmux:
| Switch | What it controls |
|---|---|
| Allow Notifications | Master toggle. Off disables all three categories. |
| Lock Screen | Show notifications on the Lock Screen when the iPhone is locked. |
| Notification Center | Persist notifications in the Notification Center for later review. |
| Banners | Show banners while the iPhone is unlocked and on the Home Screen. |
| Sounds | Play the default sound for vmuxPhone notifications. |
| Badges | Display the red number badge on the app icon. |
| Show Previews | Always, When Unlocked, or Never — controls whether the body text shows on the Lock Screen. |
| Notification Grouping | Automatic groups notifications by session thread. |
vmuxPhone uses a per-session threadIdentifier derived from the session UUID, so notifications from the same window group together when grouping is on.
There is no in-app override for any of these — vmuxPhone respects the iOS Settings.
Critical alerts
vmuxPhone does not request Critical Alerts entitlement. Notifications respect Focus modes, Do Not Disturb, and Sleep mode. There is no override for "always make a sound."
Watch routing
When a paired Apple Watch is on your wrist and the iPhone is asleep or locked, iOS routes notifications to the watch following the standard rules. There is no separate watch notification type — they are the same iOS notifications mirrored. See Watch pairing for the relay path.
Live Activities vs notifications
A Live Activity is the persistent indicator on the Lock Screen and Dynamic Island. A notification is a one-shot banner. They serve different purposes:
| Live Activity | Notification | |
|---|---|---|
| Persistence | Stays until session ends | One-shot |
| Updates | Real-time | None after delivery |
| Surfaces | Lock Screen, Dynamic Island, StandBy | Lock Screen, Notification Center, banners |
| Trigger | On every state change | On bell, command-completed, disconnect |
| Configurable | System Live Activity switch + per-app switch | Standard iOS notification settings |
Both are on by default and complement each other. You can turn off Live Activities and keep notifications, or vice versa.
Troubleshooting
Notifications never appear
Check Settings → Notifications → vmux. Allow Notifications must be on, and at least one of Lock Screen or Banners must be enabled. Restart the app after toggling.
Notifications appear with no body
Show Previews is set to Never or When Unlocked. Change it to Always to see the host name and body text on the Lock Screen.
Bell notification spams the Lock Screen
The 5-second throttle should keep this under control. If you still see floods, the remote shell is likely emitting BEL many times per second. Disable the bell in your shell config — set bell-style none in bash, set visualbell in vim.
Command-completed never fires
You probably do not have shell integration installed on the remote. Add the vmux integration to your ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish. The visionOS docs walk through it; the same script works on iPhone.
Related
- Live Activities — persistent Lock Screen indicator.
- Workspace — unread-activity badges on inactive windows.
- Mosh on iPhone — disconnect events during the lifecycle.