Tutorial

Organize your workspace

A terminal you actually live in isn't one window — it's a layout. In this walkthrough you'll turn a single shell into a workspace: tabs per project, splits per task, saved tile layouts you snap into place, sidebars for navigation, and a few power moves — broadcast typing, read-only panes, tearing a tab onto a second display — that pay off the moment you're running more than one thing at once. Everything here happens live inside one window.

1. Open a tab per project

A tab is a workspace of one or more panes. Open a fresh one with ⌘T (new_tab), jump straight to a tab by index with ⌘1 through ⌘9 (goto_tab:N), and walk the row with ⌘⇧] for the next tab and ⌘⇧[ for the previous. To reorder the active tab, bind move_tab:DELTA — a positive delta shifts it right, a negative one left. Close the current tab with ⌘⌥W (close_tab).

Each tab titles itself after the focused pane's working directory, and when that directory is a git repository the current branch is shown alongside it — so a glance at the tab bar tells you which project and which branch you're on. Pin a fixed label to the active tab with change_tab_title, and add the tab-title-show-host config option to keep the user@host prefix in the title (handy over SSH).

2. Split a tab into panes

Every pane is a full, independent shell with its own process, scrollback, and working directory. Inside a tab, split the focused pane to make room for another: split to the right with ⌘D (new_split:right) and downward with ⌘⇧D (new_split:down). The full set is new_split:left|right|up|down, and splits are recursive — any pane can itself be split — so you can nest a column of logs beside your editor or build a 2×2 grid of servers.

Move focus directionally with ⌘⌥ plus an arrow key (goto_split:up|down|left|right), which jumps to the pane in that direction; goto_split:next and goto_split:previous cycle through every pane in order. Resize by dragging a divider with the mouse or nudge it from the keyboard with resize_split:DIR. Press zoom_split to temporarily maximize the focused pane so it fills the whole tab — it's a toggle, so the same binding restores the split — and equalize_splits resets every divider to an even 50/50.

Whichever pane isn't focused dims slightly so the active shell always stands out. Tune how much with the unfocused-split-opacity config option.

3. Snap panes into a tile layout

Splitting one pane at a time is fine, but when you know the shape you want, a tile layout arranges several panes in a single step. Sinclair ships a set of presets:

• Two Columns and Three Columns — side-by-side panes
• Two Rows — stacked top and bottom
• Grid (4) — a 2×2 grid
• Main + Bottom Row — a large pane over a wide row
• Main + Right Stack — a large pane beside a narrow stack

Apply any preset from the Layouts sidebar panel or the Workspace menu — both invoke tile:LAYOUT_ID. Built an arrangement by hand that you want to keep? Run save_layout: it captures the current tab's split tree as a named custom layout, stored under ~/.config/sinclair/layouts/. Saved layouts then appear alongside the built-in presets, ready to re-apply in any tab.

4. Reach everything from the sidebars

Sinclair has VS Code-style drawers on the left and right edges, each fronted by an activity bar of icons. Toggle a side with sidebar:SIDE[:PANEL] — for example sidebar:left opens the left drawer, and sidebar:right:relay opens the right drawer directly to the Relay panel. Triggering the action for the panel that's already active collapses the drawer, so the same binding flips it open and shut.

The built-in panels are:

5. Type into every pane at once

Toggle broadcast input with ⌘⇧B (toggle_broadcast) and everything you type is mirrored to every pane in the active tab, with a floating indicator to remind you it's on. It's the fast way to run the same command across a row of splits — restart a fleet of servers, tail several logs at once, or set the same shell option everywhere.

6. Lock a pane read-only

toggle_read_only locks a pane against input without closing it — useful for a long-running process or a log you want to watch without fat-fingering a keystroke into it. Re-running the action unlocks it. Pair it with broadcast input above and you can keep a monitoring pane immune to the command you're fanning out everywhere else.

7. Tear a tab into its own window

When one window gets crowded, drag a tab out of the tab bar and release it outside the window. Sinclair re-homes that pane into a fresh window — the live shell keeps running, so nothing is restarted or lost. It's the quickest way to move a session onto a second display, or to split one busy window into two.

8. Pick up where you left off

Turn on the session-restore config option and Sinclair reopens the previous window's tabs, splits, and working directories the next time it launches, so you resume exactly where you stopped. A pane that was running a coding agent is remembered as one: on restore it relaunches the agent — resumed, reloading its own session rather than starting cold where the provider supports it — instead of dropping to a bare shell. New tabs and splits already open in the focused pane's current directory — that's window-inherit-working-directory, on by default — keeping related shells rooted in the same project.

// ~/.config/sinclair/settings.json
{
  "session-restore": true      // reopen tabs & splits on next launch
}

9. Keep a shell one keystroke away

The quick terminal is a Quake-style drop-down pane that slides in over your screen and tucks away again. Toggle it with ⌘⌥T (toggle_quick_terminal) for a throwaway shell that's always available without disturbing your layout — check a path, kick off a command, then dismiss it and you're back exactly where you were.

10. Keep notes beside your work

Notes is a built-in markdown-vault surface. Open it from File → Notes or with the default ⌘⌥N binding (the notes action). It keeps plain-markdown notes in a side surface that lives alongside your terminal — a scratchpad for the command you'll need again, the token you're about to paste, or the plan for the branch you're on.

Where to next