Viewing Sessions
Browse hosts, open the terminal page, swipe between windows, and read alerts on your wrist.
The session list
When you launch vmuxWatch, the first thing you see is the session list. It is a single scrolling list with these sections:
| Section | What it shows | When to use it |
|---|---|---|
| Status | Whether the iPhone is reachable. | Glance to confirm the link is alive. |
| Phone Sessions | Open windows on the iPhone. | Tap to view a session that is already running. |
| Hosts On Phone | Saved hosts on the iPhone. | Tap to ask the iPhone to open or focus that host. |
| Saved | Hosts saved directly on the watch (manual flow). | Rarely used; mostly for hosts you typed in on the watch. |
| Manual | Single entry: Connect Manually. | Use when you want to type host details on the watch itself. |
A session that the iPhone currently has selected shows a small green broadcast icon next to its title. That is just an indicator; tapping any other session reassigns selection.
Each window entry shows three lines: the window's title, the host label below it, and the status line below that. The status line is the iPhone's current connection summary — for example, Connected 80×24 or Connecting… or a short error string.
Tapping a window
Tapping a window in Phone Sessions does two things:
- Tells the iPhone to make that window the selected one (so the iPhone foregrounds it on screen).
- Opens the watch's own terminal page for that window.
You will see the most recent screenful of output appear within a second. If output is still streaming on the iPhone side, you'll see new lines arrive as the iPhone debounces and forwards each snapshot.
Tapping a host on the iPhone
Tapping an entry under Hosts On Phone is slightly different. If the iPhone already has a window for that host, the watch behaves like you tapped that window. If there is no live window yet, the watch shows a hint to open the host on the iPhone first, then continue from the watch. This avoids the watch silently asking the iPhone to do an authentication round-trip with credentials it cannot see.
If you really want the watch to drive a fresh connection without the iPhone's help, use Connect Manually under the Manual section, type the host details and password directly on the watch, and tap the link icon. The connection is still made by the iPhone, but the watch supplies all the configuration.
The terminal page
The terminal page is a stack of three things:
- An optional red banner explaining a connection failure.
- A
TabViewof one or more windows, each rendered as a vertical stack of monospaced rows. - Two rows of mini buttons for input and tmux shortcuts.
The terminal renderer shows whatever the iPhone last sent. Empty leading rows are trimmed so output starts at the top. The cursor cell is replaced with a filled block (▉) so you can see where the shell prompt lives even when the actual character is a space.
Display modes
Two density presets:
| Mode | Font size | Line height | Min columns | Min rows | When to use |
|---|---|---|---|---|---|
| Dense (Dn) | 6 pt | 7 pt | 24 | 16 | You want to see as much of a wide terminal as possible. |
| Readable (Rd) | 8 pt | 9 pt | 18 | 12 | You actually want to read text without squinting. |
Tap the Dn / Rd button in the control row to switch. The watch sends the new viewport hint to the iPhone so the iPhone re-renders snapshots at a column and row count that fits the watch.
Swiping between windows
If the iPhone has multiple open windows, you can swipe left or right on the terminal page to flip between them. Each swipe also tells the iPhone to make that window the selected one — so what you see on the watch matches what the iPhone is foregrounding.
The page indicator dots are hidden to keep the screen clean. The connection label at the bottom right tells you which window you are on (Connected, Connecting…, or a short error reason).
Reading the connection label
The bottom right of the terminal page shows a small status pill. The label is shortened from the iPhone's status so it fits on the watch:
| Label | Meaning |
|---|---|
| Connected | The iPhone has a live PTY for this window. |
| Connecting… | The iPhone is dialing or authenticating. |
| Disconnected | The iPhone closed the PTY (idle, you closed it, or it ended cleanly). |
| No route to host | iPhone cannot reach the hostname over the network. |
| Connection refused | The hostname resolves but the SSH port is closed. |
| Timed out | The SSH/Mosh handshake exceeded its timeout. |
| Authentication failed | Wrong password, wrong key, or denied by the server. |
| Anything else | A truncated form of the iPhone's full status line. |
When the label says Connecting…, the failure timeout starts; if the iPhone has not acknowledged the request after about eight seconds, the watch shows a red banner explaining that the iPhone did not respond. Tap the reload button to retry, or check that the iPhone is unlocked and reachable.
Alerts and notifications
vmuxPhone forwards notifications to the watch through the standard iOS notification routing (not through the vmux relay). On the watch you may see:
- Bell — a session printed a
\abell character. Useful for "build done" alerts. - Command completed — vmuxPhone's marker-based command tracking detected a long-running command finished.
- Disconnect — a session dropped unexpectedly.
These are routed by iOS and obey your normal Watch notification preferences (per-app silent, per-app prominent, etc.). Customize them in the iOS Watch app under Notifications → vmux.
For the full taxonomy of what can fire a notification, see vmuxPhone — Notifications.
Returning to the list
Use the standard back gesture (left edge swipe or the Digital Crown) to return to the session list. Sessions stay open on the iPhone — the watch is a viewer, not a session owner, so leaving the terminal page does not disconnect anything.
Refresh cadence
While the watch is on your wrist and the session list view is visible, the watch asks the iPhone for a bootstrap refresh every two seconds. This is small and battery-cheap, and means a freshly opened iPhone-side window appears on the watch without you needing to scroll or pull.
When the terminal page is visible, no polling is needed: the iPhone pushes snapshots itself.
Related
- Pairing with iPhone — how the link works under the hood.
- Input on watch — typing into a session you are watching.
- Troubleshooting — when something is not appearing.