Sessions: Your tmux Sessions, New Session and Needs You

The Sessions list

Sessions has a section for each host with something running, headed by the host's name, and an icon for each kind of session. Within a host, rows come in this order:

AI coding tools: Claude Code, Codex, Gemini and others.
Conn's tmux shells and commands, marked Shell or Command.
Other tmux: tmux sessions you started yourself, outside Conn.
This device's single sessions (marked This device only) and screens.

Each row shows the session's name, its kind, its folder and how long ago something happened. Also open elsewhere means another device or terminal is attached to it too. A host's own page has a Live Sessions card with the same rows.

With sessions on two or more hosts, a Host Filter shows all hosts or one. The Sessions tab's badge counts open sessions, and gets a dot when one needs you.

A session marked Other tmux is your own tmux: Conn opens it and copies its attach command, and changes nothing there.

What the labels mean

Label	Means
Needs you	The session is waiting for you, such as Claude Code asking for a yes. See Needs you.
Showing	A terminal on this device has it open.
Quiet	Nothing has printed for a minute or more.
Ended	The program in it has exited. tmux keeps it so you can read what it left.
Watching / Controlling	A screen, and whether you control it.
Reconnecting, Checking the connection	Conn is bringing the link back, or checking it after a return.

A session that's printing has no label.

How the list stays up to date

When Sessions or a host's page opens, Conn lists the tmux sessions on your hosts. It uses a terminal already open on the host, or a short connection with the saved sign in.
A host whose sign in needs Face ID, Touch ID or your passcode waits for you, so Conn never asks unprompted.
Refresh lists every host. Check, beside a host's name in Sessions or on its page, lists that one.
While Conn is open, it looks every 30 seconds on hosts with a terminal open, over that terminal. That look never opens a new connection or asks for Face ID.
A line says which hosts couldn't be listed: under the host's heading, or, for a host with nothing listed, under the list (with why behind its i). Reasons include no saved sign in, a host key not yet trusted on this device, or no tmux (with Install).

Conn lists hosts set to tmux, and hosts where this device has started a tmux session.

Opening, closing and ending

Tap a row (click on a Mac) to open it. If a terminal on this device is already in that session, it comes forward. Touch and hold, swipe, or right click a row for more:

Item	What it does
Rename...	Changes the name Conn shows. The session keeps its own name in tmux.
Open in New Window	Opens it in a window of its own (iPad and Mac).
Open Here Only	Opens it here and detaches your other devices, so it takes this screen's size. Their terminals stay at a shell until you open it there again.
Copy Attach Command	Copies the tmux command that attaches to it, to type in a shell on the host.
End Session	Stops it on the host, and whatever it runs, after asking.
Remove	Clears an ended session from the host and the list.

Closing isn't ending. The × on a tmux session closes it here only. It keeps running on the host, and its row stays so you can open it again. End Session stops it on the host, and the row goes with it. On an ended session the × removes it, as Remove does. A single session ends when you close it.

New Session

New Session starts Claude Code, Codex, Gemini, a shell or a command in a folder, in tmux or as a single session. Find it in a terminal's ⋯ menu, at the top of Sessions, on a host's Live Sessions card, or with ⌘T on a Mac or an iPad keyboard.

Field	What to choose
Host	Any host with Terminal turned on.
Run	Claude Code (the default), Codex, Gemini, Shell, or Command, which adds a field for the command, such as `htop`.
Runs in	tmux or Single session. It starts on the host's own choice, and applies to this session only.
Folder	Where it starts. Empty means the home folder. Recent Folders lists the last few for the host (kept on this device only), and the list button browses the host's folders when its sign in is saved.
Name	For tmux: the name Sessions shows. tmux names the session after the folder.

Press Start. In tmux, Conn opens a login shell in the folder and starts the tool there; when the tool exits, its shell stays. Claude Code and Codex are started so they ring the terminal bell when they need you, which is how Needs you knows. As a single session, Conn types cd to the folder and the command at the shell's prompt.

A tool that isn't on the host: Install shows the tool's own installer first, then types it in a terminal there, or shows it for you to copy. Codex and Gemini need Node.js.
No tmux: the host offers Install. See Installing tmux.
iPhoneiPad If you leave Conn while Start is working and the host doesn't answer in time, Conn tries again when you come back. A typed install can stop part way if Conn goes to the background.
In tmux on a Mac host, a banner says if Claude Code isn't signed in, with Unlock Keychain.

A single session ends when you close it or the link drops, and has no Needs you.

Needs you

Needs you means a tmux session is waiting for you. Conn sets it when:

a session started from New Session rings the terminal bell, as Claude Code and Codex do when they need an answer;
in a session started from New Session, Claude Code reports it's waiting, or Codex or Gemini shows that an action is required;
a bell or a program's notification reaches a terminal on this device while you're not at it.

Open the session and answer it, and it clears. A bell in the terminal you're typing in doesn't count (on a Mac, unless the Mac is locked, asleep or idle for 2 minutes).

How you're told

iPhoneiPad The Sessions badge gets a dot, and a banner comes down at the top unless that session is on screen. Tap it to open the session, or tap its × (or flick it up) to dismiss it.
Mac Conn posts a notification and Sessions gets a red dot. Click the notification to open the session. The menu bar icon gets a dot too, and lists that session first. Notify When a Session Needs You, in Settings, Terminal, turns notifications off.

Needs you works while Conn is open. Conn looks every 30 seconds on hosts with a terminal open. Nothing is said while Conn is closed, or on iPhone and iPad while it's in the background, because Conn has no servers to send push notifications.

On all your devices

tmux sessions live on the host, so every device you use lists them, through its own connection.
A host's tmux choice syncs with iCloud sync on. A single session belongs to the device it's on.
Handoff picks up a tmux session on another device. See Handoff.
Mac Conn's menu bar icon lists your sessions, ones that need you first, and up to five tmux sessions per host, with Show All in Sessions where a host has more.