Terminals and agents

Agents panel and agent status

See every terminal of every project with its status, jump to one on the canvas, act on many at once, and learn what each status means.

On this page

The Agents panel lists every terminal of every project in one place. Each row has a status dot, so you see at once which agents work and which wait for you. Click a row to bring its terminal into view. Select several rows to act on many terminals at once. The status bar shows the same statuses as a short tally.

Where to find it

  • Left sidebar, the Agents icon on the activity rail (tooltip "Agents"). See Window layout.
  • Status bar, the Agents item at the right end. A click opens the panel.
  • Keyboard: Ctrl+Shift+A (Cmd+Shift+A on macOS) brings the next waiting agent into view. You do not need to open the panel first.

What you see

Panel title bar. The title is Agents. Two icon buttons sit before the ✕ button.

  • Resource button — tooltip "Show resource usage". When resource usage is on, the tooltip is "Hide resource usage" and the button is lit.
  • Idle-sleep button — tooltip "Sleep every terminal idle longer than N hours (right-click to change the threshold)".

Fleet resource total. A thin band under the title bar. It shows only while resource usage is on. It reads CPU, a figure, Memory, a figure, and a count such as "3 terminals". A figure shows "—" when no terminal has a measurement. The count reads "measuring…" until the first measurement arrives, and "nothing live" when no measured terminal exists.

Attention rail. A strip of chips, one for each live agent that has the status Awaiting input. It shows at most 5 chips. A grey chip +N shows how many more agents wait. The rail does not show when no agent waits.

  • Each chip has the agent badge and the terminal name. Its tooltip is "Reveal <name>".

Project sections. One section for each project that has at least one terminal. The active project is first. The other projects follow in alphabetical order. A section header has:

  • a chevron, the project name and the number of terminals;
  • an amber dot and a number when agents of the project wait for input.

Terminal group card. A card inside a section. Its header has a grid icon, the group name and the number of members. The header button is named "Collapse <name> group" or "Expand <name> group". A collapsed card shows a small tally of its members: a dot and a number for each status. The tally lists waiting agents first.

Row. One row for each terminal. The first line, from left to right:

  • the status dot. It has no text. See "States and messages";
  • the terminal name;
  • the marks Has note (notebook icon), Pinned (pin icon), Lead (the lead of a terminal group) and Unread (a small dot);
  • the memory figure (tooltip "Memory used by this terminal's processes") and the CPU figure (tooltip "CPU used by this terminal's whole process tree, including its children"). They show only while resource usage is on;
  • the agent badge. Its tooltip is the agent name, for example "Codex". A plain shell shows a terminal icon and the word "shell" instead.

The second line shows the worktree name, the git branch, the model, a dot and the effort. The second line appears only when a worktree, branch or model exists; effort appears only beside a model. Without those details, the row is shorter and its status dot is centered on the name line. A plain shell has the same compact one-line layout. When the model or effort comes from the launcher and not from the terminal, its tooltip says so. The row of the terminal that is active on the canvas has a light highlight.

Sleeping. A button with a moon icon, the word Sleeping and a number. It sits under the live rows of a section. It shows only when the project has terminals without a live process. It stays closed until you open it. Its rows look dimmed.

Selection bar. A bar at the foot of the panel. It shows only while at least one terminal is selected. It reads "N selected". It has seven icon buttons, in this order:

  • Group terminals (grid icon).
  • Wake or reload terminals (refresh icon).
  • Sleep idle selected terminals (moon icon). Its tooltip is "Sleep selected terminals idle longer than N hours".
  • Terminal colour (palette icon).
  • Copy terminal references (copy icon).
  • Close selected terminals (trash icon).
  • Clear selection (✕ icon).

The tooltip of each button, except the sleep button, is the button name.

Empty state. "No agents launched yet." shows when no terminal exists.

Agents item in the status bar. The label Agents, then a tally of six numbers:

  • the total, then one dot and number each for active, working, awaiting, not started and finished;
  • each number has the name, for example "3 working".

The item reads none and is disabled when no terminal exists. It counts all terminals of all projects, plain shells too. The finished number also counts sleeping terminals and terminals with an error. The awaiting number pulses while it is more than zero. Orkestra shows no popover for this item.

How to

Open the Agents panel

  1. Click the Agents icon on the activity rail in the left sidebar.

Result: the panel opens. Only the section of the active project is open.

You can also click the Agents item in the status bar. That click opens the panel and never closes it.

Bring a terminal into view

  1. Open Agents in the left sidebar.
  2. Click a row.

Result: Orkestra opens the project and the workbench of the terminal. The window comes to the front, the canvas centres on it and the window flashes. An enlarged window returns to the canvas. A finished or waiting status that you had not seen turns to Active.

Bring a waiting agent into view from the rail

  1. Find the attention rail at the top of the panel.
  2. Click a chip.

Result: the same as a click on its row. The chip leaves the rail, because the wait is now seen.

Bring the next waiting agent into view with the keyboard

  1. Press Ctrl+Shift+A (Cmd+Shift+A on macOS).

Result: Orkestra brings one waiting agent into view, as a click on its row does. Press the keys again for the next one. The order is the order of the panel: the active project first. If no agent waits, nothing happens. While the cursor is in a terminal, Ctrl+Shift+A selects all text in that terminal and does not bring an agent into view. See Terminal windows.

Show or hide the terminals of a project

  1. Click the header of a project section.

Result: the section opens or closes. The section of the active project always stays open. When you close and open the Agents module again, only the active project is open.

Show or hide the members of a terminal group

  1. Click the header of a terminal group card.

Result: the members show or hide. Orkestra remembers this after a restart. A reveal of a hidden member opens its group again. See Terminal groups.

Find a terminal that has no live process

  1. Open a project section.
  2. Click Sleeping.

Result: the dimmed rows show. Click a row to bring its terminal into view. Orkestra opens Sleeping by itself when you reveal such a terminal. To wake one, see Terminal states, reconnect and history.

Select several terminals

  1. Hold Ctrl (Cmd on macOS) and click a row.
  2. Hold Ctrl (Cmd on macOS) and click a second row.

Result: both rows are marked. The selection bar shows "2 selected". A row of a terminal group selects the whole group. Click a selected row with Ctrl or Cmd again to unselect it. The rows stop moving while a selection exists.

Group the selected terminals

  1. Select two or more rows.
  2. Click Group terminals in the selection bar.

Result: the terminals form one group. Terminals of other workbenches of the same project move to the workbench of the first selected terminal. Terminals of different projects do not group. The message reads "Terminals can only be grouped within one project." The button is off while fewer than two terminals are selected. See Terminal groups.

Wake or reload the selected terminals

  1. Select one or more rows.
  2. Click Wake or reload terminals.
  3. If a dialog titled Reload terminals opens, click Reload.

Result: Orkestra wakes the terminals without a live process and restarts the live ones. Without live terminals no dialog opens. The message reads "Waking · N terminals", "Reloading · N terminals" or "Waking N · reloading M". A terminal that a person controls through Telegram stays out, and a message tells you.

Sleep the selected idle terminals

  1. Select one or more rows.
  2. Click Sleep idle selected terminals.

Result: Orkestra stops the idle live terminals of the selection. The message reads "Slept N terminals". Its detail lists the skipped terminals with the reason and the threshold. If a skipped terminal is controlled through Telegram, a red error message also reads "A person controls this terminal through Telegram. Try again in 60 seconds, then 2 minutes, then 5 minutes." It shows once for the whole action, and that terminal stays live. See "Sleep every idle terminal".

Change the colour of the selected terminals

  1. Select one or more rows.
  2. Click Terminal colour in the selection bar.
  3. Click a swatch. The first swatch is Default. The others are Ruby, Coral, Gold, Lime, Emerald, Cyan, Azure, Violet, Magenta and Slate.

Result: the swatch row closes. The title bars of all selected terminals take the colour.

Copy references to the selected terminals

  1. Select one or more rows.
  2. Click Copy terminal references.

Result: the message reads "Copied · N terminal references". The clipboard holds one reference line for each terminal. A group that you selected whole comes as its own block. You can paste the text into an agent prompt.

Close the selected terminals

  1. Select one or more rows.
  2. Click Close selected terminals.
  3. In the Close terminals dialog, click Close.

Result: the terminals close. The message reads "Closed · N terminals". The dialog says "Close N selected terminals? This cannot be undone." Click Cancel to keep them.

Clear the selection

  1. Click Clear selection in the selection bar.

Result: the rows are no longer marked and the selection bar goes away.

Open the menu of one terminal

  1. Right-click a row.

Result: the terminal info menu opens at the pointer. It has the extra buttons Pin, Reload and Close. See The terminal info menu. A pinned terminal stays at the top of its project.

Show memory and CPU of the terminals

  1. Click the resource button (tooltip "Show resource usage") in the panel title bar.

Result: every row shows its memory and CPU figures, and the fleet total band shows. Click the button again (tooltip "Hide resource usage") to hide them. The setting resets to off when you restart Orkestra.

Sleep every idle terminal

  1. Click the idle-sleep button in the panel title bar.

Result: Orkestra stops each live terminal in every project that you did not use for longer than the threshold. It asks no question. The message reads "Slept N terminals". Its detail reads, for example, "· Skipped 2 — working (1), recently active (1) · threshold 3 hours". Orkestra skips a terminal that is not live, works, waits for input, is controlled through Telegram or is recently active. When it skips a terminal that is controlled through Telegram, a red error message also reads "A person controls this terminal through Telegram. Try again in 60 seconds, then 2 minutes, then 5 minutes." It shows once for the whole action. Other skip reasons are "could not be put to sleep", "cancelled because the terminal changed state" and "stop not confirmed".

Change the idle-sleep threshold

  1. Right-click the idle-sleep button.
  2. Type a number in the Hours field of the Idle sleep threshold popover.
  3. Click Apply. You can also press Enter.

Result: the popover closes and Orkestra saves the value. The same value is in Settings → Performance, in the field "Sleep terminals unused for (hours)". Press Esc, or click outside, to close the popover without a change.

States and messages

Status labels and dots. A row dot has no text.

  • Not started — hollow grey ring. The terminal has no process now, for example after a restart.
  • Active — solid green dot. The process runs. The agent is idle, or you have seen its last finish or wait.
  • Working — blue ring that turns. The agent works or its output flows now.
  • Awaiting input — amber dot with a soft pulse. The agent waits for you, and you have not seen it yet.
  • Finished — magenta check mark. A turn that you sent has ended and the output is quiet. The status also shows when the process ended on its own.
  • Sleeping — faded grey dot. The process is stopped to save resources. The window stays on the canvas.
  • Error — red dot. The process failed to start, or it ended with an error right after the start.

The status bar tally and the terminal title bar use the same colours as plain dots. The title bar shows Sleeping in violet. See Terminal windows.

How Orkestra decides.

  • A supported agent reports what it does. Only a report can tell "waits for you" from "finished". Turn this on or off in Settings → Engines, group Agent status reporting, check box "Let agents report their status through installed hooks". It is on by default. See Settings: task defaults and engines.
  • Without reports Orkestra reads the flow of output. Awaiting input then never shows.
  • A report "working" counts for 10 minutes after the last sign of life. After that, and when the output is quiet, the status falls back to what Orkestra sees.
  • A wait or a finish that you have seen shows as Active. You see it when you click its window or bring it into view from the panel, the rail or the shortcut. A new turn or a new wait shows the status again.
  • A Sleeping row holds every terminal without a live process. That includes Not started, Sleeping, Finished (process ended) and Error terminals.

Which agent a terminal shows.

  • A terminal shows the status of the agent that it started as. A report from a different agent in the same terminal does not change the dot.
  • A plain shell did not start as an agent. It shows the status of the first agent that reports in it. When that report ends, the next agent that reports can take its place.

Agent by agent.

  • Codex. Awaiting input shows when Codex itself asks you. At that time the Codex window title says "Action Required". A command that Codex reviews automatically does not show Awaiting input. Press Esc on an open question, or cancel the turn: the wait ends at once and the terminal shows Finished. A question that Codex asks while it continues to work keeps Awaiting input while Codex shows "Action Required".
  • Claude Code. Press Esc while Claude works: the terminal can show Finished. A cancel does not end Awaiting input. A Claude session that runs in the background does not change the status of the terminal.
  • OpenCode. Answer or reject a prompt, also a prompt of a subagent: Awaiting input ends at once. An error that OpenCode recovers from does not show Finished. Working stays while a subagent works.
  • Antigravity. A question or a permission request from a tool shows Awaiting input.

Marks.

  • Unread — Orkestra has not marked the terminal as seen. It sets this after a turn is sent, and when the agent starts or stops waiting. A click on the window, or bringing the terminal into view, marks it as seen while it is Finished or Awaiting input.
  • Lead — the terminal leads its group.

Messages. They show briefly at the screen edge.

  • "Waking · N terminals", "Reloading · N terminals", "Waking N · reloading M" — after Wake or reload terminals.
  • "Nothing to wake · the selection is already live" and "Already reconnecting · N terminals" — nothing new to start.
  • Dialog Reload terminals — "Reload N live terminals? Their agent sessions restart." With dormant terminals in the selection: "Wake N terminals and reload M live ones? The live agents' sessions restart." The buttons are Reload and Cancel.
  • "Slept N terminals" with the detail of skipped terminals — after an idle-sleep action. A red error message "A person controls this terminal through Telegram. Try again in 60 seconds, then 2 minutes, then 5 minutes." follows it when a skipped terminal is controlled through Telegram.
  • In the Idle sleep threshold popover: the hint "1–720 · Enter applies · Esc dismisses", the error "Enter a number between 1 and 720", and the notice "Clamped to N" when Orkestra changed your number to fit.

Limits and tips

  • The panel lists all terminals, plain shells too. It does not show a status word. The status is the dot.
  • Order inside a section: pinned terminals first, then waiting agents, then the terminals you used most recently, then by name. A group card sits where its best-ranked member sits. A group can show twice: its live members in the list and its other members under Sleeping.
  • You can also reach a row with the Tab key and press Enter or Space. That brings the terminal into view.
  • A Ctrl or Cmd click selects and does not bring a terminal into view. The selection is the same as the selection on the canvas.
  • The selection can span workbenches and projects. Only grouping needs one project.
  • The idle-sleep button and Sleep idle selected terminals skip a working or waiting agent.
  • While the Idle sleep threshold popover is open, a click on the idle-sleep button closes the popover. It does not sleep any terminal.
  • Status reports and the idle threshold are settings. See Settings: task defaults and engines and Settings: diagnostics, performance, system state, license and about.
  • Shortcuts on other keyboard layouts work too. See Keyboard shortcuts.