Common Orkestra workflows

Choose a workflow below and follow its links to the instructions for each step. The overview glossary explains the terms used here.

Start my first agent after I install Orkestra

When to use: the first time you open Orkestra on a computer.

1. Let the Set up Orkestra window check your computer, then click Continue — see First-run setup, Getting started and tours.
2. Install an agent and sign in to it, if the check shows it missing or signed out — see System check and System check.
3. Choose the default agent for new tasks — see First-run setup, Getting started and tours.
4. Add your first project — see Adding, creating, cloning and importing projects.
5. Click an agent button in the top bar to start it — see Starting terminals and agents.

Result: a terminal window on the canvas runs the agent in your project folder. The Getting started checklist in the status bar shows your progress.

Run an agent on a task in its own worktree and review its changes

When to use: you want an agent to work on one job without touching your main checkout.

Before you start, the project needs a Git repository with at least one commit. If it has none, initialize Git, add a file, then stage and commit it in Source Control; worktrees need a commit to branch from. See Worktrees.

1. Create a task and write what the agent must do — see ToDo: the task board and Task window.
2. Open the Launch dialog from the play button of the task row — see Starting terminals and agents.
3. Choose Separate worktrees and launch — see Starting terminals and agents.
4. Wait until the status dot of the terminal shows Finished or Awaiting input — see Agents panel and agent status.
5. In Source Control, choose the worktree in the worktree list — see Source control: changes and commits.
6. Open the diff of each changed file — see Source control: changes and commits.
7. Stage the files and commit — see Source control: changes and commits.
8. Merge the worktree branch into your branch from the branch menu — see Branches, log and shelf.
9. Remove the worktree when you are done — see Worktrees.

Result: the agent's work is committed and merged, and the worktree folder is gone.

Find out which agent needs me

When to use: many agents run and you want to answer the ones that wait.

1. Look at the Agents item in the status bar. The awaiting number shows how many agents wait — see Agents panel and agent status.
2. Press Ctrl+Shift+A (Cmd+Shift+A on macOS) to bring the next waiting agent into view — see Agents panel and agent status.
3. Or open the Agents panel and click a chip in the attention rail — see Agents panel and agent status.
4. Type your answer in the terminal — see Terminal windows.

Result: the agent goes on with its work, and its status dot changes from Awaiting input.

Bring my agents back after I restart Orkestra

When to use: you quit Orkestra and start it again.

1. Look at the terminals: each one says Session not live — see Terminal states, reconnect and history.
2. Click the saved text of one terminal to reconnect it — see Terminal states, reconnect and history.
3. Or reconnect all terminals of the workbench with the lightning-bolt button in the top bar — see Terminal states, reconnect and history.
4. For a terminal that you closed before the restart, use Restore in Session history — see Session history.

Result: the agents run again. A supported agent resumes its saved conversation.

Run agents on several tasks at once

When to use: you have a list of jobs for agents.

1. Put the tasks in one task group — see ToDo: the task board and ToDo: the task board.
2. Set the launch settings of each task — see Task window.
3. Launch the whole group — see ToDo: the task board. Or select tasks and launch them together — see ToDo: the task board.
4. Watch them in the Agents panel — see Agents panel and agent status.

Result: one terminal opens for each task. Max concurrent agents in Settings paces the start — see Settings: the window, appearance, terminal, workbench and notifications.

Keep many terminals in order on the canvas

When to use: the canvas is crowded with terminals.

1. Select related terminals with Ctrl+click (Cmd+click on macOS) — see Terminal groups.
2. Group them — see Terminal groups.
3. Dock windows edge to edge — see Canvas windows: move, resize, dock and focus.
4. Click Tidy windows — see Workbenches and the canvas.
5. Move work to a second workbench when one canvas is not enough — see Workbenches and the canvas.

Result: related terminals sit together in named groups, and no window overlaps another.

Give an agent a file, a task or a worktree to work with

When to use: you want to point an agent at something in Orkestra without typing paths.

1. Open Files, ToDo, Worktrees or Session history in the left sidebar — see Window layout.
2. Drag the item into the terminal of the agent — see Terminal windows.
3. Or copy a reference to a terminal or a group and paste it — see The terminal info menu and Terminal groups.

Result: the agent's input holds a path or an Orkestra link. Press Enter in the terminal to send it.

Review and commit what an agent changed

When to use: an agent finished and you want to keep its work.

1. Open Source Control and the Commit tab — see Source control: changes and commits.
2. Open the diff of a file — see Diff, merge, commit and Git console windows.
3. Discard a change you do not want — see Source control: changes and commits.
4. Stage the files you keep — see Source control: changes and commits.
5. Let Helm write the commit message, or type it — see Source control: changes and commits.
6. Commit, or commit and push in one step — see Source control: changes and commits.

Result: the commit is in the branch; with push, it is on the remote too.

Resolve a merge conflict

When to use: a merge or rebase stops with conflicts.

1. Read the banner at the top of the Commit tab — see Source control: changes and commits.
2. Open the conflicted file in the merge window — see Diff, merge, commit and Git console windows.
3. Choose a side for each conflict, then click Save & Stage — see Diff, merge, commit and Git console windows.
4. Continue the merge or rebase — see Source control: changes and commits.

Result: the merge or rebase completes. To give up instead, abort it — see Source control: changes and commits.

Ask Helm to do the work for me

When to use: you prefer to say what you want in plain words.

1. Open Helm with the sparkle button or Ctrl+J (Cmd+J on macOS) — see Helm assistant.
2. Type your request and send it — see Helm assistant.
3. Answer a permission card if Helm shows one — see Helm assistant.
4. Read what Helm did in its steps — see Helm assistant.

Result: Helm creates the tasks, terminals or worktrees that you asked for. You see them in the app.

Run a job for me every night

When to use: you want Helm to repeat an instruction on a schedule.

1. Open Scheduler and create a routine with a prompt and a time — see Scheduler and routines.
2. Choose which tools the routine may use — see Scheduler and routines.
3. If the routine must open terminals or launch agents, turn on the matching unattended-run switch — see Settings: Helm.
4. Read the run history the next day — see Scheduler and routines.

Result: Helm runs the routine at the set time while Orkestra is open. To launch a task on a schedule instead, see Task window.

Control my agents from my phone

When to use: you are away from your computer and Orkestra keeps running.

1. Store a Telegram bot token in Settings → Remote — see Remote control with Telegram.
2. Pair your phone and click Apply — see Remote control with Telegram.
3. In Telegram, send /overview to see every live terminal — see Remote control with Telegram.
4. Open a terminal card and read its output — see Remote control with Telegram.
5. Send text to the terminal, or talk to Helm — see Remote control with Telegram and Remote control with Telegram.

Result: you follow and steer your agents from Telegram. Approval requests can also be answered there — see Approvals.

Approve or deny a risky action that an agent asks for

When to use: the Approvals item in the status bar shows a number.

1. Open the Approvals list — see Approvals.
2. Open the request and read who asks and what it wants to do — see Approvals.
3. Look at the terminal or the task behind it, if you need to — see Approvals.
4. Click Approve once or Deny — see Approvals.

Result: the action runs, or the agent receives a refusal. To change when Orkestra asks, see Approvals.

Make two of my agents work together

When to use: two agents run at the same time and must share work, for example one writes code and one reviews it.

1. Give both agents the Orkestra tools before you start them — see Settings: MCP.
2. Start the two agents — see Starting terminals and agents.
3. Copy the terminal ID of one agent and give it to the other agent with a coordination instruction and the terminal-agent-protocol skill — see The terminal info menu.
4. Watch both terminals. Optional: group them so that they stay together — see Terminal groups.

Result: the agents send one-line messages into each other's terminal input and report back to you. This is the preferred way for agents that work together now.

Stop an agent before it uses up my plan limit

When to use: an agent runs alone and you want a safety stop.

1. Check how much of each limit you have used — see Usage limits.
2. Turn on budget protection for the terminal — see Budget protection.
3. Set the limit of each reading — see Budget protection.
4. Choose what happens at the limit: a message or Force sleep — see Budget protection.
5. Optional: replay the Terminal budget protection tour to see these controls one by one — see First-run setup, Getting started and tours.

Result: when a reading reaches its limit, Orkestra sends your message to the agent or puts the terminal to sleep. Wake it later — see Terminal states, reconnect and history.

Connect an outside tool to Orkestra

When to use: a coding tool outside Orkestra must create tasks or read terminals in Orkestra.

1. Turn on the external MCP server — see Settings: MCP.
2. Copy a client configuration for your tool — see Settings: MCP.
3. Paste it into the MCP configuration of that tool.
4. Allow or block single tools for outside callers — see Settings: MCP.

Result: the outside tool connects with its token and uses the tools you allowed. Risky actions can still ask for your approval — see Approvals.

Get back unsaved edits after Orkestra closed

When to use: you edited a file and Orkestra closed before you saved.

1. Start Orkestra. The file window comes back at its place — see File, image and HTML windows.
2. Read the notice "Recovered your unsaved draft" and keep the draft — see File, image and HTML windows.
3. Save the file — see File, image and HTML windows.

Result: your edits are on disk. A task description needs no save: Orkestra keeps it as you type — see Task window.

Add many repositories at once

When to use: you keep many Git repositories in one folder.

1. Open the Add project dialog and choose Scan a folder for repositories — see Adding, creating, cloning and importing projects.
2. Import them as separate projects or as one project group — same recipe.
3. Arrange the projects in groups in the project switcher — see Projects and the project switcher.

Result: every repository is a project, and the project switcher lists them in your groups.