tmux & Mosh

MTerm integrates deeply with tmux and implements the Mosh protocol natively, giving you two powerful tools for managing remote sessions. This guide covers how both work and how to get the most out of them.

tmux Integration

If you use tmux on your remote server, MTerm makes it feel like a native part of the app rather than a separate tool running inside the terminal.

Mouse Mode Auto-Detection

MTerm automatically detects when tmux has mouse mode enabled and translates your touch gestures into the appropriate mouse events. No configuration needed on the MTerm side — just make sure your ~/.tmux.conf includes:

set -g mouse on

With this enabled, your touch interactions map directly to tmux actions:

Tap a tmux pane to switch focus to it
Scroll with touch or trackpad to scroll through tmux history

Three Mouse Mode Settings

You can control this behavior in MTerm’s settings:

Mode	Behavior
Auto (default)	Sends mouse events only when tmux has mouse mode active. When mouse mode is off, scrolling uses MTerm’s own scroll buffer instead.
Always ON	Always forwards touch events to tmux, even if mouse mode is not explicitly enabled. Useful if you want all scroll and tap interactions to go directly to tmux.
Off	Never sends mouse events to tmux. All scrolling uses MTerm’s local scroll buffer.

Alternate Screen Auto-Detection

MTerm detects when the terminal enters alternate screen mode (used by applications like Vim, less, htop, and tmux itself). This affects scroll behavior — when alternate screen is active, scrolling is forwarded to the running application rather than scrolling through MTerm’s local buffer.

tmux Session and Window Management

Because MTerm handles tmux mouse events natively, you can:

Tap on tmux window tabs in the status bar to switch windows
Tap on tmux panes to switch focus
Scroll within individual tmux panes
Use tmux’s mouse-based pane resizing by dragging pane borders

OSC 1212 Handler

MTerm implements the OSC 1212 escape sequence handler for context sharing and notifications between tmux and the app. This enables advanced integration scenarios where tmux can communicate state changes back to MTerm.

Mosh Connection

Mosh (Mobile Shell) solves one of the biggest frustrations of using SSH from a mobile device: dropped connections. Standard SSH over TCP dies the moment your network changes — switching from Wi-Fi to cellular, walking between access points, or encountering a brief network interruption. Mosh handles all of this gracefully.

How Mosh Works

Unlike SSH, which uses a persistent TCP connection, Mosh uses UDP. This means:

Network changes are invisible. Switch from Wi-Fi to cellular and back. Your session never drops.
Brief interruptions are handled automatically. If you lose connectivity for a few seconds (or even minutes), Mosh reconnects without losing any state.
Lower latency. Mosh predicts your keystrokes locally and displays them immediately, correcting later if the prediction was wrong. This makes typing feel responsive even on high-latency connections.
No hanging sessions. TCP connections can hang for minutes before timing out. Mosh connections either work or immediately tell you they are disconnected.

Setting Up Mosh

Install mosh-server on your remote host:

# Ubuntu/Debian
sudo apt install mosh

# macOS
brew install mosh

# CentOS/RHEL
sudo yum install mosh

In MTerm, edit the host settings and change the connection method from SSH to Mosh.
Connect as usual. MTerm will establish an initial SSH connection to bootstrap the Mosh session, then switch to UDP for the actual terminal session.

When to Use Mosh

Mosh is ideal when you are:

Working from locations with unreliable Wi-Fi (cafes, airports, trains)
Moving between networks frequently
Using cellular data with variable signal strength
Running long-lived sessions that you want to survive network interruptions

For stable connections on a reliable network, standard SSH works perfectly well and has the advantage of supporting port forwarding and other TCP-based features.

Mosh requires Pro plan

Live Activities (Lock Screen & Dynamic Island)

MTerm uses iOS Live Activities to keep you informed about your active sessions even when the app is in the background.

When you have an active SSH or Mosh session, a Live Activity widget appears on your Lock Screen showing the connection status. You can see at a glance whether your session is still connected, reconnecting, or disconnected — without unlocking your device or opening the app.

Dynamic Island

On devices with Dynamic Island (iPhone 14 Pro and later), MTerm displays a compact connection status indicator. Tap the Dynamic Island to jump straight back into your terminal session.

Why This Matters

If you are running a long Claude Code task and switch to another app to check email or browse documentation, Live Activities let you monitor the connection without repeatedly switching back to MTerm. Combine this with Webhook notifications and you can confidently leave the app knowing you will be informed when your task completes or if your connection drops.