Alert Monitor widget
Shows live status of one saved vmux window with theme-aware colors and an unread-alert indicator.
What it does
The Alert Monitor widget watches a single saved vmux window and renders its current state in the window's own theme colors. It is the widget you place on your Home Screen for sessions you want to keep an eye on without unlocking the phone or opening vmuxPhone.
Each widget instance is bound to one window. The widget gallery lets you add multiple instances if you want to monitor several windows at once — one per Home Screen tile.
What you see
The widget is laid out as a compact terminal pane. From top to bottom:
- Header. A small terminal or bell glyph, the window's display name in monospaced caps, and a status chip on the right. The bell glyph appears when the window has an unread alert.
- Divider. A one-pixel rule in the window's accent color.
- Body. The window's display name in larger type, an optional subtitle line (working directory, host label, or whatever the window saved), and a status line prefixed with a
$prompt. A blinking-cursor block sits at the right edge.
Everything is drawn in the theme colors that vmuxPhone snapshotted for the window — foreground, background, accent, and alert. If the snapshot is missing, the widget falls back to a neutral dark theme so it stays legible.
Size variants
The widget supports two Home Screen sizes. The medium variant is not just a stretched small variant — it uses larger type and more padding to give the subtitle and status lines room to breathe.
| Family | Use case |
|---|---|
| Small | Place several side by side to watch a few windows at once. The header, status chip, and a single body line are all visible. |
| Medium | Single-row spotlight on one window. Subtitle and status text both have room without truncation. |
Status states
The widget surfaces four logical statuses. The status chip in the header and the body color cue change with each.
| Status | Meaning | Visual cue |
|---|---|---|
| Idle | The session is connected and quiet. | Status chip uses a faint foreground tint; body text is the window's foreground color. |
| Alerting | The session has an unread alert. | Header glyph swaps to a bell in the window's alert color; the chip stays neutral so the bell is the focal point. |
| Reconnecting | vmuxPhone is reconnecting the session. | Status chip uses the accent color tint; the chip text reads RECONNECTING. |
| Unavailable | The window's session cannot be reached — host is down, app is suspended, or the snapshot is too old. | Status chip uses the alert color tint; the chip text reads UNAVAILABLE. |
The chip text is whatever vmuxPhone wrote for the window's last status — Working, Restorable, Building, or any free-form label the window definition stored. The widget falls back to Working when no text is available.
What triggers the alert glyph
The widget shows the bell glyph any time the saved snapshot's hasUnreadAlert flag is true. vmuxPhone sets that flag when the underlying session produces a notification you have not yet acknowledged. The conditions that produce a notification are configured per-host in vmuxPhone — typically a regex match in the scrollback, an exit code, an idle-timeout breach, or an explicit vsh notify from inside the session.
To configure which session events become notifications, see Notifications on iPhone. The widget only mirrors the unread state; it does not initiate alerts itself.
Acknowledging a notification or opening the matching window in vmuxPhone clears the flag. The next widget refresh reflects the cleared state.
Refresh cadence
The widget rebuilds its timeline every 5 minutes by default, which is the policy iOS will honor when no other signal is available. In practice you will see fresher data because:
- vmuxPhone forces a widget reload whenever the saved snapshot changes — connect, disconnect, alert, or status update.
- iOS prioritizes widgets that the user has interacted with recently, so a Home Screen visit is enough to pull a recent state.
- A push notification that wakes vmuxPhone also causes a snapshot write and a widget reload.
There is no manual refresh button. If a widget looks stale despite an active session, see Troubleshooting.
Tap behavior
Tapping the widget opens vmuxPhone with a deep link to the bound window. If the session is already running, vmuxPhone selects it. If the window is restorable, vmuxPhone reconnects. If the window cannot be opened — the host has been removed, for example — vmuxPhone opens to the host list so you can decide what to do.
App Lock is honored. If you require Face ID or Touch ID to unlock vmuxPhone, the prompt runs after the tap and before the terminal becomes visible.
Choosing which window to monitor
Window selection happens in the widget editor, not inside vmuxPhone. After adding the widget, long-press it and pick Edit Widget. The Window field lists every saved window from your local snapshot. Picking one binds the widget; the next refresh redraws with the selected window's theme and status.
For a step-by-step walkthrough see Adding a widget.
Limits
- The widget shows one window. Use multiple instances for multiple windows.
- It does not render terminal output. Live scrollback on the Home Screen is not possible inside iOS's widget extension model.
- It does not animate. The blinking cursor is decorative and does not reflect activity.
- Lock Screen and StandBy families are not yet supported. Use Live Activities for the Lock Screen.
Related
- Adding a widget — how to add and edit instances.
- Troubleshooting — fixes for stale data and missing windows.
- Notifications — how the unread-alert flag gets set.
- vmuxPhone widgets — Recent Hosts, Session Status, and other vmuxPhone-bundled widgets.