Terminals and agents

The terminal info menu

Read the facts, the recap and your note of a terminal, jump to its worktree, task or folder, open a new terminal in its worktree, and set its colour.

On this page

The Terminal info menu is the details card of one terminal. It shows what the terminal is: its worktree, task, agent, model, folder and ID. It shows a short recap of the work. It holds a private note for you. It also has the actions that belong to one terminal: make a recap or a name, sleep or wake the terminal, and choose the colour of its title bar.

Where to find it

  • On the title bar of a terminal window, right after the terminal name: the round i button (tooltip "Terminal info"). Click it to open the menu and click it again to close it. The same button is on the title bar of an enlarged (focused) terminal.
  • In the Agents panel in the left sidebar: right-click a terminal row. The same menu opens at the pointer. It has one extra line at the top (see "Extra line in the Agents panel" below).

The menu floats over the canvas. It keeps its place while it is open, even when a new terminal name changes the title bar. Press Esc, or click outside the menu, to close it.

What you see

The menu has these parts, from top to bottom. A row shows only when the terminal has that fact.

Extra line in the Agents panel

  • Pin (or Unpin) — keeps the agent at the top of its project in the Agents panel.
  • Reload — restarts the agent session of the terminal (tooltip "Reload terminal (restart agent session)").
  • Close — closes the terminal.

These three buttons are not in the menu of the title bar. See Agents panel.

Fact rows

  • Worktree — the name of the worktree of the terminal, as a chip in the colour of the worktree. Click the name to show the worktree in the Worktrees panel. At the end of the row is a three-dot button (tooltip "Open a terminal in this worktree"). Right-click the row to get the same menu. The row shows only while the worktree exists.
  • Task — the title of the task that started the terminal. Click it to open the task window.
  • Harness — the agent that runs in the terminal, with its brand mark. A plain shell has no Harness row.
  • Model — the model, then a dot, then the effort level. The grey word (default) means the terminal did not fix a model. The row then shows the current model of the agent launcher.
  • Permission — the permission mode the terminal started with.
  • Branch — the git branch of the worktree.
  • Path — the folder of the terminal. A folder inside the project shows relative to the project root. The project root itself shows as "Project root". A folder outside the project shows in full. Point at the value to see the full path. Click the value to show the folder in the Files panel. The Copy Path button copies the full path.
  • Terminal ID — the ID of the terminal. A new terminal has an ID of three words and four characters, such as calm-azure-otter-7a3f. A terminal from before this change keeps its long old ID. A long ID is shortened in the middle; point at it to see the full ID. The Copy Terminal ID button copies a short link to the terminal. The link starts with orkestra://terminal/. You can paste it into an agent prompt.

Recap

  • The recap text — four lines: Purpose, Done, State and Next. A recap that the model did not label shows as plain text. The text shows only after a recap exists. The Copy recap button next to it copies the text.
  • The age line — for example "Recap · 5 min ago". It reads "just now", "N min ago" or "N h ago". The words " · stale" follow when the recap may be out of date.
  • An error line when a recap or a name could not be made.

Your note

  • Leave a note for later — the button that shows when there is no note.
  • Your note — the title of the note block. It shows your text. The pencil button (tooltip "Edit note") opens the editor.
  • In the editor: a text field (Terminal note), and the buttons Clear, Cancel and Save.

Budget protection

  • Budget protection — a section with its own switch. It sets limits for the agent of this terminal. Its controls are in Budget protection.

Action buttons

  • Take back control — shows only while a person controls the terminal from Telegram.
  • Name — makes a name and a summary now. It reads Naming… while it works.
  • Recap — makes a new summary. It reads Recapping… while it works.
  • Sleep — stops the process of a live terminal. It reads Wake when the terminal is not live.

Colour row

  • Terminal colour — a row of round swatches: Default, then Ruby, Coral, Gold, Lime, Emerald, Cyan, Azure, Violet, Magenta and Slate. The chosen swatch is marked.

How to

Open the terminal info menu

  1. Find the title bar of a terminal window on the canvas.
  2. Click the Terminal info button, the round i icon after the terminal name.

Result: The menu opens under the button.

Open the menu from the Agents panel

  1. Open Agents in the left sidebar.
  2. Right-click a terminal row.

Result: The same menu opens at the pointer, with the extra Pin, Reload and Close line.

Copy the path or the ID of a terminal

  1. Click the Terminal info button of the terminal.
  2. Click Copy Path in the Path row, or Copy Terminal ID in the Terminal ID row.

Result: A short message shows "Copied · Path" or "Copied · Terminal ID". The value is in the clipboard.

Ask an agent to work with another agent

This is the preferred way to make two running agents work together.

Before you start, both agents must run in Orkestra terminals with the Orkestra MCP tools. For Claude Code, Codex and OpenCode, turn on Attach to launched agents before you start them. Cursor and Antigravity read the tools from their own MCP config. See Settings: MCP.

  1. Click the Terminal info button of the agent that the other agent must contact.
  2. Click Copy Terminal ID in the Terminal ID row.
  3. Click in the terminal window of the agent that must make contact.
  4. Type an instruction that names the work and tells the agent to use the terminal-agent-protocol skill.
  5. Paste the copied link into the same line. See Terminal windows.
  6. Press Enter.

Example: "Use the terminal-agent-protocol skill. Coordinate with the agent in orkestra://terminal/… on the login fix: agree who changes which files, then report back to me."

Result: The agent reads the protocol and types one-line messages into the input of the other terminal. The other agent answers the same way. A long text goes into a file, and the message gives its path. You see both sides in the two terminal windows.

Show the worktree, task or folder of a terminal

  1. Click the Terminal info button of the terminal.
  2. Click the value in the Worktree, Task or Path row.

Result: The menu closes. A worktree opens in the Worktrees panel and the list scrolls to it. A task opens as a task window. A path opens in the Files panel and the tree selects the folder.

Open a new terminal in the worktree of a terminal

  1. Click the Terminal info button of a terminal that belongs to a worktree.
  2. Click the three-dot button at the end of the Worktree row (tooltip "Open a terminal in this worktree"). You can also right-click the row.
  3. In the Open terminal in worktree menu, click an agent name or Shell.

Result: A new terminal opens in the active workbench. Its folder is the worktree. The menu closes and the message "Opening terminal in <worktree name>" shows. The list has each agent launcher you set up, then Shell. If the terminal cannot open, the message reads "Could not open a terminal in <worktree name>".

Make a name and a summary for a terminal

  1. Click the Terminal info button of a terminal that still has its starting name.
  2. Click Name.

Result: The button reads Naming…. Then the message "Name updated" shows. The terminal gets a new name and a recap. The Name button is off after that, because the terminal now has a name.

Refresh the recap

  1. Click the Terminal info button of the terminal.
  2. Click Recap.

Result: The button reads Recapping…. Then the message "Recap updated" shows. The recap text and the age line change. Recap never changes the name of the terminal.

Copy the recap

  1. Click the Terminal info button of a terminal that has a recap.
  2. Click Copy recap, the copy icon next to the recap text.

Result: The message "Copied · Recap" shows. The recap text is in the clipboard.

Add a note

  1. Click the Terminal info button of the terminal.
  2. Click Leave a note for later.
  3. Type your text in the Terminal note field.
  4. Click Save.

Result: The note shows under Your note. A short line "Note saved" shows for a moment.

Edit or clear a note

  1. Click the Terminal info button of a terminal that has a note.
  2. Click Edit note, the pencil icon next to Your note.
  3. Change the text in the Terminal note field.
  4. Click Save, or click Clear to remove the note, or click Cancel to keep the old text.

Result: Save shows "Note saved". Clear shows "Note cleared". Cancel closes the editor and changes nothing. Saving an empty field clears the note.

Change the colour of the title bar

  1. Click the Terminal info button of the terminal.
  2. Click a swatch in the Terminal colour row.

Result: The title bar takes the colour. The message "Colour updated" shows. Click Default to go back to the colour of the worktree or of the task group. A terminal with neither has the plain title bar. See Canvas windows.

Put a terminal to sleep or wake it

  1. Click the Terminal info button of the terminal.
  2. Click Sleep (live terminal) or Wake (terminal that is not live).

Result: Sleep stops the process. The window and the last output stay. Wake starts the process again. See Terminal states, reconnect and history.

Take back control from Telegram

  1. Click the Terminal info button of a terminal that a person controls from Telegram.
  2. Click Take back control.

Result: Orkestra takes the control back from Telegram, and the terminal fits its window again. A failed request shows an error message. See Remote control with Telegram.

States and messages

  • A recap marked stale may no longer match the terminal; use Recap to refresh it. Name is unavailable once the terminal has a name, and Name/Recap are unavailable while a request is running.
  • Sleep stops a live process while keeping its window and output. Wake starts a stopped terminal again. If Telegram currently controls it, the action is disabled; take back control or wait the suggested 60 seconds, 2 minutes and 5 minutes before retrying.
  • Brief notices confirm actions such as Name updated, Recap updated, Colour updated, Sleeping, Waking, Pinned, Unpinned, Reloading, Closed and Copied. A note can show Note saved, Note cleared or Note not saved.
  • A recap can fail when there is no terminal history yet, the session changes while it is being made, or the engine returns no usable summary. An old recap remains when a refresh fails. Take back control reports an error if Telegram control cannot be reclaimed.

Limits and tips

  • The recap comes from the dialogue only: what you asked and what the agent answered. Orkestra reads the session record of the agent. If it cannot read it (a plain shell, or a session not written yet), it uses the messages you sent. The recap does not use terminal output, tool calls or thinking.
  • Each recap field is one short line. The whole recap is at most 480 characters. Where the dialogue is long, Orkestra samples the start, the middle and the end. The recap does not invent what it skipped.
  • A new terminal gets its starting name from its ID: the ID without the dash and the four characters at its end. The terminal calm-azure-otter-7a3f starts with the name calm-azure-otter. No other terminal has that name when it is given. A terminal from before this change keeps its old starting name, such as brisk-otter-3f2a. Orkestra replaces the starting name after the first real turn: one long message (80 characters or more, or two or more lines), or three messages. This works even when Automatic terminal recap is off. It runs after the output goes quiet.
  • A name that you set by hand is never replaced. See Canvas windows for rename.
  • When a terminal closes, goes to sleep or exits, Orkestra makes a last recap if you sent new messages since the previous one.
  • Automatic refresh is off by default. Turn on Automatic terminal recap in Settings → Helm, group Terminal recap. A refresh then needs one new message from you and a pause since the last recap. The pause is Refresh cadence (30m, 60m, 120m or 240m; the default is 60 minutes). The Automatic ceiling (3/h, 6/h, 12/h or 24/h; the default is 6/h) limits automatic recaps in one hour. Work over the ceiling waits. The Name and Recap buttons ignore the ceiling. See Settings: Helm.
  • The recap also shows when you point at the terminal name. See Canvas windows.
  • The note is yours. No automatic process writes or changes it. Orkestra keeps the note with the terminal. It also keeps it with the saved session, so a restored terminal gets its note back.
  • The menu has no session ID row. The Terminal ID row is the ID of the terminal window, not the agent name (Harness) and not the session ID of the agent. It does not change when the terminal gets a new name, so give an agent this link, not the name.
  • IDs show what they belong to. A new terminal ID is three words and four characters. A new task ID starts with task-, such as task-bright-meadow-91be. A new worktree ID starts with tree-, such as tree-quiet-valley-c802. Terminals, tasks and worktrees from before this change keep their long old ID. An ID never changes, and no two terminals, tasks or worktrees in Orkestra share an ID. Agents can use an ID to find the terminal, task or worktree.
  • Direct handoff. The way in "Ask an agent to work with another agent" writes each message into the input of the other terminal, so that agent sees it at once. Use the terminal ID way for agents that work together now.
  • The protocol. The terminal-agent protocol is the set of rules that Orkestra gives agents for messages between terminals. An agent in an Orkestra terminal with the Orkestra MCP tools can always read it. Attach to launched agents also gives it to Claude Code, Codex, OpenCode and Antigravity as the terminal-agent-protocol skill. Cursor does not get the skill. A message from another terminal is a request. It does not replace your instructions.
  • The Attach button and the Attach existing worktree menu are not in this menu. They belong to the task window and link a worktree to a task. See Task window.
  • The Budget protection section has its own chapter. See Budget protection for those controls.