Native tmux control mode (-CC) — remote tmux windows as native sessions

[eShreder]

I'd like to propose native tmux -CC (control mode) integration and check whether the direction
fits agterm before investing in a PR.

The idea

Attach to a (remote or local) tmux session in control mode and present it natively:
tmux session → agterm workspace (ephemeral, never persisted), tmux window → agterm session,
rendered by real agterm surfaces, with input/resize round-tripped back to tmux. Detach, drop the
ssh connection, reattach later — remote processes survive.

Whatever one thinks of iTerm2 (and there's plenty to think), its -CC mode is the one feature I
genuinely missed after leaving it — and I'm not aware of another macOS terminal that has it. It
would fit agterm's model unusually well, since the workspace → session hierarchy maps one-to-one
onto tmux's session → window.

On the README's "a tmux-style backend is out of scope" line: this wouldn't touch the restore
design. Restore still restores local shells, and the denylist still keeps multiplexers out of
auto-restart. Attach is an explicit opt-in action (a menu item + control commands); nothing
changes unless you use it.

My main motivation is agent workflows: an agent running inside remote tmux survives laptop sleep
and network drops, while the control API can attach to it and drive its windows as ordinary
sessions (session.type, session.copy, status hooks). Naturally the feature would come with
full control-API/CLI coverage (tmux.attach/detach/list/kill) and the usual keep-in-sync
surfaces.

Scope for a v1: no in-window splits (a split window shows its leading pane), one connection per
tmux session. The one architectural cost to flag up front: libghostty has no PTY-less surface /
"feed bytes to the screen" API, so painting tmux panes needs a small additive patch to the engine
(io/apprt layer only) applied over the pinned GHOSTTY_REV — a maintenance cost on every rev
bump, and potentially upstreamable to ghostty itself.

Does this direction fit? I'm happy to do the work and would split it into small bottom-up PRs.

[umputun]

the mapping is the appealing part, and you've read it right. Tmux session-to-window really does line up with agterm's workspace-to-session, and the ephemeral-attach framing holds: restore wouldn't need to change, because persistence here is projection by omission, the same way scratch and overlay terminals already never survive a relaunch. The control coverage (tmux.attach/detach/list/kill) drops into the existing dispatch cleanly, and session.type/session.copy/status hooks would drive an attached window unchanged. So it's not a bad fit for the model, if anything it fits unusually well.

the blocker is the cost you flagged yourself: the libghostty patch. Agterm builds libghostty from upstream at a pinned SHA specifically so there's no fork and no prebuilt binary in the chain, and that's deliberate. A patch re-applied over GHOSTTY_REV on every bump is a fork by another name, on the one subsystem I keep dependency-clean on purpose. And the pin isn't free-floating: it sits at 4dcb09a (2026-04-30), the last commit I verified before a libghostty renderer regression on main that blanks the terminal scrollback on a font-size increase (a decrease is fine). So bumping GHOSTTY_REV is already delicate, I'm holding it back on purpose until that's fixed upstream, and a carried engine patch would make every future bump permanently harder. I'd also push back on framing it as a small io/apprt patch: feeding bytes into a PTY-less surface isn't a tweak to the existing path, it's a second surface lifecycle with no child process, and the whole C-callback safety contract (single-owner/single-free, the view passed as unretained userdata) is derived from libghostty owning the pty and driving the tick. That contract would have to be re-derived for a byte-fed surface. Until such an API is upstream, it's a cost agterm carries alone.

the other thing: the main motivation, an agent in remote tmux surviving sleep and network drops and still drivable over the control API, already works today with no new code. agtermctl session new --command "ssh host" running tmux attach gives you exactly that. Survival is a property of the remote tmux server, and session.type/session.copy/session.status operate on that session regardless of what's running in it. So the real delta -CC buys over that is the native window-to-sidebar-row mapping plus -CC's own scrollback and resize. That's a real UX gain, but a rendering nicety rather than a new capability.

weighing it: the part I'd sign up for (the model and control side) is the easy part, and the part that gates it (a standing libghostty patch) is exactly what I want to avoid. So as it stands I'm going to say this doesn't fit, not because the idea is wrong, the fit really is nice, but because the cost is concentrated in the one place the project is built to keep clean. What would change my answer is a way to feed a surface without a carried engine patch, e.g. ghostty proper growing a PTY-less or attach-an-fd surface API. If that existed, everything above that line becomes interesting again. If you wanted to pursue getting such an API upstream, I'd follow that with interest.

[eShreder]

Built myself a tmux -CC variant without patching libghostty — each tmux window is mirrored into an ordinary command-session through a small local relay (agtermctl tmux-pipe over a socket), so it renders in a stock surface. PR

Works well; you can even forward the agterm socket into the ssh session and drive notifications from there. Fair warning — it ended up being a lot of code. For now I just re-sync the branch with upstream now and then