Start here

First-run setup, Getting started and tours

Set up Orkestra the first time you start it, follow the Getting started checklist in the status bar, and learn the main surfaces with short guided tours.

On this page

Use first-run setup to check your agent tools, choose a default agent and add a project. Then follow the Getting started checklist in the status bar or replay one of eight guided tours to learn a feature. Begin with Set up Orkestra when it opens, or open it later from Settings → System check → Run setup.

Where to find it

  • First-run setup — opens by itself the first time you start Orkestra on a computer that has no earlier Orkestra data. To open it again, use the Settings button (gear icon) in the top bar, then System check, then Run setup.
  • Getting started — at the left end of the status bar, at the bottom of the window. See Window layout for the other status bar items.
  • Tours — start from Show me in the checklist, or from Settings, System check, Tours. One tour can also start by itself (see "Limits and tips").

What you see

First-run setup window (title Set up Orkestra):

  • Step bar — three steps in this order: System check, Default agent, First project. The current step is highlighted. A finished step shows a check mark. Click a finished step to go back to it.
  • Close setup — the ✕ button at the top right (tooltip "Close setup"). It asks for confirmation (see Skip setup? below).
  • Step 1, System check — a summary line, then the System check report. The report is described in System check.
  • Step 2, Default agent — choose the agent Orkestra uses for new tasks. You can change it later in Settings → Task Defaults. The Default agent list has one row per coding agent. Rows are in two groups: Installed and Not installed. Each row shows the agent name, its path or a short detail, and a state word such as Ready. An installed agent also shows a chip: Signed in, Signed out or Not checked. A not-installed agent has an Install button. One row is selected (round marker).
  • Step 3, First project — choose how to add your first project. You can add more later from the project switcher:
    • Create a new project — create an empty project folder.
    • Clone from a Git URL — copy a remote repository to this computer.
    • Open an existing folder — add a folder already on this computer.
    • Scan a folder for projects — find and add Git repositories under a folder.
  • Footer — Skip setup on the left. On the right: Back (from step 2), and Continue (steps 1 and 2) or Finish (step 3).
  • Skip setup? — confirms that you want to close setup; you can reopen it later in Settings → System check. The buttons are: Keep setting up and Skip setup.

Getting started checklist (status bar):

  • Getting started entry — a progress ring, the words Getting started and a count such as 2 of 11. The count changes to All set when all items are done.
  • Getting started panel — opens upward from the entry. The header shows Getting started, the count, and a ✕ button (tooltip "close Getting started"). When all items are done, the line "You are set up." shows above the list.
  • Item rows — each row has a mark (check, spinner, red dot or empty circle), the item name, a Show me button, sometimes an action button, and a hint line.
  • Footer — the Hide checklist button and the text "Items tick when you really do them".

The items, in order. Open Helm shows only when Helm has an engine you can use; without it the count is out of 10:

Item Ticks when Hint Action button Show me starts the tour
An agent is ready System check finds an agent that is installed and signed in. The hint then reads "<agent> is installed and signed in". Install and sign in to an agent in System check Open System check Workbench and terminals
Add a project At least one project exists. Point Orkestra at a folder on this computer Add project Workbench and terminals
Create a task At least one task exists in any project. A task in the trash does not count. Write what you want the agent to do New task From task to agent
Launch an agent from a task An agent has started from a task at least once. Use a task’s Launch button to choose an agent none From task to agent
Protect a terminal’s budget You turn on Budget protection for a terminal, or you finish the tour with Done. Turn it on in Terminal info, or finish the tour none Terminal budget protection
Work with two terminals on one workbench A workbench has a terminal group, or two terminals that started. Open a second terminal, or group two of them none Workbench and terminals
Group terminals You create a terminal group, or you finish the tour with Done. Group two terminals, or finish the tour none Terminal groups
Move around with the minimap You click or drag the minimap, or move windows with it, or you finish the tour with Done. Click or drag the minimap, or finish the tour none Minimap navigation
Create a worktree At least one project has a worktree. Let agents work on branches side by side New worktree Worktrees
Open a file in the editor A file has opened and loaded at least once. Double-click a file in the tree none Files and source control
Open Helm You open Helm, or you finish the tour with Done. Use the sparkle button, or finish the tour none Helm

The items that allow Done to count can also be completed by doing the real action. Skip tour and tours requested by an agent do not count. The Terminal groups and Helm tours wait for you to perform an action; if the needed control is unavailable, that step is skipped. The other checklist items tick only after you do the action.

Guided tours. Eight tours teach the main surfaces:

  • Workbench and terminals — Choose a project, Start a terminal, then Arrange your workbench by its title bar.
  • From task to agent — Add a task in ToDo, Review the task description, then Launch an agent for the task.
  • Worktrees — Create a worktree. The project needs a Git repository with at least one commit; initialize Git and commit a file first if needed.
  • Files and source control — Open a project file, then Check source control in its panel.
  • Terminal groups — Select terminals, Group the selected terminals, then Keep related work together. The Group terminals action appears after you select at least two.
  • Helm — check that Helm is available, Open Helm from the sparkle button, then Send a request to Helm.
  • Terminal budget protection — Open Terminal info, Check support and identity, Pick readings and limits, then Choose what happens at a limit. The tour does not change settings. Protection reacts to usage readings; it is not a billing cap. Only Codex and Claude Code support it. A stale or startup reading cannot trigger a limit, and message actions need a Message.
  • Minimap navigation — Navigate the canvas by clicking or dragging without changing zoom; Select terminal markers with Ctrl-click (Cmd-click on macOS); Move windows and groups with Ctrl-drag (Cmd-drag). Press Esc to cancel a move.

A tour callout highlights the current control and provides Next, Back, Skip tour and, on the final step, Done. Some steps pause while you perform an action; the tour advances when it succeeds.

Below the report in Settings → System check, use Run setup, Show checklist, or Start/Replay beside a tour. See System check.

How to

Complete the first-run setup

Before you start, the Set up Orkestra window must be open.

  1. Read the summary line at the top of the System check step.
  2. Click Continue.
  3. Choose an agent in the Default agent list (see "Choose a default agent").
  4. Click Continue.
  5. Click Create a new project in the First project step. You can click another option instead.

Result: Setup closes. The project dialog for your choice opens. See Adding, creating, cloning and importing projects.

Choose a default agent

Before you start, go to the Default agent step.

  1. Click the row of the agent you want in the Default agent list.
  2. Click Continue.

Result: Orkestra saves this agent as the default launcher for new tasks. You can change it later in Settings, Task Defaults (see Settings: task defaults and engines).

Skip the first-run setup

  1. Click Skip setup in the footer of the setup window.
  2. Click Skip setup in the Skip setup? dialog.

Result: Setup closes and does not open by itself again. The step you reached is kept.

Run setup again

  1. Click the Settings button (gear icon) in the top bar.
  2. Click System check in the Settings list.
  3. Click Run setup in the Setup group.

Result: Settings closes and the setup window opens at the System check step.

Open the Getting started checklist

Before you start, the Getting started entry must show in the status bar.

  1. Click Getting started in the status bar.

Result: The panel opens above the status bar. Click the entry again, press Esc, or click outside the panel to close it.

Finish a checklist item with its button

Before you start, open the Getting started panel.

  1. Click the action button of an open item, for example Add project.

Result: The panel closes and Orkestra does the first step for you. Open System check opens Settings, System check. Add project opens the add-project dialog. New task adds a task to the current project and opens it in a task window (see Tasks). New worktree opens the Worktrees panel and puts the cursor in its name field (see Worktrees). The item ticks when you finish the real action.

Hide the checklist

  1. Click Getting started in the status bar.
  2. Click Hide checklist in the panel footer.

Result: The panel and the status bar entry disappear.

Show the checklist again

  1. Click the Settings button (gear icon) in the top bar.
  2. Click System check in the Settings list.
  3. Click Show checklist in the Getting started group.
  4. Close the Settings window.

Result: The panel opens in the status bar. It stays out of the way until Settings is closed.

Start a tour from the checklist

Before you start, open the Getting started panel.

  1. Click Show me on the row of an item.

Result: The tour for that item starts. The table above lists the tour for each item.

Start or replay a tour from Settings

  1. Click the Settings button (gear icon) in the top bar.
  2. Click System check in the Settings list.
  3. Click Start (or Replay) in the row of a tour, in the Tours group.
  4. Close the Settings window.

Result: The first callout of the tour appears after Settings closes.

Move through a tour

Before you start, a tour callout must show.

  1. Do what the callout asks, if it shows a wait text.
  2. Click Next when it shows. On the last step, click Done.
  3. Click Back to see the step before.

Result: The ring and the card move to the next control. A step with a wait text moves on by itself when your action succeeds.

Stop a tour

  1. Click Skip tour on the callout. You can press Esc instead, when the cursor is not in a terminal.

Result: The callout closes. Focus returns to the control that had it before the tour.

States and messages

  • Checking agents and Git… means the setup report is still running. Its summary may say <N> of <M> agents ready, Git not found or Git could not be checked. Here, ready means installed; sign-in is shown separately.
  • System check could not finish includes the reason. Click Re-check when offered.
  • If Clone from a Git URL is tagged Needs Git, Git is missing and cloning is disabled. When Git could not be checked, cloning remains available.
  • A selected default can be Not installed yet. Orkestra still saves that choice if you continue, but install the agent before launching it. If no agents are configured, add one later in Settings.
  • If the setup window cannot open, close the fallback dialog and reopen setup from Settings → System check. While Access deactivated is shown, setup and tours are unavailable.
  • Checklist marks show progress: a check is complete, a spinner means the agent check is running, a red dot means that check failed, and an empty circle is unfinished. A failed check shows its reason and offers Re-check. You are set up. appears when all items are complete.
  • In Settings, tour status is Seen after its first callout appears; otherwise it is Not started. Automatic tours are unavailable if setup was never run on this computer, but you can still start or replay a tour yourself.

Limits and tips

  • When setup opens. It opens on the first start with no earlier Orkestra data. It opens at every start until you finish it, skip it or choose a project. If you quit in the middle, it resumes at the step you reached.
  • What setup saves. It saves your place and the default agent (only when you click Continue on the Default agent step). Back, Skip setup and the step bar do not save the agent. Choosing a project option or clicking Finish closes setup. Finish adds no project.
  • A fix that opens Settings. If a System check row in step 1 offers a fix that opens Settings, Orkestra closes setup, keeps your place and opens that Settings pane. Run setup again later if you want to continue.
  • Keys in setup. Press Enter, while no button has focus, to click Continue or Finish. Esc, the ✕ button, or a click outside the window opens the Skip setup? dialog. In the agent list, use the Up, Down, Home and End keys to change the selection.
  • Checklist visibility. After a new installation the checklist shows. On a computer that already used Orkestra before this feature, it is hidden. Use Show checklist in Settings to show it.
  • The entry goes away. The status bar entry disappears when you click Hide checklist or when all items are done.
  • Ticks can go away. Five items follow the current state: if you remove all projects, the item Add a project is open again. The other items are history and stay ticked: Launch an agent from a task, Open a file in the editor and the four items that also tick when you finish their tour.
  • Ready means signed in. The checklist item An agent is ready needs a signed-in agent. A Not checked sign-in does not tick it.
  • Automatic tour. On a new installation where Orkestra showed the setup window, one tour starts by itself after setup closes. It is the first tour you have not seen, in the order of the list above. At most one tour starts by itself at each start of Orkestra. On a computer that already used Orkestra before, no tour starts by itself. You can start or replay any tour yourself at any time.
  • Install help. The Install button in the Default agent step opens the install help in place of the list. It works like the one in System check.
  • Helm tour. The Helm tour is in the list only when Helm has an engine you can use.
  • Terminal budget protection tour. It needs a terminal on the workbench. It does not open the menu for you, turn protection on, change a limit or send anything to an agent. If you choose Next before you open the menu, the callout stays on the Terminal info button. When you open the menu, it moves to the section. The readings, limits, action and Message show only while the switch is on. The callout shows on top of the open menu, and clicks on the callout do not close the menu. A click elsewhere or Esc closes the menu as usual. Esc also ends the tour. See Budget protection and The terminal info menu.
  • Minimap navigation tour. It needs the minimap: the setting Show the canvas minimap is on and the workbench has a window. The tour moves nothing by itself. Your clicks and drags on the minimap work as usual while the callout shows. Esc during a Ctrl drag cancels only the move. See Workbenches and the canvas.
  • Callouts wait. A callout is hidden while the Settings window, a dialog or the setup window is open, and while the Orkestra window is hidden. It comes back when they close. A tour you start from Settings begins after you close Settings.
  • A control is missing. The tour waits two seconds for the control to appear. It opens the needed panel for you where it can. If the control of the first step is missing, the tour ends. If the control of a later step is missing, the tour skips that step. Orkestra shows no message in these cases.
  • Wait steps do not act for you. You do the action. Only a new success after the step began counts. If you go Back to a wait step, do the action again, or click Skip tour.
  • Esc ends a tour. Done ends it on the last step.
  • Tours from an agent. Helm or another agent can point at a control for you, show a short tour of its own, or start one of the eight tours. You use the same callout: Next, Back, Done, Skip tour and Esc. An agent tour never marks a tour as Seen, is never the automatic tour, and does not depend on the automatic-tour rules.
  • Your tour wins. An agent cannot replace a tour that you started, from the checklist or from Settings. A tour that you start replaces an agent tour. A newer agent tour replaces an older one.
  • An agent tour does not wait. If the Settings window, a dialog or the setup window is open, or the Orkestra window is hidden, when an agent tries to show its tour, the tour does not appear, also not later. The agent is told why and can try again. After its first callout shows, an agent tour waits like any other tour.
  • One workbench at a time. An agent tour points only at controls on the workbench that you see. To show a terminal on another workbench, the agent first brings that terminal into view.