q quicktuiv1 Get the App

Guide ยท tmux

How to attach a tmux session from your phone

tmux keeps your terminal sessions running on the machine after you disconnect: long builds, agents, log tails, and shells all stay alive. This guide walks through attaching to those sessions from an iPhone or iPad with QuickTUI, reattaching after a drop, and starting a fresh session when you need one.

The idea behind tmux persistence is simple: the session lives on the machine, not on the client. You attach a view to it, detach, and the work keeps going. QuickTUI is a native app (plus a browser client) that attaches to real tmux on your own machine, so the session you open on your phone is the same one you left in the terminal at your desk.

Install on your machine

Run the installer on the machine where your tmux sessions live. It sets up the QuickTUI service. On macOS/Linux you need tmux 3.2+ already installed (the installer does not install tmux). On Windows it installs the qscn session backend automatically.

macOS / Linux

curl -fsSL https://quicktui.ai/q.sh | sh

Windows (PowerShell)

irm https://quicktui.ai/q.ps1 | iex

The connection is direct by default, so your code and keys never pass through our servers. A single machine is free with full features; QuickTUI Pro is a one-time purchase that unlocks unlimited machine profiles.

Pair the app

Windows note: the session backend is qscn, not tmux. Create sessions with New Session in the app; the tmux new-session examples below apply to macOS/Linux.

Start a short-lived pairing QR on the machine and scan it once:

# macOS / Linux
quicktui-server --pair-qrcode

# Windows (PowerShell)
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --pair-qrcode

On a desktop session you can open the QR in your default browser instead:

# macOS / Linux
quicktui-server --pair-qrcode --browser

# Windows (PowerShell)
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --pair-qrcode --browser

Open the QuickTUI app on your iPhone or iPad, scan the QR code, and the server is added. You can also add it manually by URL and token if you prefer to type the details in.

Open, attach, and reattach

Working with agents? Start Claude Code, Codex, or any CLI tool inside a tmux session and supervise it from your phone. See run Claude Code from your iPhone.

FAQ

Does the session survive if my phone loses connection?

Yes. tmux keeps the session running on the machine, and QuickTUI's session keeper reattaches after a network change, a dropped connection, or an app restart, so you pick up where you left off.

How do I start a new tmux session?

On macOS/Linux, run tmux new-session -s name on the machine or in the app shell. On Windows use New Session in the app (qscn). The named session appears in QuickTUI's list to attach from iPhone, iPad, or a browser.

Do I need SSH?

No. QuickTUI talks to its own lightweight server over HTTP/WebSocket. You can reach it on your LAN, over a VPN or tunnel such as Tailscale or Cloudflare Tunnel, or a public address.

Related