Terminals and agents

Starting terminals and agents

Start an empty terminal or a coding agent from the launch buttons, or launch one or more tasks through the Launch dialog.

On this page

Use the launch buttons to open a plain terminal or a coding agent in the active project. Use the Launch dialog to start the agent for one or more tasks. In the dialog you choose where the agent runs, which agent, which model, and which permission mode.

Where to find it

  • Launch buttons: in the top bar, on the right. They sit after the workbench tabs and before the reconnect, arrange and zoom controls (see Workbenches and the canvas). They show only when a project is open.
  • Launch dialog: it opens when you launch tasks from the play button of a task row, from the Launch button of the selection bar in the ToDo panel, or from a task window. See Tasks and Task window.
  • Launch notices: small cards in the bottom-right corner. The launch error card shows inside the terminal window whose start failed.

What you see

Launch buttons (one pill, left to right)

  • The terminal button (tooltip "New empty terminal") — starts a plain shell terminal.
  • A thin separator. It shows only when at least one agent button follows.
  • One icon button for each installed agent launcher (tooltip "Launch" and the launcher name, for example "Launch Claude Code"). The icon has the color of the launcher. A default Orkestra install has Claude Code, Codex, Cursor, OpenCode and Antigravity.
  • The pill scrolls sideways when the window is narrow. It has no overflow menu.

Quick-launch menu (right-click an agent button)

  • Header — the launcher name and a refresh icon button (tooltip "Refresh model catalogue").
  • Effort — a row of choices: Auto and the levels that the agent offers. This row shows only for agents that have a reasoning effort setting.
  • A list of models. Each row shows the model name. The tag Configured marks the model that is saved on the launcher. A play icon at the end of a row shows that the row is ready.
  • Footer — "Click a model to launch" and "Esc to close".

Launch dialog (top to bottom)

  • Title Launch task, or Launch N tasks for several tasks. An X icon button (tooltip "cancel launch") closes the dialog.
  • Launch mode — two cards: Current repository and Separate worktrees.
  • Worktree — a list of the task's linked worktrees and Create new worktree. It shows only in some cases (see Launch a task in an existing worktree).
  • Launcher — one chip button for each agent launcher.
  • Model — a list with a Default (engine-managed) choice, a Custom model id… choice, and a reload icon button (tooltip "Reload model list").
  • Reasoning effort — a list with a Default (harness-managed) choice and a reload icon button (tooltip "Reload reasoning effort list"). It shows only for agents with an effort setting.
  • Permission mode — a list of the modes of the selected agent and a reload icon button (tooltip "Reload permission modes").
  • Run automatically — a switch with a one-line explanation.
  • An info line that tells how many terminals open and how many new worktrees are created.
  • Cancel and the confirm button (Launch or Launch N tasks).

Launch notices and cards: a notice card with a Dismiss icon button, the Initialize Git? dialog, and two error cards in the terminal window. See States and messages.

How to

Start an empty terminal

  1. Find the terminal button (tooltip "New empty terminal") in the top bar.
  2. Click it.

Result: a new terminal window opens in the middle of the visible canvas (or at the nearest free spot). It runs your shell in the project folder and has the title "shell".

Start an agent from the launch bar

  1. Find an agent button in the top bar, for example the one with the tooltip "Launch Codex".
  2. Click it.

Result: a new terminal window opens in the middle of the visible canvas, titled with the launcher name. The agent starts in the project folder. Orkestra passes no model, effort or permission choice, so the agent uses its own defaults.

Start an agent with a chosen model and effort

  1. Right-click an agent button in the top bar. (With the keyboard: focus the button, then press Shift+F10 or the Menu key.)
  2. In the Effort row, click an effort level, or keep Auto. Skip this step when the menu has no Effort row.
  3. In the model list, click the model you want.

Result: the menu closes and a new terminal opens. The agent starts with that model and effort.

Open the Launch dialog for one task

  1. Open ToDo in the left sidebar.
  2. Move the pointer over a task row that has no running terminal.
  3. Click the play icon button (tooltip "launch task").

Result: the Launch task dialog opens. Its fields start with the launch settings saved on the task. If a window is in focus mode, Orkestra leaves focus mode first.

Open the Launch dialog for several tasks

  1. Select two or more task rows in the ToDo panel.
  2. Click Launch N (for example Launch 3) in the selection bar.

Result: the Launch N tasks dialog opens and the selection clears. The fields start with the launch settings saved on the first selected task.

Launch a task in the current repository

  1. In the Launch dialog, click the Current repository card.
  2. Under Launcher, click the agent you want.
  3. In the Model list, choose a model, or keep Default (engine-managed).
  4. In the Permission mode list, choose a mode.
  5. Click Launch (or Launch N tasks).

Result: the dialog closes. For each task, a terminal opens on the active workbench in the project folder. The terminal has the task name as its title, and the task moves to In Progress.

Launch a task in a new worktree

  1. In the Launch dialog, click the Separate worktrees card.
  2. If the Worktree list shows, choose Create new worktree.
  3. Under Launcher, click the agent you want.
  4. Click Launch (or Launch N tasks).

Result: Orkestra creates one new worktree for each task and opens a terminal in each. The info line shows the number of new worktrees before you confirm.

Launch a task in an existing worktree

  1. Open the Launch dialog for one task that has a linked worktree.
  2. Click the Separate worktrees card.
  3. In the Worktree list, choose the branch of the worktree.
  4. Click Launch.

Result: one terminal opens in that worktree. Orkestra creates no new worktree.

Check the prompt before the agent starts

  1. In the Launch dialog, find Run automatically.
  2. Click the switch to turn it off.
  3. Click Launch.

Result: the terminal opens and the task text is typed into the agent. The agent does not start the work until you press Enter in the terminal.

Fix an "executable not found" error

  1. Read the card in the terminal window. It names the missing program and lists the folders that Orkestra searched.
  2. Click Open settings in the card to open Settings → Engines.
  3. Set the exact path of the program there, or install the program on your computer. See Settings: task defaults and engines.
  4. Close Settings and click Retry in the card.

Result: Orkestra tries to start the agent again. If it finds the program now, the terminal shows the agent.

Show the button of a newly installed agent

  1. Install the agent command line program on your computer.
  2. Click the Settings gear button in the top bar.
  3. Open Engines and click Re-scan.

Result: Orkestra checks again which agents are installed. The agent button shows in the top bar when the check finds the program.

States and messages

  • Agent buttons appear after Orkestra checks installed launchers at startup. An incorrect executable override does not hide a button. In Settings → Engines, use Re-scan after installing an agent.
  • In the quick-launch menu, Loading models… means Orkestra is fetching the list. If it fails, use Retry or Refresh; No models advertised means the agent did not provide a list. A disabled model can be incompatible with the selected reasoning effort. If a saved effort is no longer offered, Auto is selected.
  • In the Launch dialog, a model or permission-list error shows the reason; use its reload button to try again. A saved model that is no longer listed is kept and marked (not listed). Custom model id… lets you enter an ID directly.
  • A Launch failed notice names the task and first failure. Worktree creation errors are included. If the worktree port range is exhausted, Orkestra also shows a system notification.
  • Initialize Git? appears when a worktree launch has no Git repository or commit to branch from. Initialize Git creates the repository, but does not repeat the launch. Add and commit a file, then launch the task again; Not now cancels.
  • Executable not found lists the folders Orkestra searched. Fix the program path in Settings → Engines or install the program, then choose Retry.
  • Terminal engine not available means Orkestra could not start a terminal. Follow the Fix: guidance, or open System check, then try Retry. Other start errors appear in the terminal as failed to start with the reason. A task whose launch fails returns to its previous status.

Limits and tips

  • A launch from the top bar uses no task and asks for no permission mode. Orkestra records the session in the project history (see Session history).
  • The Launch dialog starts one terminal for each task. In a group launch, all tasks use the same choices. The Worktree list is only for a single task.
  • The dialog closes as soon as you confirm. Failures show afterwards as notices.
  • Changing the Launcher resets Model to the default, because a model name belongs to one agent. Permission mode changes to the first mode of the new agent if the old mode was a mode of another agent.
  • Reasoning effort shows only for launchers built on Claude Code or Codex. OpenCode and Antigravity have no effort setting. For Cursor, the level is part of the model choice. If you change the model and the effort is not supported, the effort list moves to the model default.
  • The Permission mode list comes from the agent. Claude Code lists Manual, Accept edits, Plan, Auto, Don't ask and Bypass permissions. Codex lists Read-only, Agent and Agent (full access). If the task saved a mode that the list does not contain (for example Ask each time), the list adds it as the last choice. Some modes reduce or remove approval prompts. Read the mode name before you click Launch.
  • New tasks get their launch values from Settings → Task Defaults. The launchers come from Settings → Engines. A custom launcher gets its own button. Its icon is the mark of its base agent, and its color tells it apart from other launchers on the same base. See Settings: task defaults and engines.