Terminals and agents

Terminal states, reconnect and history

Bring back a terminal that does not run (restored after a restart, asleep or ended), and read the saved output of a terminal.

On this page

A terminal window does not always have a running process. When you quit Orkestra, all processes end. When you start Orkestra again, every terminal comes back with its window but without its process. Orkestra can also put an idle terminal to sleep to save resources. Use this guide to bring terminals back, read saved output while they are stopped, and open the full history of a live terminal.

Where to find it

  • A terminal that does not run shows its state inside its window. See "What you see".
  • The reconnect control is in the top bar, on the right. It is right of the launch buttons and left of Tidy windows. It shows only while a project and a workbench are open.
  • The history view opens inside a live terminal window when you scroll up past the oldest line of its live view.
  • Terminals that cannot start (for example a missing agent program) show an error card. See Starting terminals and agents.

What you see

Body of a terminal that does not run (a restored terminal or a sleeping terminal):

  • Saved output — the last output of the terminal, as plain text without colours. The newest line is at the bottom. At the top, a notice can say "Beginning of history" (all saved lines are loaded) or "Only the newest rows that fit are retained; scroll to the top for older history."
  • Status strip — a bar along the bottom edge with an icon, a bold state name and a grey line of help text.
    • Restored terminal: a circular-arrow icon and the bold name Session not live.
    • Sleeping terminal: a moon icon and the bold name Sleeping.
  • The body has no button. The whole body is the target for reconnect and wake.

Title bar of the same window:

  • Status dot — it shows "Not started" for a restored terminal and "Sleeping" for a sleeping terminal. See Agents panel and agent status.
  • Reload button — a circular-arrows button (tooltip "Reload terminal (restart agent session)"). See Terminal windows.

Top bar:

  • Reconnect control — a button with a lightning-bolt icon. Its tooltip shows the count, for example "Reconnect 3 sleeping agents in this workbench". The button looks grey when the tooltip says "No sleeping agents in this workbench".

Inside a live terminal:

  • History view — a read-only copy of the whole output, drawn over the live terminal. It uses the same colours as the terminal, but the text has no colours or styles.
  • History badge — a small, faint round icon (a clock face with a circular arrow) in the top-right corner of the history view. Its tooltip is "Scrollback history — scroll down to the live line, or press Esc, to return".

Bottom of a terminal that has ended:

  • Footer — a line that says "process exited" or "failed to start", with a Restart button.
  • Recovery card — a card titled "Session could not be recovered", with a Start new session button.

How to

Reconnect one terminal after a restart

  1. Find a terminal window whose status strip says Session not live.
  2. Click the saved text in the body of that window.

Result: the terminal starts a new process in the same folder. If the terminal has a saved agent session, the agent resumes that session. If not, a fresh session starts. The body changes to the live terminal. If many agents wake at the same time, a terminal can wait a few seconds in a short queue. The body stays unchanged until its turn comes.

Other ways to reconnect: right-click or middle-click the body, or press Enter or Space while the body has the keyboard focus. The Reload button in the title bar restarts the terminal at once, without the queue.

Reconnect all terminals of a workbench

  1. Select the workbench in the tab strip of the top bar.
  2. Point at the lightning-bolt button in the top bar. Read the count in the tooltip.
  3. Click the lightning-bolt button.

Result: Orkestra wakes every restored terminal and every sleeping terminal of that workbench. It starts them in batches. A terminal that already runs is not touched. Orkestra shows no message when the batch starts. It shows an error message only when a wake fails. See "States and messages".

Wake a sleeping terminal

  1. Find a terminal window whose status strip says Sleeping.
  2. Click the saved text in the body of that window.

Result: the terminal starts again. If it has a saved agent session, the agent resumes it. If not, a fresh session starts. A wake gives no message when it works.

Other ways: click Wake in the Terminal info menu of the terminal (see The terminal info menu), or use the reconnect control in the top bar.

Read the saved output without waking the terminal

  1. Scroll the saved text of a restored or sleeping terminal with the mouse wheel or the scrollbar.
  2. Scroll to the top to load older lines.

Result: you read the output and the terminal stays as it is. The keys Page Up, Page Down, Home, End and the arrow keys also scroll without a wake. A click on the scrollbar does not wake the terminal.

Selecting text with the mouse wakes the terminal, as does a click in the text. Shift with an arrow or page key and Ctrl+A (Cmd+A on macOS) also wake it.

Focus a sleeping or restored terminal

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

Result: the terminal opens large over a dim backdrop. At the same time Orkestra wakes it (sleeping) or restarts it (restored). The same body with the status strip shows until the terminal is live. If someone controls the terminal through Telegram, Orkestra does not wake it. See Canvas windows: move, resize, dock and focus for focus mode.

Open the full history of a live terminal

  1. Scroll up in the live terminal with the mouse wheel until you reach its oldest line in memory.
  2. Turn the wheel up once more.

Result: the history view opens over the terminal. It shows the older saved lines above and the live lines below. The place where you were is at the top of the view. Scroll up to read older lines.

The view opens only if older output exists outside the live view and the setting for saved history is on. See "Limits and tips".

Close the history view

  1. Click the history badge in the top-right corner of the view.

Other ways: press Esc, or scroll down with the wheel until the live lines reach the top of the view. The view opens at that place, so one turn of the wheel down closes it at once. The live terminal shows the same lines.

Result: the live terminal is in front again.

Restart a terminal that has ended

  1. Click Restart in the footer of the terminal ("process exited" or "failed to start").

Result: Orkestra starts a new process for the terminal. Restart is grey while someone controls the terminal through Telegram. Point at it to read the tooltip "A person controls this terminal through Telegram." A click on it does nothing.

Start a new session when recovery failed

  1. Click Start new session on the card "Session could not be recovered".

Result: Orkestra starts a fresh session. Before this click, Orkestra starts no replacement agent. The card shows a message from Orkestra about the old session.

States and messages

  • Session not live means the app restarted and the terminal process ended. Click its saved output to reconnect; Orkestra resumes a saved agent conversation when one exists, otherwise it starts a fresh session. Scrolling the output alone does not wake it.
  • Sleeping means Orkestra stopped the process but kept the window, output and, when available, the agent context. The reason can be a manual sleep, the idle limit, a live-agent or memory limit, or budget protection. Click the saved output or use Wake to resume; without a saved session, a new one starts.
  • Loading history… means saved output is still being read. No saved scrollback is available means there is nothing to show; History unavailable means Orkestra could not read it.
  • A Telegram control lock prevents wake, restart, reload and close. Take back control from the terminal info menu; if Orkestra reports a temporary lock, wait the displayed intervals before trying again.
  • process exited and failed to start show Restart. Session could not be recovered offers Start new session; no replacement agent starts until you choose it.
  • Orkestra shows a notice when it puts a terminal to sleep automatically or hits a performance limit. Agent startup problems use the error card described in Starting terminals and agents.

Limits and tips

What a restart restores:

  • Orkestra restores the layout: every window with its place, size, name and title colour, the pan and zoom of each workbench, and the terminal groups. It also restores the link to the agent session, the recap and the note of each terminal.
  • Orkestra restores the saved output of each terminal as text, when the setting for saved history is on. After a reconnect, scroll up past the top of the live view to see it again.
  • Orkestra does not restore the process. A terminal always comes back as Session not live, also when it slept before the restart. A plain terminal (no agent) starts a new shell.
  • Orkestra never starts restored terminals by itself. Each one waits for you, also on the workbench you look at.

Resume by agent:

  • Claude Code, Codex, Cursor, OpenCode and Antigravity can resume a saved conversation. A plain terminal has no session to resume.
  • Claude Code gets its session link when it starts. The other four agents get it after they record the conversation. A terminal that closed before that point starts fresh. The help text tells you which case applies: "resume the saved session" or "fresh session".
  • On a resume Orkestra applies the launch options again: the model and the permission mode. It reads the settings of the launcher again, for example the extra environment.

Status after a reconnect:

  • A reconnect, a wake, a restart and a reload start a new process. The status of the old process does not carry over. The status dot starts again from what the new process does.
  • A terminal shows the status of the agent that it started as. In a plain terminal, an agent that you start by hand can report its status. When that agent ends and the shell is in front again, its report ends within about 5 seconds. The dot then shows what the output shows.
  • Status dots and their meaning are in Agents panel and agent status.

Reconnect control:

  • It works on the active workbench only. There is no wake-all for the whole app, on purpose: starting every agent at once overloaded the app.
  • It counts restored terminals and sleeping terminals of the active workbench. It counts plain terminals too, although the tooltip says "agents". It does not count terminals that ended. Use Restart or Reload for those.
  • Plain terminals start at once, up to eight. More plain terminals wait in the same queue as agents. Agents start in batches of at most two, about two seconds apart. A Max concurrent agents value of 1 makes the batch one agent.
  • The Agents panel has its own reconnect action for selected agents. See Agents panel and agent status.

Automatic sleep:

  • It is on by default. Orkestra puts a terminal to sleep when you did not use it for 24 hours. The time is a setting. Limits for live agents, app memory and system memory are off by default.
  • Only a live terminal can sleep. Orkestra never sleeps a terminal while a turn works, while the agent waits for you, or while someone controls it through Telegram. It sleeps the least recently used terminal first, one at a time.
  • In Notify only mode Orkestra does not sleep terminals by itself.
  • The settings are in Settings, Performance. See Settings: diagnostics, performance, system state, license and about.
  • To sleep a terminal by hand, use Sleep in the Terminal info menu. See The terminal info menu.

Terminals that are off screen:

  • A terminal outside the canvas view keeps running. Orkestra stops processing its output and keeps less history for it. When you bring it back into view, it catches up. No process stops. This is a setting and it is on by default.
  • A terminal counts as on screen when its window is in the canvas view or within half a view-size of it. While focus mode is open, all other terminals count as off screen. Terminals of other workbenches and other projects count as off screen.
  • The settings are in Settings, Performance, group Offscreen terminals. See Settings: diagnostics, performance, system state, license and about.

History view:

  • It opens only with a wheel or trackpad gesture. There is no button for it on a live terminal.
  • It does not open while a program in the terminal captures the mouse. The wheel then belongs to that program.
  • It needs the setting Keep full scrollback history on disk (on by default) in Settings, Performance, group Scrollback history. The limit per terminal is the setting Max history per terminal (MB). It is 8 MB by default.
  • The history view is read only.

Other: