The window

First launch

• If no daemon is running, the window opens one project with one tab and one pane running the shell.
  • If you start it in a directory other than your home directory, that directory becomes the project, and the project is named after it.
  • If you start it from a launcher, it starts in the home directory (on a Mac, in /). The project then has no root and gets a generated two-word name such as amber-fjord.
  • A pane in a project with no root, and with no directory set for the pane, starts in the home directory.
• If a daemon is already running, the window shows what the daemon has.
• The window opens at 1200×800, centred. It doesn't remember its size or position.
• Each insensical process has one window. Two processes give you two windows on the same daemon; see Two windows.
• On Linux, the window asks the desktop's settings portal whether the desktop is dark before it opens, so it doesn't open light and then turn dark. If the desktop has no portal, or the portal doesn't answer within half a second, the window uses the toolkit's answer, and you might see a flash of the other appearance.

Parts

• Sidebar, on the left, 248 pixels wide: a row of tools, a field, then the project tree. It's shown with tabs = "sidebar".
• Top bar, shown with tabs = "top": the sidebar button, the project's name, the current project's tabs, and a + for a new tab. On the right: a settings problem if there is one, the update notice if there is one, the count of panes that need you, and a count and switch for floating panes when the tab has any. The top bar also shows the notice about agents that don't report yet (Agents).
• The tab's area: tiled panes with dividers between them, and floating panes above them.
• Dock, at the bottom: shown only while the tab has minimized panes.

When this manual says something is shown "in the top bar" (a settings problem, the update notice, the notice about agents, the count of panes that need you, the switch for floating panes, + for a new tab), that's where it is with tabs = "top". With tabs down the side, the same things are at the top and bottom of the sidebar.

Every button is a glyph. Hover over one to see what it does and, where a command does the same thing, that command's keys in the current keymap. A pane's header buttons show their keys on the focused pane only, and a tab's close button on the front tab only, because those are what the keys act on.

Tabs run along the top or down the side, never both. The tabs setting chooses which. Press Ctrl+Shift+B to hide them, and again to show them in the same place.

• tabs = "sidebar", the default: the sidebar lists every tab of every project, so it suits watching work spread across several projects. There's no top bar. Everything the top bar holds besides tabs is at the top of the sidebar: the count of panes that need you, the switch for floating panes, and + for a new tab. A settings problem, the notice about agents and the update notice are at the bottom, when there are any.
• tabs = "top": the top bar shows only the current project's tabs, which suits working in one project. There's no sidebar.
• When hidden, neither is shown and the panes get the whole window. The count of panes that need you and the notices are then off screen. Ctrl+Shift+A still goes to the pane that needs you, and the palette still lists them.
• The window opens with tabs shown. It doesn't remember that you hid them.

What resizes terminals and what does not

Showing or hiding the sidebar, the dock appearing or disappearing, and hiding pane headers all change how much room terminals have, so the terminals are resized. Changing the sidebar, pane-header, density or pane-gap setting does the same. These count as you changing the layout.

Nothing else that covers terminals resizes them: the palette, the overview, search, zoom, the leader's panel and the restart question.

What the window does not remember

The window doesn't remember its size and position, which sidebar rows are folded, or whether the sidebar is shown from one launch to the next.

Two windows

The design assumes one window. If two windows share one daemon, or a window and isc attach, each resizes a shared pane to its own size. The last one to ask wins, and the other shows a pane that doesn't fit.

Appearance

• The UI around the terminals uses the system's own proportional font at 13 pixels, whatever font-size is. On Linux that's the family fontconfig gives for system-ui, looked up once when the application starts. Use interface-font to name another. If you name the terminal's font, the UI uses the terminal's typeface.
• Icons in the UI are glyphs from the terminal's font. If your font-family isn't a Nerd Font, they show as empty boxes.
• density = "comfortable", the default, draws each pane as a rounded card with space around it. compact puts panes edge to edge with a hairline between them.
• pane-gap sets the space between panes directly, in pixels from 0 to 40. If you leave it out, it's 6 when comfortable and 0 when compact.
• The focused pane has an accent-coloured border. Unfocused panes aren't dimmed.
• Only two things are animated: a blinking cursor, and the spinning mark of a pane that's working.
• A state is never shown by colour alone: each has a mark and a word.
• Terminal content isn't exposed to screen readers.