Terminals, Panes & Profiles
The four nested objects that make up every TermFlow window — windows, tabs, panes, and the terminals inside them — plus the shell profiles that decide what each terminal runs.
The containment model
TermFlow arranges everything into a simple hierarchy. A window holds one or more tabs. Each tab owns a split-pane tree. Every leaf of that tree is a pane, and each pane hosts exactly one terminal — a single PTY (pseudo-terminal) running a shell.
That one-pane-to-one-terminal rule is worth internalizing: when an agent or the API talks about a "terminal", it means one live shell process bound to one pane, not a tab and not a window.
Terminals
A terminal is one PTY. TermFlow gives it a stable id and records the tabId of the tab it belongs to, so callers can tell which terminals share a tab. The create_terminal MCP tool and POST /api/terminals both return this id, and get_terminal_detail includes the tabId. An agent running inside a TermFlow terminal can refer to its own terminal with the shorthand "me" instead of looking up the id.
Because a pane and a terminal are one-to-one, "close the pane", "close the terminal", and "kill this PTY" are the same action.
Panes and the split tree
A tab starts as a single pane. Splitting it turns that pane into an internal node with two children, and you can keep splitting — the result is a recursive binary split tree, so any pane can be divided horizontally or vertically to any depth. Dragging a divider re-balances its two children (each side stays between 10% and 90%).
When you split a pane, the new terminal starts in the current working directory of the pane you split from — not the profile's configured start directory. Change into a project folder, split, and the new shell is already there.
Panes are portable. You can drag a pane (or a whole tab) out of the window to hand its live PTY over to a new window — the shell keeps running; it is not respawned. See Split panes and Windows and tear-off for the full mechanics.
Shell profiles
A shell profile decides which shell a new terminal runs. TermFlow detects the shells installed on your system and offers them as profiles, so on Windows you might see PowerShell and WSL, and on macOS or Linux you'll see zsh, bash, and so on.
When you open a new tab, you pick a profile; one profile is marked as the default (badged in the picker) and is used when you don't choose. Each profile also has a per-profile Start In Directory — the working directory a fresh terminal opens in. Both the default and the start directory are configured under Settings → Shell Profiles.
Under the hood a profile carries a name, the shell's executable path, launch arguments, environment overrides, an optional working directory, and flags for whether it's the default or a custom (user-created) profile.
An honest note: The start directory only applies to terminals opened fresh from a profile. Panes created by splitting deliberately ignore it and inherit the parent pane's live CWD instead — the two behaviors are intentional, not a conflict.
Next steps
- Shell profiles — create, edit, and set defaults in day-to-day use.
- The MCP server — how agents create and address terminals by
id(or"me").