Full-window zoom

[melonamin]

I'm missing this feature from my tmux setup: zoom to full window in any terminal surface. It works like a toggle, per window.

Demo

Screenshot.2026-07-06.at.16.20.18.mp4

p.s. probably should show window controls in zoomed-in state too, looks a bit alien without it. But not sure yet.

[umputun]

tmux prefix+z maps cleanly onto agterm, and most of it is scriptable today - I wired up a toggle and it works. The two moving parts (maximize the focused pane, hide everything around it) both have control commands.

Scriptable now

session split off shows the focused pane maximized, not always the main one - it honors which pane you're on. sidebar hide gives full window width. Chain them behind a per-window marker file (sidebar visibility isn't readable over the socket, so the marker is how un-zoom knows what to restore) and bind it in keymap.conf:

#!/bin/bash
# tmux-style full-window zoom toggle. per-window state in a marker file.
set -u
wid=$(agtermctl window list --json | jq -r '.result.windows[]|select(.active)|.id')
marker="/tmp/agterm-zoom.${wid:-default}"
if [ -f "$marker" ]; then
  read -r sid split < "$marker"
  agtermctl sidebar show
  [ "$split" = true ] && agtermctl session split on --target "$sid"
  rm -f "$marker"
else
  read -r sid split < <(agtermctl tree --json \
    | jq -r '.result.tree.workspaces[].sessions[]|select(.active)|"\(.id) \(.split)"')
  printf '%s %s\n' "$sid" "$split" > "$marker"
  agtermctl sidebar hide
  agtermctl session split off --target "$sid"
fi

# keymap.conf - a single chord, or a leader like ctrl+a>v
command "Zoom" ctrl+a>v ~/bin/agterm-zoom.sh

one gotcha: keymap-launched commands run via /bin/sh -c with the plain launchd PATH, not your shell's. agtermctl resolves (it installs into /usr/local/bin), but a Homebrew jq won't, so give jq an absolute path in the script. That aside, it's a real per-window zoom toggle that restores the split state you had. One rough edge: the sidebar animates in and out, so the toggle is a visible slide, not the instant snap tmux gives.

What a script can't reach

two gaps, both app-side:

• the title bar stays. sidebar hide gives full width but there's no command to drop the chrome, so it's not the borderless look in your demo. This is the flip side of your "should show window controls in zoomed state" note - right now you can't hide them at all.
• no way to float the live surface. The one that would fit - the non-full overlay (overlay open --size-percent N), which floats a framed panel over the session - still runs a new program in a fresh pty; it can't host your existing surface. So an overlay-style zoom is a real feature, not a script.

so the everyday result is a keybinding away already, and building it in mainly buys the chrome-hide and an instant snap. If I do more, roughly three directions:

1. leave it - keep the script as the answer, accept that a floating (%-size) overlay isn't zoomable.
2. add a command to resize an overlay after it's open - a zoom factor that's useful on its own, independent of this.
3. a universal zoom toggle over the control API, addressable by surface id, so any pane one-shots to full and back.

my default is do-nothing / minimal, but option 2 is worth having regardless, and a one-shot per-pane zoom (option 3) is genuinely appealing - probably comes down to how cheaply that per-pane zoom can be built.

[melonamin]

(option 3) is genuinely appealing - probably comes down to how cheaply that per-pane zoom can be built.

Checkout #158 doesn't look terrible

[umputun]

as built this is the GUI half of option 3, not the one I was after. What I described as appealing was zoom over the control API, addressable by surface id. This is a frontmost-active-surface toggle wired to keymap/menu/palette (cmd+shift+return, toggle_terminal_zoom), and the only control-side changes are two guards that reject quick/search while zoom is on. No zoom command, no agtermctl subcommand, no id addressing. For agterm that's the keep-in-sync gap: a new toggle isn't done until it's drivable over the socket and the agent-skill is updated. That's also the part a script genuinely can't do, so it's where the value is.

on chrome: you hide the traffic lights and titlebar for the borderless look, which is the opposite of your own "maybe keep the window controls" note. I'm fine either way but we never settled it, and the current pick has a side effect worth seeing: with no titlebar the window can't be closed/moved/minimized by mouse while zoomed, and Cmd-W is swallowed (closeActiveSession early-returns). So zoom becomes a modal state you can only leave through the toggle. Intentional?

cheapness was my gate for option 3, and it splits. TerminalZoom.swift is exactly right, host-free, 95 lines, well tested. The WindowContentView side is +270/-58 threading a deckInteractive/deckHostsSurface gate through every branch of sessionDetail and reaching into the deck/split/focus machinery, which is the part I'm most wary of since that's the fragile surface (eager deck, NSSplitView overrun, reparent focus).

two blockers regardless of the above:

• swiftlint is red: WindowContentView.swift is 1059 lines now, over the 1000 cap. Pull the zoom rendering into WindowContentView+Zoom.swift rather than raising the limit.
• no XCUITest for the rendering integration, which is the risky part. The core has good swift test coverage, the view wiring has none.

so before you push it further: addressable control-API route (closer to what I framed), or keep it GUI-only? And is the chrome-hide + modal-window behavior the feel you want?

[melonamin]

Ah, now I got what you mean. Yeah, exposing it to the full API control would be more in line with the overall agterm ethos. I'll follow up.

On traffic lights I'm still undecided, will play around more with both options to get the feel.

[melonamin]

Ok, covering all behaviors and edge cases turned out to be quite a lot, but I think I've done it

Decided to keep the traffic lights chrome; otherwise, it feels a bit weird on macOS.

Screenshot.2026-07-07.at.16.20.56.mp4

[umputun]

update on the three directions from my earlier comment - a couple of the pieces I flagged are in now.

option 2 (a command to resize an overlay after it's open) shipped as session.overlay.resize (#163). It resizes an open overlay and switches it between floating and full-pane in place, no re-spawn. Useful on its own like I hoped, independent of zoom.

the two rough edges I called out on the scripted route are gone too:

• the sidebar used to animate in/out, so the toggle was a visible slide, not the instant snap tmux gives. Made it instant (9440f1a). The animation was interpolating the split width every frame, which reflowed every session's surface and janked with many sessions open; now it's one layout pass, so the script zoom snaps.
• sidebar visibility wasn't readable over the socket, so un-zoom had to trust a blind marker file. tree.sidebarVisible reads it back now (Preserve split-pane focus on re-show, add sidebar-visibility read-back to the control API #159), and split-pane focus is preserved on re-show, so the toggle restores exactly the pre-zoom state (sidebar only if it was showing, focus back where it was).

so the scripted route is clean now. Current version, keyed off the live tree instead of a blind marker:

# keymap.conf - a single chord or a leader like ctrl+a>v
command "Zoom" ctrl+a>v ~/bin/agterm-zoom.sh

#!/bin/bash
# tmux-style full-window zoom toggle, per-window marker state.
#   zoom:    hide the sidebar (only if showing) + collapse the split to the focused pane
#   un-zoom: restore both to the pre-zoom state
set -u
wid=$(agtermctl window list --json | jq -r '.result.windows[]|select(.active)|.id')
marker="/tmp/agterm-zoom.${wid:-default}"
if [ -f "$marker" ]; then
  read -r sid split sidebar < "$marker"
  [ "$sidebar" != false ] && agtermctl sidebar show
  [ "$split" = true ] && [ -n "$sid" ] && agtermctl session split on --target "$sid"
  rm -f "$marker"
else
  tree=$(agtermctl tree --json)
  sidebar=$(printf %s "$tree" | jq -r '.result.tree.sidebarVisible')
  read -r sid split < <(printf %s "$tree" \
    | jq -r '.result.tree.workspaces[].sessions[]|select(.active)|"\(.id) \(.split)"')
  printf '%s %s %s\n' "$sid" "$split" "$sidebar" > "$marker"
  [ "$sidebar" != false ] && agtermctl sidebar hide
  [ -n "$sid" ] && agtermctl session split off --target "$sid"
fi

(jq needs an absolute path in practice - keymap commands run under the launchd PATH, not your shell's.)

none of this replaces option 3. An addressable, per-surface zoom over the control API is still a valuable addition on its own: drivable headless, and it reaches the quick terminal and overlays that a sidebar/split script can't. The building blocks above just make the scripted version solid in the meantime.