tmux Integration

tmux runs on the server and keeps your shell, and anything running in it, alive when the connection drops or the app closes. PocketCmd starts terminals inside tmux, lists the server’s tmux sessions so you can return to them, and shows the current session, window and pane in the session’s breadcrumb.

The tmux integration works on SSH, Mosh and ET servers. It is not available for Telnet; if a Telnet device runs tmux, start it yourself after logging in.

Requirements

tmux must be installed on the server:

# Debian / Ubuntu
sudo apt install tmux

# Fedora / RHEL
sudo dnf install tmux

# Alpine
apk add tmux

# macOS (Homebrew)
brew install tmux

Live session state (below) needs tmux 3.2 or later. Older versions fall back to polling.

Turn on tmux for a server

In the server form, turn on Enable tmux. The switch appears after Test Connection or when you edit a saved server. If tmux was not found, it reads tmux (not detected) and shows install instructions when tapped.

With tmux enabled, every new terminal on the server starts in a new tmux session. The server sheet’s New terminal picker can turn tmux on or off for a single launch without changing the server’s setting. See Home Screen.

Return to a tmux session

The server sheet’s Sessions list shows every tmux session found on the server, after this device’s saved Mosh and ET sessions. Sessions already open in the app are listed first. Each entry shows its windows, panes and when it was created.

• Tap a session to open it in a terminal.
• Long-press for Open, Rename and Kill Session.
• Refresh sessions asks the server again and also re-checks which protocols it offers.

Closing a terminal that runs tmux detaches from its session; the session keeps running on the server and stays in this list, which PocketCmd refreshes shortly afterwards. Use Kill Session to end it.

Reattach after a drop

When a connection drops, PocketCmd reconnects and reattaches to the same tmux session, so the programs in it keep running and the screen comes back as it was:

• SSH reattaches after the new login.
• Mosh starts the tmux session as the mosh-server command, so resuming the Mosh session resumes tmux with it.
• ET reattaches after the ET connection is restored.

A startup command is typed only into a tmux session’s first shell, never into a session PocketCmd reattaches to.

The breadcrumb

In a tmux session the breadcrumb at the top of the terminal shows the session name and the current window:

• Tap the session name to Switch tmux session: pick another session on the server, or start a New Session.
• Tap the window to open Pane Layout, where you can switch windows and panes, Split H, Split V, Zoom In or Zoom Out on a pane, Kill a pane, and open a New Window.

PocketCmd’s own split screen is separate from tmux panes. A split-screen pane can hold a terminal that has tmux panes of its own.

Live session state

On tmux 3.2 and later, the breadcrumb follows tmux through a control-mode channel (tmux -C). tmux reports changes as they happen, so a window created from another computer, a split pane or a renamed session appears in the app within about a second, even while the terminal is busy with heavy output. Session switches, pane and window commands and scrollback capture use the same channel.

PocketCmd falls back to asking tmux for its state every five seconds on tmux older than 3.2, on a host with no tmux session yet, and whenever the control channel fails.

The state channel uses its own pooled SSH connection, whatever protocol the terminal uses, so the breadcrumb and session switching work on Mosh and ET too. PocketCmd opens that connection silently. On a server that would need you to type a password, the breadcrumb falls back to a plain label instead of prompting.

To turn the state channel off, use Settings › tmux › Live Session State. With it off, PocketCmd sends no background tmux traffic, the breadcrumb shows a plain label, and you cannot switch sessions from it. Terminals still start in and reattach to tmux. The switch takes effect in open sessions without reconnecting.

tmux settings

Settings › tmux applies to every server:

Setting	Default	What it does
Live Session State	On	Keeps the breadcrumb in sync, as described above.
Detach on Destroy	On	When a session ends, detach instead of jumping to another session.
Detach Other Clients	Off	Detaches other clients when PocketCmd attaches, so a stale client cannot shrink the window to its size.
Mouse Mode	On	tmux handles scrolling, clicking and selection.
Status Bar	On	Shows the tmux status bar.
Apply tmux Theme	Off	Styles tmux sessions with the theme chosen under tmux Theme.
History Limit	10,000 lines	Scrollback lines per pane, from 1,000 to 100,000. Applies to newly created panes.

With it off, a tmux session can stay attached on a computer and in PocketCmd at the same time. tmux sizes a window to its smallest attached client, so turn Detach Other Clients on if a forgotten client keeps the window too small.

tmux themes

The PocketCmd and PocketCmd Light tmux themes match the app’s dark and light colors and are available on Free. The other presets and the tmux theme editor require PocketCmd Pro. See Themes & Backgrounds.