Projects and workbenches

Workbenches and the canvas

Keep several canvases per project, pan and zoom the view, tidy the windows, and move around with the minimap.

On this page

A workbench is one canvas of a project. A project has one or more workbenches. Use several workbenches to keep windows apart, for example one workbench for each feature. A canvas has no edge. You pan and zoom it to see more or less. Use this page to manage workbench tabs, the canvas view, Tidy windows, the minimap and the placement of new windows.

Where to find it

  • The workbench tabs are in the top bar, right of the project switcher. They show only when a project is selected.
  • Tidy windows and the zoom controls are in the top bar. They sit right of the launch buttons and the reconnect control, and left of the Settings button (the gear).
  • The canvas is the dotted area below the top bar and right of the left sidebar.
  • The minimap floats in the bottom-right corner of the canvas.

What you see

Workbench tabs

  • One tab for each workbench of the project, in the order of creation. Each tab has:
    • a small coloured square. The colour identifies the workbench;
    • the name you gave the workbench, or a small canvas grid icon when the workbench has no name;
    • an ✕ button (tooltip "delete workbench"). It appears when you point at the tab, and only when the project has two or more workbenches.
  • The active tab has a highlighted background and a glowing square.
  • The tooltip of a tab is the workbench name. A workbench without a name has the tooltip "Workbench 1", "Workbench 2" and so on, by position in the strip.
  • The + button (tooltip "new workbench") after the last tab.

Toolbar controls

  • The Tidy windows button (a grid icon). Its tooltip is "Tidy windows — collect and de-overlap them, keeping each window's size".
  • The zoom group, left to right:
    • the − button (tooltip "zoom out");
    • the zoom level, for example "100%";
    • the + button (tooltip "zoom in");
    • the Reset view button.

Canvas

  • A dotted surface. The windows float on it. The window frame is in Canvas windows.
  • On a workbench with no window, a hint: "Empty workbench — use a terminal launch button above, double-click a file in the sidebar, or right-click a task to launch an agent."

Minimap (bottom-right corner, 300 × 190 px)

  • One rectangle for each window. Position and size are scaled down. A very small window still gets a marker of at least 14 × 10 px.
  • A terminal marker has the identity colour of its terminal. That is the title-bar colour you picked, else the worktree colour, else the task group colour. It also has a stripe on its left edge and a status dot at its top-right corner. The dot shows the same status as in the terminal window. The marker edge turns warm (amber) when the terminal waits for your input.
  • Every other window (file, image, HTML page, task, diff, merge, commit, Git console) has a grey, dimmer marker without a dot.
  • The marker of the window in focus has an accent outline. A terminal selected for grouping has an accent ring.
  • The view rectangle: an accent outline with a grip icon inside. It shows the part of the canvas that you see now. Orkestra dims the map outside it.

How to

Add a workbench

  1. Click the + button (tooltip "new workbench") after the last workbench tab.

Result: a new empty workbench opens. It has no name, the view is at 100% zoom, and it takes the first tab colour that no other tab of the project uses.

Switch to another workbench

  1. Click the tab of the workbench.

Result: the canvas of that workbench shows. The tab is highlighted. A window that was in focus leaves focus. See Canvas windows.

Rename a workbench

  1. Double-click the workbench tab.
  2. Type the name in the workbench name field.
  3. Press Enter.

Result: the tab shows the name instead of the grid icon. To remove a name, clear the field and press Enter. The tab then shows the grid icon again. Press Escape instead of Enter to keep the old name.

Close a workbench

  1. Point at the tab of the workbench.
  2. Click the ✕ button (tooltip "delete workbench").
  3. If the Close workbench? dialog opens, click Close workbench. Click Cancel to keep the workbench.

Result: the tab, its windows and its terminal sessions are gone. If it was the active workbench, the first tab in the strip becomes active. The dialog opens only for a workbench with terminal, file or task windows. Any other workbench closes at step 2.

Pan the canvas

  1. Press the left or the middle mouse button on an empty part of the canvas.
  2. Drag the pointer.
  3. Release the button.

Result: the canvas follows the pointer. Orkestra saves the new position when you release.

Zoom with the mouse wheel

  1. Move the pointer over the point you want to zoom toward.
  2. Hold Ctrl.
  3. Turn the mouse wheel. Wheel up zooms in. Wheel down zooms out.

Result: the zoom changes by a factor of 1.1 for each wheel step. The point under the pointer stays in place. The zoom stays between 25% and 250%. This also works when the pointer is over a window.

Zoom with the buttons

  1. Click the + button (tooltip "zoom in") or the − button (tooltip "zoom out") in the zoom group.

Result: the zoom level changes by 10 percentage points. It stops at 25% and at 250%.

Reset the view

  1. Click Reset view in the zoom group.

Result: the zoom returns to 100% and the canvas returns to its start position. No window moves.

Tidy the windows

  1. Click Tidy windows.

Result: Orkestra pulls the windows of the active workbench together and removes all overlap. No window changes its size. A window that was left of another window stays left of it, and a window that was above stays above. Then the view zooms to show all windows. See "Limits and tips" for the details.

Jump to a place with the minimap

  1. Click the point on the minimap that you want to see.

Result: the view centres on that point. The zoom does not change.

Drag the view with the minimap

  1. Press the left mouse button inside the view rectangle on the minimap.
  2. Drag the pointer.
  3. Release the button.

Result: the view rectangle follows the pointer, and the canvas moves with it. The point you grabbed stays under the pointer.

Select a terminal on the minimap

  1. Hold Ctrl (Cmd on macOS).
  2. Click a terminal marker on the minimap.

Result: the terminal joins the selection for grouping. If it was selected, it leaves the selection. A selected terminal has an accent ring. See Terminal groups.

Move windows with the minimap

  1. Hold Ctrl (Cmd on macOS).
  2. Press the left mouse button on a window marker.
  3. Drag the marker. The markers show a preview of the move.
  4. Release the button.

Result: the windows move once, by the matching distance on the canvas. A terminal marker moves all selected terminals together. The terminal you dragged joins the selection, and a whole terminal group moves together. Any other window moves alone. Press Escape before you release to cancel the move. The view does not move.

Hide the minimap

  1. Click the Settings button (the gear) in the top bar.
  2. Click Appearance, under Appearance & Behavior, in the Settings list.
  3. In the Interface group, click Show the canvas minimap to clear its check box.
  4. Click OK.

Result: the minimap disappears on every workbench. To show it again, select the check box again and click OK. See Settings: the window, appearance, terminal, workbench and notifications.

Bring a terminal into view

  1. Open Agents in the left sidebar.
  2. Click the row of the terminal.

Result: the workbench that holds the terminal opens, also when it is in another project. The terminal comes to the front, the view centres on it, and the window flashes. The zoom stays the same. It shrinks only when the window is too big to fit with a margin of 48 px. See Agents panel and agent status.

States and messages

  • Empty workbench means there are no windows; start a terminal, open a file or launch an agent from a task.
  • No project selected and This project has no workbench. are described in Window layout.
  • Removing a workbench that has terminal, file or task windows asks you to confirm. Closing it ends its terminal sessions and discards its windows; the dialog warns that this cannot be undone. A workbench stays open if Orkestra cannot preserve an unsaved file or task description, or cannot close one of its terminals.
  • A text field in a tab means rename mode is active. Minimap not shown means the minimap setting is off or the workbench has no supported window. A dashed outline means the current view covers the map; a small dotted box means the view is outside the mapped area—click the map to return.
  • The zoom percentage is rounded to a whole number and updates for every zoom method.

Limits and tips

  • Keyboard on tabs. Tab moves focus into the strip, to the active tab. Left and Right arrows go to the previous and the next tab and open it. They wrap round at the ends. Home and End go to the first and the last tab. Enter and Space open the focused tab. F2 renames it.
  • Tab colour and order. Orkestra picks the colour. It has eight tab colours. A new tab takes the first colour that the project does not use. When all eight are used, it takes the least used colour. The strip has no control to change a colour or to reorder tabs.
  • At least one workbench. A project always keeps one workbench. A single workbench has no ✕ button.
  • Narrow window. The strip scrolls sideways when the tabs do not fit. It shows no scroll bar.
  • Wheel rules. The canvas reacts to the wheel only with Ctrl held. Without Ctrl, the wheel scrolls the content of the window under the pointer, and does nothing on the empty canvas. Shift does not change this. A two-finger scroll on a trackpad does not pan the canvas. To pan, drag the empty canvas or use the minimap.
  • Terminals that use the mouse. When a terminal program asks for mouse events, that terminal keeps the wheel, also with Ctrl. Zoom with the buttons or point at another place.
  • No keyboard zoom. Orkestra has no key to zoom or pan the canvas. Use the buttons, Ctrl and the wheel, or the minimap.
  • Zoom buttons. The buttons keep the canvas origin fixed on the screen, not the centre of the view. The windows can appear to slide. Ctrl and the wheel zoom around the pointer instead.
  • Reset view. The start position can show an empty part of the canvas when your windows are far away. Use Tidy windows or the minimap to find them.
  • What Tidy windows does.
    • It works on the active workbench and on all window kinds. It does nothing on an empty workbench.
    • It never resizes a window.
    • Windows with less than 240 px between them count as one bunch, and so do chains of such windows. Inside a bunch the gap becomes 24 px. Between bunches the gap becomes 240 px. So bunches that you kept apart stay apart.
    • A terminal group moves as one block. See Terminal groups.
    • The view then fits all windows with a small margin. The zoom does not go above 100% or below 25%. When the windows do not fit even at 25%, the layout starts near the top-left corner of the view.
  • Where new windows start. A new window starts at a point 460 px from the left and 200 px from the top of the visible canvas. The point follows pan and zoom, so a new window opens in the part you see. For windows opened from tasks or from the sidebar, the point shifts by 32 px right and 32 px down for each open window. The shift repeats after eight steps. A terminal from the launch buttons has no shift.
  • A crowded canvas. Orkestra keeps at least 16 px between a new window and every other window or group frame. If the start point is too near another window, Orkestra uses the nearest free point. It moves no other window for this. On a crowded canvas that point can be outside the visible part. Find the window with the minimap or the Agents panel.
  • Window size and focus. The size of a new window is a setting. See Settings: the window, appearance, terminal, workbench and notifications. Some windows open in focus. See Canvas windows. A terminal group that grows pushes the windows in its way. See Terminal groups.
  • Worktree drop. You can drop a worktree row from the left sidebar on the canvas. A terminal opens at the drop point. See Worktrees.
  • Minimap position. The minimap stays in the bottom-right corner. You cannot move it or change its size. The only way to hide it is the setting.
  • Minimap map. The map shows all windows of the workbench, not only the view. So the map stays still when you pan. Only the view rectangle moves. Navigation on the minimap never changes the zoom.
  • Minimap marker moves. Ctrl (Cmd on macOS) with a click or a drag works only on a marker. A very small marker is easy to hit: Orkestra counts a marker as at least 12 px wide and high. Where markers overlap, the one on top wins. A press that moves 4 px or less is a click. A longer press is a drag. A drag that Orkestra cancels, for example with Escape, restores the selection that you had before.
  • Minimap tour. The Minimap navigation tour shows navigation, marker selection and moves on the minimap, also for terminal groups that already exist. It moves nothing by itself. Start it with Show me on the Move around with the minimap item of the Getting started checklist, or in Settings, System check, Tours. See First-run setup, Getting started and tours.
  • Next waiting agent. Ctrl+Shift+A (Cmd+Shift+A on macOS) brings the next agent that waits for you into view. See Agents panel and agent status.
  • Reveal. Revealing a terminal always leaves focus mode. When you reveal a terminal from an approval request, Orkestra opens its workbench and brings the window to the front, but the view does not move. See Approvals.
  • Saved state. Orkestra saves the windows of each workbench and the view of each workbench (pan and zoom) as they change. It restores them when you start Orkestra again. Terminals come back without a live session. See Terminal states, reconnect and history.
  • Terminals outside the view. Orkestra draws only the terminals near the visible area. The other terminals keep running, and Orkestra keeps their output.
  • Launch and reconnect. The launch buttons are in Starting terminals and agents. The reconnect control is in Terminal states, reconnect and history.