Appearance
Window, Tab and Split
Otty's workspace is built from three nested levels. Knowing how they relate makes the rest of this section — tabs, splits, drag-and-drop — easy to reason about.
window
├── tab
│ └── pane (terminal)
├── tab
│ └── pane (folder)
└── tab
└── split
├── pane (terminal)
└── pane (file)A pane is the leaf at the bottom of every branch — the content you actually interact with (a terminal, file, folder, or URL). Windows, tabs and splits are the containers that hold them.
Window
A window is a top-level OS window. It owns the title bar, the tab sidebar (or horizontal tab bar), and all the tabs inside it. You can run as many windows as you like — across multiple displays or Spaces.
Details Panel
You can hover on window title and click toggle details panel button to toggle details panel, to see current folder content, git status, processes, and command history or file outline. For more information about details, please see Details Panel.
Rename Title
The title bar shows the active tab's name, which by default tracks the running program via OSC 0 / OSC 2 sequences (most shells emit these from a precmd hook). To pin a fixed title — or prepend a prefix to the dynamic one — rename the active tab; see Rename Title under Tab below. Switching tabs updates the window title to match.
Window Resize and Default Window Size
Drag any window edge or corner to resize; the terminal grid reflows to fit. How a new window is sized is set by window-size (Settings → Appearance):
| Value | Behavior |
|---|---|
remember (default) | Reopen at the size and position of the last window you closed. |
grid | Size the grid to an exact cell count — window-cols × window-rows (default 80 × 24) at the active font's metrics. Window chrome is added on top so the grid lands at exactly that many cells. |
frame | Use a literal pixel content rect — window-width-px × window-height-px (default 1000 × 600). The grid is whatever fits after chrome. |
ini
window-size = grid
window-cols = 120
window-rows = 40Pin Window
View → Pin Window keeps the current window floating above all other apps' windows, so a log or monitor stays visible while you work elsewhere. When pinned, a pin button appears in the title bar — click it to unpin (or run Pin Window / Unpin Window from the Command Palette).
Watch Tasks in Window
If you just want to watch task running status in a window, compared with Pin Window, you could also set notification when the task is finished, or toggle Picture in Picture.
Picture in Picture
View → Picture in Picture pops a pane out into a system floating window that stays on top even when Otty is in the background or on another Space. Two modes:
| Mode | Behavior |
|---|---|
| Current Pane | Pops out the pane you choose; it keeps showing that pane regardless of focus. |
| Follow Active Pane | The floating window always mirrors whichever pane is currently active. |
Run them from the View menu, or from the Command Palette (pip). Close it with Close Picture in Picture or the window's standard PiP controls.
Tab
Otty's default layout is a vertical tab sidebar on the left of every window. Each tab is an independent terminal session. A horizontal tab bar (window-layout = tabs-top or tabs-bottom) is also available — see Horizontal tab bar below.
Horizontal Tab Bar
You can switch window layout from vertical tab sidebar, tabs bar on top and tabs bar on bottom from Settings → Appearance → Layout.
The switching, reordering, and labeling rules above apply identically in horizontal mode.
Sort, Group and Divide Tabs
(vertical tabs panel only — the horizontal bar keeps a flat strip)
Click the filter button at the top of the tabs panel — or right-click an empty area of the panel — to open a menu with three sections:
Group — break the list into collapsible sections:
| Mode | Behavior |
|---|---|
| No Grouping (default) | One flat list. |
| By Project | Group tabs by their git repository / project root. |
| By Date | Group by when the tab was last active (Today, Yesterday, …). |
Order — how tabs sort within a group:
| Mode | Behavior |
|---|---|
| Created Time (default) | Oldest-opened first. |
| Updated Time | Most-recently-active first. |
| Manual | Set implicitly the moment you drag a tab to reorder — the menu deselects the time orders. |
Divider — when grouping is off, insert your own labeled separators to hand-group unrelated sessions. Choose Insert Divider from the menu, or right-click between two tabs. A divider can be renamed, dragged, and deleted like a tab; Remove All Dividers clears them at once. (Dividers are disabled while a Group mode is active, since the sections come from the grouping rule instead.)
Group, order, and collapsed sections are remembered per window across session recovery.
New Tab Position
Control where a freshly-opened tab lands with new-tab-position (Settings → Appearance → New Tab Position):
| Value | Behavior |
|---|---|
auto (default) | Context-aware. Empty tabs (⌘T) land at the end of the current section — just before the next divider, or the end of the strip. Tabs opened with content (a file pane, an agent history view) drop in right after the current tab, keeping the related tab nearby. |
end | Always appended to the end of the tab list. |
after-current | Always inserted directly after the active tab. |
Auto Hide Tabs Panel / Bar
Otty can hide the tab strip when you don't need it. The policy splits by layout — auto-hide-tabs-panel governs the sidebar (sidebar-left), auto-hide-tab-bar governs the horizontal bar (tabs-top / tabs-bottom) — but both take the same three values:
| Value | Behavior |
|---|---|
default (default) | No automatic hiding — you control it with the show/hide toggle. A new window opens with the same state as the window you opened it from, so hiding the panel "sticks" as you spawn more windows. |
always | Shown by default. New windows always open with it visible, and switching to this mode reveals it everywhere. You can still hide it per-window with the toggle; opening or closing tabs won't force it back. |
auto | Driven by tab count — hidden with a single tab, shown once you have two or more, updating as tabs open and close. |
The show/hide toggle is per-window: closing the panel in one window never hides it in another. Each window also restores its own panel state across a restart via session recovery, independent of the policy above.
Set them under Settings → Appearance, or in your config file:
ini
auto-hide-tabs-panel = auto
auto-hide-tab-bar = autoRename Title
By default a tab's name tracks the running program via OSC 0 / OSC 2 sequences. To set your own, right-click the tab and choose Rename Tab... (also in the Command Palette and the Shell menu). The dialog offers two modes:
- Name — a fixed title that replaces the dynamic one.
- Prefix — text prepended to the dynamic title, so it stays informative while still updating (e.g.
prod:in front of the live program name).
Leave the Name field empty (or hit the reset button) to drop back to the automatic title. A renamed tab keeps its title across session recovery.
Tab Badge
A badge is the small status indicator Otty draws on a tab so you can see what a session is doing without switching to it — useful when a long command or an agent is running in a background tab. Badges update automatically from what the tab is running:
| Badge | Meaning |
|---|---|
| Spinner | The session is busy — a long-running command, or OSC 9;4;1 progress. |
| Checkmark | A command just finished (shown briefly, then clears). |
| Accent dot | A command exited successfully (0) in a tab you're not looking at. |
| Error triangle | A command exited with a non-zero status. |
| Hand | An agent (e.g. Claude Code) is waiting for your input. |
| Coffee cup | caffeinate is keeping the system awake for this tab. |
| Shield | A sudo / su session is active in this tab. |
| Devices | The session is running on a remote host via SSH |
You can config whether to display the related badge from Settings → Shell → Tab Badge, or from menubar, context menu and titlebar dropdown per-tab individually.
You could use otty watch <YOUR COMMAND> to wrap a command, so Spinner, Checkmark, Error triangle badge and notification will be displayed based on the command running status.
To dismiss a badge by hand, right-click the tab and choose Clear Badge. The active tab never shows the success dot or completion checkmark — they only mark unattended activity — but the spinner, awaiting-input, caffeinate, and sudo badges always show, since they reflect ongoing state.
Split Panes
A split divides a single tab into multiple panes, side-by-side or stacked.
Rearranging Splits
Otty's drag-and-drop is more flexible than Ghostty's. In Ghostty a pane can only swap with a neighbor, so a layout like moving the top-left pane to become a full-height column down the right edge simply isn't reachable by dragging. Otty drops a pane onto any edge of a target — the four edges map to split above / below / left / right of that pane — and resolves the result against the whole tab, so the same drag can turn a 2×2 grid into a full-height side column. See Drag and Drop for how drop zones map to the resulting layout.
Resize Splits
Drag any divider between two panes to resize them. To resize from the keyboard, focus a pane and nudge its divider with ⌘⌃⇧ + an arrow key — ⌘⌃⇧→ grows toward the right, ⌘⌃⇧↓ toward the bottom, and so on. To even out a lopsided layout, run Equalize Splits (⌘⌃=) and every pane in the tab springs back to an equal share.
Quickly Auto Layout
You can double click on the border of split views to get all panes resized to similar size.
Switch to Split Pane
Click any pane to focus it, or move focus from the keyboard:
⌘]/⌘[— cycle to the next / previous pane in the tab.⌘⌃←⌘⌃→⌘⌃↑⌘⌃↓— move focus to the pane in that direction.
The focused pane carries a subtle highlight in its toolbar, and pane-scoped shortcuts (⌘F, scrolling, paste) route to it. When a tab has only one pane, the cycle shortcuts pass through so they stay free for other uses.
Open and Close Views
Open Options
A new view's starting directory is controlled per scope, so a new split can inherit your current location while a brand-new window starts at $HOME:
Same as Current Tab (inherit) reuses the working directory of the currently focused pane; Home (home) starts at $HOME. The global working-directory key sets a fallback for all of them and also accepts an absolute path. Where a new tab is inserted in the list is a separate setting — see New Tab Position above.
Close Confirm
To avoid losing work, Otty can prompt before closing. Two independent keys (Settings → General):
- Running Process (
process) — only prompt when a child process other than the shell is still running (e.g. an editor, a server, ansshsession). - Always (
always) — always prompt. - Multiple Tabs (
multiple_tabs) (window only) — prompt only when the window holds more than one tab.
Reopen last closed
Closed a tab by mistake? Press ⇧⌘T to bring it back. The recently-closed list is a stack, so pressing it repeatedly walks back through the tabs you closed, most-recent first — each restored with its working directory and title. The list persists across restarts and crashes, so a reopened tab also recovers its content where possible; see Session Recovery.
Shortcuts
| View | Open | Close |
|---|---|---|
| Pane | ⌘D right · ⌘⌥D left · ⌘⇧D down · ⌘⌥⇧D up | ⌘W |
| Tab | ⌘T | ⌘W |
| Window | ⌘N | ⇧⌘W |
⌘W cascades: it closes the focused pane first; once that's the tab's last pane it closes the tab; once that's the window's last tab it closes the window. Reopen the last closed tab with ⇧⌘T.
To open a non-terminal view — a file, folder, or URL — drop it onto a pane edge (see Drag and Drop) or run otty view <file> / otty open <dir-or-url> from the shell. All shortcuts above are customizable under Settings → Keybindings (reference).
Save and Restore Layouts
Press ⌘S (File → Save…) to save the current layout as a Recipe — a reusable snapshot of your tabs, panes, and working directories. Choose a scope in the dialog (Current Tab, Current Window, or just a list of Commands) and a content level:
| Content level | What's stored |
|---|---|
| Layout Only | The pane tree and each pane's working directory. |
| Include Scrollback | The above, plus each pane's scrollback, restored on open. |
| Include Commands (replay on open) | The above, plus the commands to re-run when the recipe opens. |
Pick Include Commands when you want Otty to rebuild a working session, not just an empty layout — e.g. a terminal on the left, yazi running in the bottom pane, and lazygit on the right. Opening the recipe recreates the splits and replays those commands into the matching panes.
Restore a saved layout from File → Open Recipe…. See Recipes for editing the command list, per-recipe shortcuts, and sharing recipes as .ottyrecipe files.
Switch to Tab / Pane
Jump straight to a tab by index with ⌘1–⌘9, or step through them with ⌘⇧] / ⌘⇧[. ⌘⇧U jumps to the next tab carrying an unread badge — a finished command, an error, or an agent awaiting input — wrapping around the list.
To search across every tab and pane (plus recent files and folders) instead of stepping one at a time, open the fuzzy switcher with ⌘⇧O — see Open Quickly. Any command on this page is also reachable by name from the Command Palette (⌘⇧P).
Within a tab, move between split panes with ⌘] / ⌘[ or the directional ⌘⌃ + arrow keys — see Switch to Split Pane above.
Shortcut Keys
Every binding below is the default and fully customizable under Settings → Keybindings — see the Keybindings Reference.
Window
| Action | Default |
|---|---|
| New window | ⌘N |
| Close window | ⌘⇧W |
| Minimize | ⌘M |
| Toggle full screen | ⌘⌃F |
Tab
| Action | Default |
|---|---|
| New tab | ⌘T |
| Close tab / pane | ⌘W |
| Reopen last closed | ⌘⇧T |
| Next / previous tab | ⌘⇧] / ⌘⇧[ |
| Go to tab 1–9 | ⌘1–⌘9 |
| Jump to unread tab | ⌘⇧U |
| Toggle tabs panel | ⌘⇧L |
| Toggle details panel | ⌘⇧R |
Pane
| Action | Default |
|---|---|
| Split right / left | ⌘D / ⌘⌥D |
| Split down / up | ⌘⇧D / ⌘⌥⇧D |
| Focus next / previous pane | ⌘] / ⌘[ |
| Focus pane by direction | ⌘⌃← ⌘⌃→ ⌘⌃↑ ⌘⌃↓ |
| Move divider | ⌘⌃⇧← ⌘⌃⇧→ ⌘⌃⇧↑ ⌘⌃⇧↓ |
| Equalize splits | ⌘⌃= |
See also
- Drag and Drop — how drop targets map to layout.
- Files and Links — file panes, folder panes, and clickable paths.
- Open Quickly — fuzzy-jump across tabs, panes, and recent items.