Projects and workbenches

Canvas windows: move, resize, dock and focus

Move, resize, snap together, enlarge, rename and close any window on the workbench canvas.

On this page

Every window on a workbench canvas has the same frame. This is true for terminals, files, images, HTML pages, tasks, diffs, merges, commits and the Git console. The frame lets you place a window, snap windows together into split layouts, enlarge one window to work in it, rename it and close it. This guide covers the shared frame. See the chapter for each window kind for details specific to it (see "Window kinds" below).

Where to find it

The windows float on the canvas of the active workbench. See Workbenches and the canvas for the canvas itself, the zoom controls and the Tidy windows button. Each window has a title bar along its top edge. You open a window from the left sidebar, from the launch buttons or from a task. The chapter of each window kind explains how.

Window kinds and their chapters:

What you see

Title bar, from left to right:

  • Status indicator — a small dot or icon at the left edge. Its meaning depends on the window kind (for example the agent state of a terminal, or the type icon of a task).

  • Window name — the name you set. If you set none, it shows a default title: the agent or task title of a terminal, the file name of a file, the task title of a task window, or "Git console".

    • Hover a terminal name to see the full name, the recap and the hint "Double-click or press Enter to rename".
    • Hover a file window name to see the full file path.

  • Controls next to the name — extra controls of the window kind, such as the Terminal info button of a terminal. See the chapter of the kind.

  • Kind controls and badges — extra buttons, pills or badges on the right side, depending on the kind. See the chapter of the kind.

  • Reload button — a circular-arrows button, shown on terminal windows only (tooltip "Reload terminal (restart agent session)"). See Terminal windows.

  • Focus button — an icon button with four corner brackets (tooltip "Focus (≈80% of screen)").

  • Close button — an X icon button. The tooltip names the window kind:

    Window Close tooltip
    Terminal "Close terminal"
    File "Close file"
    Image "Close image"
    HTML page "Close page"
    Task "Close task window"
    Diff "Close diff"
    Merge "Close merge"
    Commit "Close commit"
    Git console "Close console"

Below the title bar is the window body. The kind decides what the body shows.

Around the window:

  • Edges and corners — you drag them to resize the window.
  • Dock preview — a see-through rectangle in the accent colour. It appears while you drag a window close to another window. It shows where the window will land.
  • Divider — a thin strip between two windows that sit edge to edge. It is invisible until you point at it. Then it takes the accent colour.

Title-bar colour:

  • A terminal title bar can have a colour. The colour is one you pick, or the colour of the worktree or task group the terminal belongs to.
  • All other window kinds have a plain title bar. The frame has no colour picker. A terminal colour is chosen in the Terminal info menu. See The terminal info menu.

Focus mode (after you click the Focus button):

  • Backdrop — the canvas goes dim and slightly blurred.
  • Focused window — one window, centred, at 80% of the screen width and 80% of the screen height. It has an accent-coloured border.
  • Focus title bar — the status indicator, the window name, the controls of the kind, then two buttons on the right: Exit focus (Esc) (four corner brackets pointing inward) and Close window (X).

How to

Move a window

  1. Press and hold the mouse button on the title bar of the window. Do not press on a button.
  2. Drag the window to the new place.
  3. Release the mouse button.

Result: the window stays where you released it. Orkestra saves the new place. If the window was close to another window, it snaps to it instead (see "Dock a window next to another window").

Resize a window

  1. Point at an edge or a corner of the window.
  2. Press and hold the mouse button.
  3. Drag the edge or corner.
  4. Release the mouse button.

Result: the window has the new size. Dragging a top or left edge also moves the window. The window cannot get smaller than the minimum size of its kind (see "Limits and tips").

Dock a window next to another window

  1. Press and hold the mouse button on the title bar of the window you want to dock.
  2. Drag the window until one of its edges is close to a facing edge of another window.
  3. Look for the see-through dock preview. It shows where the window will land and how large it will be.
  4. Release the mouse button while the dock preview is visible.

Result: the window snaps next to the other window, with a small gap of 8 px between them. A divider appears in the gap. If you dock left or right, the window gets the height and the top position of the other window and keeps its own width. If you dock top or bottom, it gets the width and the left position of the other window and keeps its own height. The other window does not change.

Resize two docked windows together

  1. Point at the divider between the two windows. The pointer changes to a resize pointer and the divider shows the accent colour.
  2. Press and hold the mouse button.
  3. Drag the divider. Drag sideways for a vertical divider and up or down for a horizontal divider.
  4. Release the mouse button.

Result: one window grows and the other shrinks by the same amount. The outer edges stay where they are. Neither window gets smaller than its minimum size.

Undock a window

  1. Press and hold the mouse button on the title bar of the docked window.
  2. Drag the window away from the other window.
  3. Release the mouse button away from any other window edge.

Result: the window moves freely. The divider is gone because the two windows no longer sit edge to edge.

Bring a window to the front

  1. Click anywhere in the window. A click on the title bar, the body or a button all count.

Result: the window moves above all other windows on the canvas, whatever their kind.

Focus a window

  1. Click the Focus (≈80% of screen) button in the title bar of the window.

Another way: double-click an empty part of the title bar. Do not double-click the name or a button.

Result: the window opens large in the middle of the screen, over a dim backdrop. Its place on the canvas is empty while it is in focus.

Leave focus

  1. Click the Exit focus (Esc) button in the title bar of the focused window.

Other ways: press Esc, or click the dim backdrop outside the window. While the cursor is in a terminal, the terminal takes Esc, so click the button or the backdrop instead.

Result: the window goes back to its place on the canvas. Its place and size are unchanged. If the window is a terminal, the cursor is back in it, so you can type at once.

Rename a window

  1. Double-click the window name in the title bar. (You can also move to the name with the keyboard and press Enter or Space.)
  2. Type the new name in the field. The field is limited to 320 characters.
  3. Press Enter.

Result: the title bar shows the new name. To go back to the default title, clear the field and press Enter. Press Esc to cancel without a change. Clicking outside the field saves the name, as Enter does.

In a task window the name is the name of the task. The new name shows on the ToDo board too, and clearing the field gives the name derived from the description. See Task window.

Close a window

  1. Click the Close button (X) in the title bar. Its tooltip names the kind, for example "Close terminal".

Result: the window leaves the canvas. Some kinds ask or check first. For example, a file window with unsaved changes asks what to do. See the chapter of the kind.

States and messages

  • Dock preview appears when a dragged window is close enough to dock; without it, the window will stay where you release it. Dock dividers hide during a drag and return afterward.
  • An accent ring means a terminal is selected for grouping. A brief accent flash marks a terminal Orkestra just brought into view.
  • If a person is using the terminal through Telegram, Reload and Close are disabled until you take back control.

Limits and tips

  • Docking is automatic. No setting or key turns it off. Dropping a window away from other windows leaves it free.
  • Docking has a range of 16 screen pixels. The range is the same at every zoom level.
  • Two windows dock only if their facing edges overlap along at least 24 px. Windows that only touch at a corner do not dock.
  • Docking works between all window kinds. A terminal can dock to a file window, and so on.
  • Orkestra saves only the positions and sizes. It does not save a link between docked windows. Moving a window does not move its neighbours.
  • A divider also appears when you place two windows edge to edge by hand, with a gap of 8 px or less.
  • A window in focus has no dividers and does not take part in docking.
  • Minimum sizes, width × height in px: terminal 240 × 160; file 320 × 200; image 280 × 220; HTML page 320 × 240; task 380 × 320; diff 360 × 220; merge 380 × 260; commit 380 × 240; Git console 360 × 200. There is no maximum.
  • All windows share one stack. A click always raises the window above every other kind.
  • Only one window can be in focus. Switching to another project leaves focus.
  • In focus mode you cannot move, resize or dock the window. The terminal Reload button is not shown. A terminal shows a colour you picked, but not the colour of its worktree or task group.
  • Esc first closes an open menu or popup. Press Esc again to leave focus.
  • When you leave focus, Orkestra first applies the edit that is still open in a Markdown editor. See Markdown documents.
  • A window you open from the left sidebar opens already in focus. This holds for files, images, HTML pages, tasks, diffs, merges, commits and the Git console. Leave focus to see it on the canvas.
  • Focusing a sleeping terminal wakes it. Focusing a dormant terminal restarts its session. See Terminal states, reconnect and history.
  • Ctrl+click (Cmd+click on macOS) on a terminal selects it for grouping. See Terminal groups.
  • The size a new window opens at is a setting: open Settings, then Workbench, then the New window size group. It has Size multiplier and Base terminal size (px). See Settings: the window, appearance, terminal, workbench and notifications.
  • The Tidy windows button and the zoom controls are in Workbenches and the canvas.