Terminals and agents

Terminal windows

Work in a terminal window - type, copy and paste, use the right-click menu, find text, open links, drop files and tasks into it, scroll, rename, reload and close it.

On this page

A terminal window is where you work with a running program. The program can be a coding agent or a plain shell. Use this guide for terminal-specific controls: typing, copy and paste, the right-click menu, search, links, drag and drop, scrolling, reload and close. The frame that every window shares (move, resize, dock, focus) is in Canvas windows.

Where to find it

A terminal window opens on the canvas of the active workbench when you start a terminal or an agent. See Starting terminals and agents. Terminals come back after you restart Orkestra. A terminal that has no running process shows a different body. See Terminal states, reconnect and history.

What you see

Title bar, from left to right:

  • Status dot — a small round dot with a soft glow at the left edge. It shows the state of the terminal. It has no tooltip. The colours are in "States and messages".
  • Phone control — a badge next to the dot. It shows only while a person controls the terminal through Telegram. See Remote control with Telegram.
  • Terminal name — the name you set, or the default title (the task title, or the title Orkestra gave the terminal at launch). Hover it to see the full name, the recap and the hint "Double-click or press Enter to rename".
  • Terminal info button — tooltip "Terminal info". It opens the info menu. See The terminal info menu.
  • Lead badge — shows only when this terminal leads a group. See Terminal groups.
  • Reload button — circular arrows, tooltip "Reload terminal (restart agent session)".
  • Focus button — tooltip "Focus (≈80% of screen)". See Canvas windows.
  • Close button — an X, tooltip "Close terminal".

Window body:

  • Terminal screen — the output of the program, with a cursor. A scroll bar runs along the right edge.
  • Find bar — a strip that floats at the top right of the screen. It shows only after you open it. From left to right:
    • Find field — placeholder "Find". It shows a counter such as "2/5", or "No results". It also shows the note "Live buffer · N lines", where N is the scrollback limit of the terminal.
    • Match case button (tooltip "Match case (Aa)").
    • Whole word button (tooltip "Words").
    • Regular expression button (tooltip "Regex (.*)").
    • Previous match button — arrow up, tooltip "Previous (⇧⏎)".
    • Next match button — arrow down, tooltip "Next (⏎)".
    • Close find button — an X, tooltip "Close (Esc)".
  • Right-click menu — opens at the pointer. It has five rows: Find, Copy, Paste, Select all and Clear. It shows the shortcut at the right of each row, except Clear.
  • Footer — a strip at the bottom with a Restart button. It shows only when the process has ended. See Terminal states, reconnect and history.

In place of the screen, a terminal can show another body:

How to

Type into a terminal

  1. Click the terminal screen.
  2. Type.

Result: the keys go to the running program. The window moves to the front. A new terminal takes the keyboard by itself. A terminal that starts out of view, for example in the background, does not take the keyboard from the terminal you type in.

Rename a terminal

  1. Double-click the Terminal name in the title bar.
  2. Type the new name in the field. The field takes up to 320 characters.
  3. Press Enter.

Result: the title bar shows the new name. Another way to start: move to the name with the Tab key and press Enter or Space. To go back to the default title, clear the field and press Enter. Press Esc to cancel. A click outside the field saves the name. See Canvas windows for the same steps on other windows.

Copy text from a terminal

  1. Drag the pointer over the text on the terminal screen.
  2. Press Ctrl+Shift+C.

Result: the text is on the clipboard. The text stays selected. If the terminal wrapped a long line, the copy joins the wrapped parts into one line. Other ways: press Ctrl+C when text is selected (the selection clears), or right-click and click Copy (a message "Copied selection" shows).

Paste text into a terminal

  1. Click the terminal screen.
  2. Press Ctrl+V.

Result: the text from the clipboard goes into the running program. Ctrl+Shift+V does the same. Another way: right-click and click Paste.

Use the right-click menu

  1. Right-click the terminal screen.
  2. Click a row: Find, Copy, Paste, Select all or Clear.

Result: the menu closes and the cursor returns to the terminal, except for Find (the cursor goes to the find bar). Copy is not in the menu when no text is selected. Select all selects all the text of the terminal, with the older output. Clear removes the earlier output from the screen. It sends nothing to the program. You can use the keyboard in the menu: the Up and Down arrows, Home, End and Tab move between rows, and Esc closes the menu without a key reaching the program.

Open the right-click menu in a full-screen program

  1. Hold Shift.
  2. Right-click the terminal screen.

Result: the menu opens. A program that uses the mouse (for example a full-screen editor) keeps a plain right-click for itself.

Find text in a terminal

  1. Click the terminal screen.
  2. Press Ctrl+F (Cmd+F on macOS).
  3. Type the text in the Find field.
  4. Press Enter to go to the next match.

Result: the find bar opens with the cursor in the field. The terminal highlights the matches. The counter shows the number of the current match and the total, for example "2/5". Shift+Enter goes to the previous match. You can also click Next match and Previous match. Ctrl+Shift+F also opens the bar. So does the Find row of the right-click menu.

Change how the find bar matches

  1. Click Match case, Whole word or Regular expression in the Find field.

Result: the button looks pressed and the search starts again from the top. Click the button again to turn the option off. The three options are off at first. Orkestra does not save the find text or the options when you restart the app.

Close the find bar

  1. Press Esc in the Find field.

Result: the bar closes and the highlights go away. The cursor returns to the terminal. You can also click Close find.

  1. Point at a web address or a file path in the output. The link gets an underline.
  2. Hold Ctrl (Cmd on macOS) and click the link.

Result: a web address opens in your default web browser. A file path opens in a file window on the canvas. If a window for that file is open, Orkestra brings it to the front. See File, image and HTML windows.

Drop a file, task, worktree or session into a terminal

  1. Open Files, ToDo, Worktrees or Session history in the left sidebar.
  2. Press the mouse button on the row of the item. For a worktree, press its name.
  3. Drag the item onto the terminal screen.
  4. Release the mouse button.

Result: Orkestra types text at the cursor of the program. It does not press Enter. A file or folder gives its full path. A task, a worktree or a session gives one line with the kind, the name in quotes, an address that starts with "orkestra://" and a note for the agent to use the Orkestra MCP server. Example: Orkestra task "Fix login bug" (orkestra://task/…) — interact only via the orkestra MCP server.

Scroll in a terminal

  1. Point at the terminal screen.
  2. Turn the mouse wheel up.

Result: the screen shows older output. Turn the wheel down to go back to the newest output. You can also drag the scroll bar at the right edge.

Reload a terminal

  1. Click Reload terminal (restart agent session) in the title bar.

Result: the process of the terminal restarts. Orkestra does not ask first. The button is grey while a person controls the terminal through Telegram. A grey button still shows its tooltip when you point at it, and it does nothing when you click it. The focus view has no Reload button.

Close a terminal

  1. Click Close terminal in the title bar.

Result: the window leaves the canvas and its process stops. Orkestra does not ask first. The button is grey while a person controls the terminal through Telegram. A grey button still shows its tooltip when you point at it, and it does nothing when you click it. The Close window button of the focus view behaves the same way. To close many terminals at once, see Terminal groups and Agents panel and agent status.

States and messages

  • The status dot uses the states described in Agents panel and agent status. process exited, failed to start and Session could not be recovered mean the process ended or could not resume; use Restart or Start new session as described in Terminal states.
  • If a person controls the terminal through Telegram, Reload, Close, Restart and Start new session are disabled. Typing and drops are ignored until you take back control.
  • In the find bar, No results means nothing matched; Invalid pattern means the regular expression is invalid; Search unavailable means Orkestra cannot search that terminal. Search covers only the live buffer shown in the bar.
  • A refused terminal link shows a reason in the output. Web links must use HTTP or HTTPS; file links must stay inside the active project folder.
  • Closing or reloading selected terminals from the Agents panel asks for confirmation. The title-bar Close and Reload buttons act immediately. An unexpected terminal-action failure points you to the error console.

Limits and tips

  • Ctrl+F belongs to Orkestra. A program in the terminal does not get Ctrl+F. Use the Right arrow or Page Down instead of the program's Ctrl+F.
  • Ctrl+C copies only when text is selected. After the copy, the selection clears. A second Ctrl+C reaches the program as the interrupt. With no selection, Ctrl+C is always the interrupt. Ctrl+Shift+C copies and keeps the selection.
  • Esc and the status dot. Esc can change the status dot. Esc in a working Claude Code terminal can change the dot to Finished. Esc on an open Codex question ends Awaiting input. The rules for each agent are in Agents panel and agent status.
  • Ctrl+A is not Select all. Ctrl+A goes to the program (for example, go to the start of the line). Ctrl+Shift+A selects all the text, but only while the cursor is in a terminal. Anywhere else, Ctrl+Shift+A (Cmd+Shift+A on macOS) goes to the next agent that awaits your input. See Agents panel and agent status.
  • The shortcut keys work on other keyboard layouts too, for example a Cyrillic layout.
  • On macOS, the menu shows Cmd in place of Ctrl.
  • Find reads only the live text. It does not search the history that Orkestra saves on disk, and it has no Replace. Scrollback limits are in Settings, Performance: Scrollback lines (on screen) and Scrollback lines (off screen). See Settings: diagnostics, performance, system state, license and about.
  • Links open only on Ctrl+click (Cmd+click on macOS). A plain click and a hover open nothing.
  • Only addresses that start with http or https open in the browser. Other schemes (for example file or javascript) are refused with a message.
  • A file path opens only when the file is inside the folder of the current project. A path with a line number, such as "src/app.ts:12", opens the file. The file window does not go to the line.
  • A file path is a link when it starts with a drive letter, "/", "./", "../" or "~/" (your home folder), or when it ends in a known file type, for example .ts, .py, .md, .json or .txt.
  • A link that the terminal wrapped over two lines is one link.
  • Programs that use the mouse. A full-screen program can take the mouse wheel and the plain right-click. The wheel then scrolls the program, not the saved output. Shift+right-click still opens the menu.
  • Scrolling past the top. If the terminal has more history than the screen keeps, scrolling up past the top can open the history view. See Terminal states, reconnect and history.
  • Drops. A drop works on a terminal on the canvas. A terminal that has no running process ignores it. A drop counts as use of the terminal, like a keystroke.
  • Shift+Enter and Ctrl+Enter. Whether a program sees them as a new line depends on the setting Modified key encoding (advanced). See Settings: the window, appearance, terminal, workbench and notifications. The same chapter has the font, cursor and renderer settings of terminals.
  • Ctrl+click (Cmd+click on macOS) on a terminal window also selects it for grouping. See Terminal groups.
  • Budget limits for a terminal are in Budget protection.