Panes and layout

Tiling, the slot grid, resizing by the gutter, keyboard arranging, maximizing, pane motion, stashing, and undoing a close.

Everything TermHQ opens is a pane in a tiled grid. Nothing hides behind a tab.

There are three kinds, and the grid treats them identically — every move below works on any of them:

An SSH connection opens as a terminal pane too, once you turn SSH on in Settings → SSH → SSH connections; it is off by default.

The slot grid

Every pane occupies a rectangle of grid cells. Move, swap, and grow panes to arrange your workspace; opening and closing panes can repack the grid to fit.

That is the arrangement. How wide each cell is, is a separate and much simpler question — see Resizing panes below.

There is no limit on how many terminals you can open. The grid keeps growing to hold them, and two presets in the title bar decide the shape:

• Grid — kept square-ish. Four panes make a 2×2, five to nine go three wide, ten to sixteen go four wide, and so on.
• Columns — every pane is a full-height strip, however many there are.

Each workspace keeps its own choice, and switching keeps the panes in the order you read them. Switch between Grid and Columns does it from the keyboard once you give it a shortcut in Settings → Shortcuts.

When the columns no longer fit the window, the grid scrolls sideways rather than squeezing them. A window too narrow for both the sidebar and the grid closes the sidebar first, and opens it again once there is room, without changing your sidebar setting.

Past the point where everything still fits comfortably, the answer is usually to park what you are not watching on the shelf, or fill the screen with one pane — both below, and neither stops anything running.

Panes also fall upward: a pane rises until it rests on the top edge or on another pane. That is what makes floating islands and phantom rows impossible, so resizing the window always divides the space over real rows.

A single terminal fills the whole grid area rather than sitting in one half-width cell. Spawning or cloning splits it back into the grid.

In Grid, an empty cell offers New terminal and Open file…, and whatever you open from one lands in that cell.

Pane style

The grid has two looks, chosen in Settings → Appearance → Pane style. Spaced, the default, keeps a small gutter between terminals and rounds their corners. Boxy removes both — terminals meet edge to edge with square corners, the tiling-window-manager look. Borders stay on in either style, so two terminals never blur into one, and switching is instant: no pane reflows or resizes, only the chrome around it changes.

Either way, the boundary between two panes is a resize handle; boxy simply puts it on the seam where they meet instead of in a gutter.

Settings → Appearance → Dim unfocused panes washes every pane but the focused one toward the theme’s background, so the one you are typing into stands out. It is off by default, and clicks still reach the dimmed panes.

Pane motion

Panes move rather than jump. When they swap, move or resize, they glide into place. A new pane settles into its cell with a quick fade while the others glide aside, and a closed pane fades from its place as the grid closes up under it. Stashing flies a pane down into the shelf’s count, which bumps as it lands, and restoring one rises back out into its cell. Maximize grows a pane from its cell until it fills the grid, and Restore shrinks it back. The sidebar slides in and out while the panes glide beside it, and a workspace appears in one fade, already laid out.

Settings → Appearance → Animate panes turns all of it off. It is on by default; off, panes jump straight to where they go. Reduced motion in your system settings turns it off too.

The pane header

Every header starts with a mark that says what the pane is: a prompt for a terminal, a globe for a browser, a page for an editor. It lights on the focused pane and pulses in the attention color when a run goes quiet. The focused pane keeps its header buttons in view; the others show theirs when you hover.

A terminal’s header shows its whole working directory. When the path does not fit, the start gives way first and the folder’s own name stays. Hover the path to read all of it, and click its text to copy it.

• Double-click the header, name included, to maximize the pane.
• Middle-click the header (click the scroll wheel) to close the pane, as on a browser tab. It closes exactly the way the header’s own close button does.
• Right-click a terminal’s header for Rename…, Copy path, Reveal in File Explorer (Reveal in Finder on macOS), the pane’s own actions, and Close. On a browser or editor pane, a right-click on the header renames it.
• F2 renames while the keyboard is on the header’s buttons. In the terminal itself, F2 stays with the program. Rename the focused pane does it from anywhere, once you give it a shortcut in Settings → Shortcuts.

Rearranging with the mouse

Drag a pane’s header. A translucent copy of the header follows the pointer, so it stays clear which pane you picked up, and names what letting go would do: Swap, Move here or Grow. A dashed destination preview shows where it will land. Press Esc at any point to cancel.

It is one gesture family, borrowed from Windows snap:

Closing a pane re-packs the rest in reading order, so middle holes close and the grid shrinks back through square sizes — unless you have hand-grown a pane, which switches to a gentler reflow that does not disturb your arrangement.

Closing or stashing the pane you are in keeps your place: the grid closes up, and the pane that moves into that cell takes the keyboard. Close the sixth pane of a three-wide grid and what was the seventh is selected. If the grid loses a column or a row, the pane in the same corner takes it instead, so closing the top-right pane leaves you top right. When nothing moves in because the last pane went, the one before it does.

Resizing panes

The space between two panes is a handle. Put the pointer on it, the cursor turns into a resize arrow, and dragging moves that boundary wherever you want it — the same gesture as dragging a window edge, and the same one every tiling window manager uses.

Which panes move follows from where the boundary is. Panes with an edge on the boundary you are dragging move with it; panes that do not touch it do not move at all. With three columns open, resizing the first two leaves the third exactly where it was.

Where four panes meet, the crossing is a corner: grab it and both boundaries move at once, diagonally, the way an operating system’s window corner does.

A few things fall out of that:

• Double-click any boundary — or a corner — to even up the pair it separates. It is the “make this sensible again” gesture, scoped to the edge you clicked rather than resetting the whole grid.
• A pane can never be dragged out of existence. Columns stop at 280px at 100% interface scale — the floor grows with the scale, to 420px at 150% — and rows stop at 240px, so the boundary refuses rather than tearing.
• Gutters take the keyboard too. Tab reaches one, the arrow keys move it 24px at a time (96px with Shift), and Enter evens up the pair it separates.
• Only the boundary under your pointer lights up — a thin line on the one that would move, and the one you are actually holding is a shade brighter still. It waits a moment before appearing, so sweeping the pointer across a gutter on the way somewhere else lights nothing; stop on one and the line is there immediately. Leaving is never delayed.

The gesture is the reason a browser pane and a terminal can share a row honestly: a web page has a natural width and a terminal does not, so 70/30 is often the right answer and 50/50 never was.

Putting it back

Two ways, at two scales. Double-clicking one boundary levels the pair it separates. For the whole grid, a small reset button appears in the title bar beside the Grid/Columns switch.

It is only there when there is something to reset — drag a pane off its equal share and it appears; level the grid again and it goes. That is deliberate on both counts: a button that spends most of its life doing nothing is furniture, and one that shows up only when the grid is custom answers “why is this pane wider than the others?” just by being there. Reset pane sizes does the same from the command palette, or from a shortcut you give it.

Opening or closing a pane resets the sizes

A hand-tuned layout is tuned around the panes that were in it. So opening a new pane — or closing, stashing, or restoring one — puts every boundary back to equal.

Nothing else disturbs them. Swapping, moving, growing, arranging and resizing the window all leave your proportions exactly as you set them, and a workspace remembers them across restarts.

A maximized pane and a lone pane have no boundaries to drag, because there is nothing on the other side of one.

If you would rather the grid simply divided itself evenly, Settings → Appearance → Resize panes by dragging turns the whole thing off: equal shares, no handles. Your proportions are kept while it is off, so switching back on returns the layout you had.

Arranging from the keyboard

Everything the drag can do, without the mouse. Press Ctrl+Shift+G to enter arrange mode, then use the arrow keys. What a press does depends on what is in that direction:

• Arrow pushes the pane that way: it grows into free space, keeps growing on further presses, or swaps with a neighboring pane. When it cannot advance, it pulls its back edge inward.
• Shift + arrow moves the pane one cell while keeping its size, where it fits.
• Ctrl + arrow shrinks it from that direction. On macOS it is ⌘ + arrow, because Ctrl + arrow belongs to Mission Control there.

A size-preserving move toward several smaller panes can swap the entire block when it fits.

You can also bind Push pane left / right / up / down under Settings → Shortcuts → Arrange without the mode. These perform the same push without entering arrange mode and have no default shortcuts.

While the mode is on, the pane you are arranging is outlined, and a hint bar names the mode and previews what each arrow would do from where the pane stands: grow, swap, move or shrink. Esc or Enter finishes, and any other key — or any mouse click — simply leaves the mode and does its usual job, so the arrows are never held hostage once you have moved on.

Panes will not grow past the edges of the grid in any direction, downward included. The chord itself is refused when there would be nothing to watch: a single pane, or a pane already maximized over the others.

Maximize

Ctrl+Shift+Z, a double-click on a pane header, or the header’s Maximize button fills the grid with one pane; the same action restores the grid. Hidden panes stay alive throughout, and moving focus while maximized carries the maximize to the next pane rather than dropping back to the grid.

With pane motion on, the pane grows from its cell until it fills the grid, and Restore shrinks it back into place, with the other panes fading in around it once it lands.

With only one pane in the grid there is nothing to maximize: the chord is refused, and a double-click on the header does nothing.

Font size

Separate from the above, and per-pane. Ctrl+= and Ctrl+- change the focused pane’s font size, Ctrl+0 resets it, and Ctrl+wheel — or a trackpad pinch, which arrives as the same event — changes whichever pane is under the pointer, editor panes included. An agent’s wall of output can be small while the shell you type in stays comfortable.

A terminal shows the size it landed on for a moment, with the way back: 15 px · Ctrl+0 resets.

The status bar

The thin bar along the bottom of the window is always visible. The pane grid ends above it, so items appearing or disappearing do not cover your work or change the space available to panes.

Workspace is at the far right, with Stash immediately beside it when panes are parked. Worktrees appears at the left when you have configured worktree roots. Undo close and the waiting-pane list appear as needed, before Stash and Workspace.

Right after Worktrees — or at the far left without it — the focused pane’s branch appears whenever that pane is inside a Git repository, with how many files have changed and how far the branch is ahead of or behind its upstream. Click it to open Source Control.

When something fails that can be tried again, the bar says so beside the branch, with the reason on hover and a Retry button: Settings weren’t saved, or a shell that did not start, such as Git Bash didn’t start. Other short notices, such as why a dropped file was refused, appear in the same place and can be dismissed.

The waiting item is a count — N waiting — that stays as long as anything is waiting. For a few seconds after a new pane goes quiet, a chip joined to its left names that pane under a draining bar; click the chip to jump straight there, the way Undo close restores. Open the count to see the list, then select a pane to return to it; with two or more waiting, Dismiss all clears them at once. It is hidden when empty unless you enable Settings → Agents → Always show it, even when nothing is waiting, in which case it reads 0 waiting. See When a pane needs your attention for notification controls and what makes a pane qualify.

Ctrl+Shift+N (⌘+Shift+N on macOS) jumps to the newest waiting pane, bringing it back from the shelf or out from behind a maximized pane if it has to. Focus the previous pane takes you back to where you were; it has no default shortcut, so give it one in Settings → Shortcuts or run it from the command palette.

In a narrow window the branch and workspace items drop their names and the Undo chip drops the pane’s; marks and counts stay.

Stashing

A pane can be stashed with Ctrl+Shift+S or the header’s ↓ button: hidden from the grid while its shell keeps running and its scrollback survives. This hides a job, it does not stop one. A stashed browser pane is the same bargain — the page stays loaded, and restoring it returns the same scroll position — and a stashed editor keeps its tabs and any unsaved edits in them.

Stashed panes collect behind a count in the status bar, immediately to the left of Workspace. With pane motion on, a stashed pane flies down into the count, which bumps as it lands, and a restored one rises back out of it into its cell.

Click the stash count — or reach it with Tab and press Enter, or press Ctrl+Shift+O from anywhere — to open the shelf in the window’s bottom-right corner: a list with one row per parked pane. A row says what the pane is, with a mark for its kind and the name its header shows, and where it is: a terminal’s whole folder, a page’s address, the file an editor has open, an SSH pane’s host.

• Click a row, or press Enter on it, to restore that pane into the first free slot. The list closes so you can watch it land.
• Close a pane without restoring it with the row’s ×, a middle click on the row, or Delete (Backspace too, while the list has no filter). The row slides out and the list stays open, so you can close several in a row.
• Restore all and Close all sit at the foot of the list whenever more than one pane is parked, and on the count’s right-click menu (or Shift+F10 with the count focused). Restore asks first only when the panes in the grid plus the ones on the shelf would exceed nine, and close always asks, saying what closing means under your Undo close setting. Both are in the command palette too, as Restore all stashed panes and Close all stashed panes, with no default shortcut.

A parked pane that went quiet while you were elsewhere moves to the top under Waiting on you, with the time it went quiet, and its row glows in the attention color. The rest follow under Stashed, most recently stashed first.

The list takes the keyboard while it is open. ↑ and ↓ move through the rows and the foot and wrap around, Home and End go to either end, and Esc puts the list away and hands the keyboard back to your pane. Nothing you type reaches a shell while the list is open, and any other shortcut puts the list away first and then does its job. Opened from the keyboard, the list starts on its first row. Opened with a click, nothing is selected until you press an arrow or point at a row, and pointing and the arrows move the same single selection.

Past eight parked panes a filter box appears above the rows, and every opening starts on the first row. The filter is one more stop in the loop: ↑ from the first row reaches it, and ↑ again continues from the bottom, so holding an arrow cycles through everything. Start typing on any row to filter by name or place; Enter in the filter moves to the first match, and Enter again restores it.

When the last stashed pane is restored or closed, the stash count disappears. The status bar itself stays in place.

Undoing a close

Closing a terminal removes its pane immediately, but the shell underneath keeps running during the undo window. Undo close in the status bar restores the most recently closed terminal in one click, and names the pane it will bring back; the closed-pane count opens the full list. These controls appear before Stash and Workspace, keeping that pair together at the far right.

A draining bar shows how long each shell will remain available, and each row of the list counts its seconds down. A row’s Restore brings that terminal back and its × closes it now; with two or more closed, Restore all and Close all now act on the whole list. Show recently closed panes opens the list with the keyboard on its first row, from the command palette or a shortcut you give it.

Restoring one re-adopts that shell with its program still going and its recent output replayed, including whatever it printed while it was gone. If no pane has been opened, closed or stashed since, the grid goes back exactly as it was at the close, with the restored pane in its old place; otherwise it takes a free cell like a new pane. With pane motion on, a closed pane fades from its place and a restored one settles into its cell.

Only when its timer runs out is the shell actually killed; opening the list does not extend that deadline. Closing the window or quitting TermHQ ends any shell still counting down, rather than leaving it running where nothing can reach it.

A shell that ends by itself is never parked; there is nothing to restore. Nor is a browser pane: closing one is final, because the undo window exists to hold a shell that is still running and a page has nothing left running to hold.

An editor pane has its own protection instead of an undo window — closing one with unsaved work asks about each file first.

The behavior is configurable in Settings → General:

• how long the undo window lasts, in seconds (default 5)
• whether closing with the pane’s × button also offers undo, or only the keyboard shortcut does
• whether the feature is on at all

Ctrl+Shift+R — Restore last closed terminal — undoes without reaching for the mouse, the same restore as Undo close in the status bar.

Ultra focus

Some terminal programs want chords TermHQ also uses. Ultra focus (Ctrl+Shift+U) hands every keystroke to the terminal, turning off TermHQ’s own shortcuts so a TUI gets them unmodified. See Keyboard shortcuts for exactly what it does and does not take.

Because a mode that swallows the keyboard could trap you, the chord that turns it on always turns it off, and a badge appears in the title bar that can be clicked to leave.