[Feature] Detach and resume multiplexed sessions without killing them

[jvanderen1]

Problem

There are times where I want to briefly leave a multiplexed session (tmux -CC, raw tmux, zmx, zellij, herdr) without killing the remote session, then reconnect later (especially when I know network may drop).

Today:

• tmux -CC already supports graceful self-detach (gateway context menu, Sessions eject, ESC on the gateway), but it is easy to miss when the gateway tab is auto-hidden.
• ⌘⇧X Detach Other Clients only detaches other tmux clients — not yourself.
• Other multiplexers have no first-class “leave cleanly / keep session / reconnect” path.
• Reopening a mux auto-start profile while still attached can feel like spawning an unrelated new window.
• Missing remote binaries can silently fall through to $SHELL while the UI still looks attached to that multiplexer.

Desired direction

1. Self-detach is obvious — Tabs → Detach Session / tab context menu from any attached tab, including tmux window tabs when the gateway is hidden. Optional user-assigned keybinds in Settings (no new default chord — avoid stealing macOS Dock ⌘⌥D or anyone’s existing shortcuts).
2. Works across multiplexers — tmux -CC graceful detach; raw tmux / zellij / herdr native chords; zmx close-client (recommended detach).
3. Resume, don’t spawn — opening the same mux auto-start profile while a live attachment exists focuses that UI (including zmx: don’t open a second client to the same named session by default).
4. Post-detach reconnect affordance — short banner (“session keeps running”) with Reconnect; dismissible via ✕.
5. Honest auto-start — if the multiplexer isn’t on the host, say so and don’t pretend the pane is still that mux.

Inspired in part by iTerm2’s detach / resume journey for multiplexed sessions — worth a shout-out for the UX pattern.

Non-goals / notes

• ⌘⇧X remains “detach others” for tmux -CC.
• zmx is one PTY per named session (not multi-window restore like tmux -CC). Intentional multi-attach can still happen via session discovery if needed later.
• Prefer discoverable self-detach over teaching users to hunt for a hidden gateway.

Status

Contributor PoC in progress locally; manual testing before PR.

[kitknox]

If using tmux I would strongly suggest trying out our control mode tmux -CC based attachment and then just opening up the specific tabs you want. If you want the detach shortcuts of tmux or zmx to return you to a regular shell you just need to attach via session discover or have the auto attach be a custom command you run as typed text into a shell once it launches so the actual launched command in your base shell.

I am not 100% sure I understand your ask, but that was my best guess?

[jvanderen1]

This was primarily driven by how iTerm2's "detach" user journey

iTerm.Detach.Session-gh.mp4

I am also okay forgoing this exact way of detaching, but being able to detach and resume whenever I can would be helpful (especially if I know I am going to lose internet connection).

Happy to contribute a PR if desired!

[kitknox]

If using tmux control mode rootshell has built in detach that leaves you back at the shell that did the control mode attach. Right click on the gateway. If you pair this with tssh it seamlessly handles losing internet connections and even reboots. Is this what you are looking for? With that said this is only for tmux and not the other multiplexers currently.

[jvanderen1]

Thanks for the swift reply!

I don't actually see the "Detach" option within the tab options:

Tmux.Missing.Detach-gh.mp4

Is this currently in a development release? I am currently using the latest version installed via Homebrew.

With that said this is only for tmux and not the other multiplexers currently.

This sounds like there are plans on adding this to other multiplexers. Are you open to PRs for this?

As an aside, I want to say this has by far been my favorite terminal to use. You've got my support!

[kitknox]

Detach is only on the gateway tab, which you don't seem to have visible there (perhaps auto hide enabled?). The eject button in the tmux Session view also performs a detach and is visible in your screenshot.

[kitknox]

Does it still seem like something is still missing here? There is currently a keyboard shortcut for detaching all of the OTHER clients, but not yourself.

[jvanderen1]

Yes — that shortcut gap is exactly what felt missing.

⌘⇧X (Detach Other Clients) only kicks other tmux clients. Self-detach for tmux -CC already existed (gateway menu / ESC / Sessions eject), but it was easy to miss when the gateway is auto-hidden, and it didn’t cover zmx / raw tmux / zellij / herdr the way iTerm2’s “detach, keep session, reconnect later” journey does.

I’ve been iterating a PoC for this issue that aims at that journey across multiplexers:

1. Self-detach everywhere — ⌘⌥D / Detach Session on window tabs (not only the gateway), plus native chords for raw muxes; zmx uses close-client (its recommended detach).
2. Resume, don’t spawn — reopening a mux auto-start profile while already attached focuses the live UI instead of a second unrelated-looking client.
3. Post-detach Reconnect banner — clear “session keeps running” feedback with a one-click reconnect.
4. Honest auto-start failures — if the remote binary is missing, print that and open a normal shell (no silent $SHELL while the UI still looks like zmx/tmux).

I’ll update the issue description to match this direction. Still doing manual testing before any PR — happy to adjust based on what you want in-tree vs leave as guide/docs only.