Terminal groups

A terminal group keeps related terminals together on one workbench canvas. A group has a name, a colour and a frame around its terminals. You can move, rename, copy or close all terminals of a group in one step. Each terminal stays a normal window with its own session. Use a group to keep an agent and its helpers in one place.

You make a group by hand from a selection. Or an agent makes a group when it starts a terminal from one of your terminals. See "Groups that agents make" in "Limits and tips".

A terminal group is not a task group in the ToDo panel. See ToDo: the task board.

Where to find it

• Group frame and header — on the canvas of the active workbench, around the terminals of the group. The frame sits behind the terminal windows.
• Selection bar — at the bottom of the canvas, to the right of the Helm button (tooltip "Ask Helm (⌘J)"). It shows only while a terminal of the active workbench is selected.
• Select with the mouse — hold Ctrl (Cmd on macOS) and click a terminal window, a group header, a minimap marker, or a row in the Agents panel.

What you see

• Selected terminal — a terminal window with an accent ring around it.
• Selection bar — a floating pill. From left to right:
  • Count text — for example "2 terminals selected", "1 group selected" or "1 group + 2 terminals selected".
  • Group terminals button (grid icon) — it turns into Merge into one group (merge icon) when the selection holds a group. It stays disabled until two terminals are selected.
  • Copy terminal references button (copy icon).
  • Close selected terminals button (trash icon, turns red when you point at it).
  • Clear selection button (X icon).
• Group frame — a rounded rectangle in the colour of the group, with a light tint inside. It fits the terminals of the group and follows them when they move or change size.
• Group header — the strip along the top of the frame. From left to right:
  • Colour dot — a dot in the colour of the group.
  • Group name field — shows the name. You can type in it.
  • Copy group references button (copy icon).
  • Ungroup button (layers icon).
  • Close entire group button (trash icon, turns red when you point at it).
• Lead badge — a Lead badge in the title bar of one terminal. It shows only in groups that an agent made. The Agents panel also marks it Lead. A group without the badge is a group that you made, or one whose Lead is closed.

How to

Select terminals

Before you start, open a workbench with at least two terminals.

1. Press and hold Ctrl (Cmd on macOS).
2. Click the title bar of the first terminal.
3. Click the title bar of the second terminal.

Result: both windows get an accent ring. The selection bar shows "2 terminals selected". Ctrl+click (Cmd+click) a selected terminal again to remove it.

Select a whole group

Before you start, make sure the workbench has a group.

1. Press and hold Ctrl (Cmd on macOS).
2. Click an empty part of the group header.

Result: every terminal of the group gets an accent ring. The selection bar shows "1 group selected". Ctrl+click (Cmd+click) on any terminal of a group does the same, because a group is always selected as a whole. Ctrl+click the header again to remove the group.

Clear the selection

1. Click Clear selection in the selection bar.

Result: the rings go away and the selection bar disappears.

Create a group

Before you start, select at least two terminals that are not in a group.

1. Click Group terminals in the selection bar.

Result: a frame appears around the terminals. Its name is "Group" and a number (the groups on this workbench plus one). Its colour is the next colour of the cycle. The terminals keep their sizes and their order (left stays left, top stays top) and move closer together. A window that the new frame covers moves aside. The selection clears.

Add terminals to a group

Before you start, select one group and one or more terminals that are not in a group. Use Ctrl+click (Cmd+click) on the group header and on the terminals.

1. Click Merge into one group in the selection bar.

Result: the free terminals join the group that you selected first. Any other selected group merges into it and its frame disappears. The first group keeps its name and colour. The terminals pack closer together. The selection clears.

Add a terminal to a group by dragging

Before you start, find a terminal that is not in a group and a group frame.

1. Press the left mouse button on the title bar of the free terminal.
2. Drag the window until its centre is inside the group frame.
3. Release the mouse button.

Result: the terminal joins the group. The group packs around the new position. The terminal keeps its size.

Remove a terminal from a group

Before you start, find a terminal that is a member of a group.

1. Press the left mouse button on the title bar of the member terminal.
2. Drag the window until its centre is outside the frame of the other members.
3. Release the mouse button.

Result: the terminal leaves the group and stays open. The frame shrinks to the other members. If it was the only member, the group disappears.

Move a group

1. Press the left mouse button on an empty part of the group header. The pointer shows a grab hand.
2. Drag the header.
3. Release the mouse button.

Result: all terminals of the group move together. Their positions inside the group do not change. Ctrl+click (Cmd+click) on the header selects the group and does not drag it.

Rename a group

1. Click the Group name field in the group header.
2. Type the new name.

Result: the group keeps the new name as you type. The Agents panel shows the same name. A blank name is not saved. The old name stays.

Copy references to one group

1. Click Copy group references in the group header.

Result: the clipboard holds one line for the group, then one line for each terminal of the group. Paste the text into an agent prompt to point the agent at the group.

Copy references to the selection

Before you start, select terminals or groups.

1. Click Copy terminal references in the selection bar.

Result: a message shows "Copied" and "· 3 terminal references" (the number of selected terminals). The clipboard holds one block for each fully selected group (a group line, then a line for each member). A line for each remaining terminal follows.

Ungroup the terminals

1. Click Ungroup in the group header.

Result: the frame and the header disappear. All terminals stay open at the same place.

Close all terminals of a group

1. Click Close entire group in the group header.

Result: Orkestra closes every terminal of the group. It does not ask you first. The group disappears.

Close the selected terminals

Before you start, select terminals or groups.

1. Click Close selected terminals in the selection bar.
2. Click Close in the dialog "Close terminals". It asks "Close 3 selected terminals? This cannot be undone."

Result: the terminals close. A message shows "Closed" and "· 3 terminals". A group that loses all its members disappears.

States and messages

• The selection bar appears only when a terminal on the active workbench is selected. Group terminals stays disabled until at least two terminals are selected.
• Close entire group is disabled while Telegram controls one of its terminals. If a bulk close can close only part of the selection, Orkestra closes the others, keeps the controlled terminal open and reports what happened.
• Terminals can be grouped only within one project. A selection across projects is left unchanged.
• Groups and their terminal membership return after restart; their terminals return dormant. The selection itself is cleared.

Limits and tips

• One workbench, one project. A group never spans workbenches or projects. A terminal is in at most one group.
• Plain clicks do not select. Only Ctrl+click (Cmd+click) selects. A plain click works as always.
• Windows keep their sizes. When you group by hand, Orkestra never resizes or reorders your windows. You can still move and resize each member. See Canvas windows.
• Group colour. The colour is automatic and you cannot change it. The colours cycle in this order: emerald, violet, coral, cyan, gold, magenta. The next colour depends on how many groups exist in all projects.
• Tidy windows and the minimap. Tidy windows moves a group as one block. On the minimap, Ctrl+click (Cmd+click) on a terminal marker selects the terminal, and a Ctrl drag moves the selection. See Workbenches and the canvas.
• Agents panel. The panel lists a group as one section with its name and colour. A Ctrl+click (Cmd+click) on a row adds that terminal to the same selection. The panel has its own Group terminals button. It can group terminals from several workbenches of one project and moves them first to the workbench of the first selected terminal. See Agents panel and agent status.
• No group launch. You cannot start a whole group of terminals from the group frame. To start agents for a ToDo task group, see ToDo: the task board. That start opens one terminal for each task. It does not make a terminal group. For single launches, see Starting terminals and agents.
• Title-bar colour. The group colour does not colour the title bars of its members. Only the Lead of an agent-made group gets it (see below). Change a title-bar colour in the Terminal info menu. See The terminal info menu.

Groups that agents make.

• What triggers it. An agent that runs in one of your terminals starts another terminal, or launches a task or a task group, through Orkestra. The new terminal and the terminal of the agent form a group.
• What does not trigger it. A terminal that you open or launch yourself in the app. A terminal that Helm, Telegram or a program outside the app opens. A terminal in another project than the one of the agent.
• First start. The agent terminal is not in a group. Orkestra makes a new group. The agent terminal is the Lead. The new terminal is a child. The group takes the name of the Lead. Its colour is the next colour of the cycle. The title bar of the Lead takes that colour.
• Next starts. The agent terminal leads the group. Each new terminal joins as a child.
• A child starts a terminal. The child leaves its group. It leads a new group with the new terminal. The name is the name of the child, then "←", then the name of the old group.
• A chosen group. An agent can send a new terminal into a named group on its own workbench. The terminal joins as a child. This never changes the agent's own role.
• Layout. The Lead stands alone at the left. The children stand to its right, in columns of up to three, with a wider gap after the Lead. Every member gets the size of the Lead. Windows in the way move aside. Children have no badge.
• Only at the start. Orkestra groups only at the moment of the start. It never moves terminals into groups later. A rename of the Lead or of the group does not change the other name.
• A closed Lead. The group stays. It has no Lead and no badge. Nobody takes over the role.
• No setting. No setting in Settings turns automatic grouping off. To undo a group, click Ungroup in its header.

Related

• Workbenches and the canvas — the canvas, Tidy windows and the minimap.
• Canvas windows: move, resize, dock and focus — the frame of each member window.
• Terminal states, reconnect and history — dormant terminals after a restart.
• Agents panel and agent status — the list of agents, grouped like the canvas.
• ToDo: the task board — task groups, which are not terminal groups.