Hide/show command for overlays (via API or CLI)

[anadale]

Feature request: hide/show command for overlays (via API/CLI)

Problem

Overlays in agterm are modal by design — they block interaction with everything else while open. The scratch terminal (cmd+J) is meant for quick, one-off commands, and the quick terminal works well but is limited to one per window.

None of these fit a common use case: long-running processes that live for the whole session, e.g. aspire run or npm start. You want to:

• start the process once,
• keep it running,
• glance at its logs occasionally,
• and get it out of the way the rest of the time.

Today the options are all unsatisfying:

• Dedicating a split to it — wasteful; the splits are needed for actual work.
• Dedicating a session to it — overkill for a single process.
• Scratch terminal — modal, and it's the wrong surface: it's for quick commands, not long-lived ones.
• Quick terminal — one per window, and single-purpose.
• Running tmux inside an overlay — exactly the kind of workaround this should avoid.

The existing surfaces are sensibly separated and each has a clear purpose. The goal is not to shoehorn this into one of them with a hack.

Proposed solution

Add hide/show commands for overlays, exposed through the API/CLI (agtermctl).

Behavior:

• If the overlay isn't running yet → the command starts it.
• If it is running → the same command toggles its visibility (show/hide).

Because it's an API/CLI-level command, arbitrary custom commands and keyboard shortcuts can be built on top of it. Map it to a key once, and it works identically across all sessions.

Alternatives considered

• Multiple scratch-like surfaces, launchable via commands/API. More flexible, but a bigger design change.
• "Workspace per project" — one session for agents, another for the runtime. Possibly the "correct" architecture, but heavier and less portable across sessions.

The hide/show command is the smaller, more incremental change, and it composes well with existing shortcut/command customization.

Open question

How well does non-modal (or hideable) behavior fit the current overlay design, which assumes modality? This is the main thing worth discussing.

[umputun]

the use case here is legit: a home for long-lived processes (watchers, builders, dev servers) you start once and only glance at occasionally, without tying up the scratch for it.

I looked at whether overlays could be that home, and I don't think they fit.

two shapes came up:

• CLI hide/show for the existing overlay: start it hidden, show/hide over agtermctl, still modal when shown.
• going further, non-modal overlays like the quick terminal: click the pane behind the overlay to hide it while it keeps running.

both break what makes the overlay easy to reason about. Today the model is tiny: one overlay per session, always visible while open, and you close it by exiting its process. A hidden-but-running state breaks the "singular and visible" part, and the follow-on cases don't resolve cleanly:

• the single slot can now hold something you can't see. If a hidden watcher is running and you open a second overlay (say yazi), there's no intuitive answer. Rejecting looks wrong on a screen that shows no overlay, replacing silently kills your watcher, and keeping both is just "multiple overlays", the exact thing I wanted to avoid.
• non-modal makes it worse. You get two dismiss gestures that mean opposite things (click-away keeps the process alive, escape kills it), plus you need a persistent indicator so a hidden overlay isn't a ghost you forget about.

net, it piles a lot of surface onto a concept that should feel simple, and the mental model stops being intuitive. So I'm going to leave overlays as they are: singular, visible, exit-to-close.

for the actual need, a dedicated session fits, and it's lighter than the "overkill" in the first post suggests. Spinning one up just for the watcher is cheap. Run it there (a background session if you don't want it grabbing focus), switch to it when you want to look, and it stays up the whole time with the overlay concept untouched.

if someone sees a shape that gives a hideable long-lived process without wrecking the overlay model, I'm open to it.