Orkestra user guide

Orkestra overview

The Orkestra user guide: core ideas, screen map, first steps and glossary.

Quick starts

On this page

What Orkestra is

Orkestra is a desktop app for work with command-line coding agents, such as Claude Code, Codex, Cursor, OpenCode and Antigravity. Each agent runs in a real terminal. Orkestra puts these terminals on a canvas, next to your files, tasks and Git tools, and keeps them organized by project. You write a task, start an agent on it, watch many agents at once, review their changes and commit them. A built-in assistant, Helm, can do much of this for you when you ask in plain words. Orkestra keeps the layout of every window when you restart it. New here? Start with First steps, or pick a workflow in Common Orkestra workflows.

Core ideas

Project. A folder on your computer that Orkestra manages. A project has its own tasks, workbenches, terminals, worktrees, Helm chats and settings for Helm. Only one project is active at a time. You switch projects in the top bar. See Projects and the project switcher and Adding, creating, cloning and importing projects.

Workbench. One canvas of a project. A project has one or more workbenches, shown as tabs in the top bar. Each workbench keeps its own windows, its pan and its zoom. See Workbenches and the canvas.

Canvas window. Every window on a workbench: terminal, file, image, HTML page, task, diff, merge, commit and Git console. All windows share one frame: you move, resize, dock, focus, rename and close them the same way. See Canvas windows: move, resize, dock and focus.

Terminal. A canvas window that runs a program: a plain shell or a coding agent. A terminal has a name, a status dot and an info menu. After a restart a terminal comes back without its process, as a dormant terminal, and you reconnect it. See Terminal windows and Terminal states, reconnect and history.

Agent. A command-line coding program that runs in a terminal, for example Claude Code or Codex. A launcher is the Orkestra entry that starts one agent with its options; you set up launchers in Settings → Engines. Some Orkestra messages call an agent program a "harness". See Starting terminals and agents and Settings: task defaults and engines.

Agent status. Orkestra shows what each agent does with a status dot: Not started, Active, Working, Awaiting input, Finished, Sleeping or Error. The Agents panel lists all agents of all projects. See Agents panel and agent status.

Task. A unit of work on the ToDo board of a project: a title and a description, a status (To-Do, In Progress, Done), a type and an optional task group. You launch an agent on a task; the task text becomes the agent's first prompt. See ToDo: the task board and Task window.

Terminal group. A named, coloured frame around terminals on one workbench. You make one by hand, or Orkestra makes one when an agent starts another terminal. It is not the same as a task group on the ToDo board. See Terminal groups.

Worktree. A separate Git checkout of the project on its own branch, in its own folder. An agent can work in a worktree and not touch your main checkout. See Worktrees.

Helm. The assistant built into Orkestra. You ask it in plain words; it works through Orkestra's own tools (tasks, terminals, worktrees, schedules). Helm keeps chats per project and can keep memories across chats. See Helm assistant, Helm memory and Settings: Helm.

Routine. A standing instruction that Helm runs on a schedule, for example every night. Tasks and task groups can also have a schedule. See Scheduler and routines.

Session. One run of a terminal. Orkestra keeps a record of closed sessions, and a supported agent can resume its saved conversation. See Session history.

Approval request. A risky action that an agent asks for and that waits for your yes or no. See Approvals.

MCP server. The interface through which agents in Orkestra terminals, and tools outside Orkestra, control Orkestra. See Settings: MCP.

Screen map

Top bar (left to right) — see Window layout: top bar, sidebar and status bar

Left sidebar — the activity rail with one icon per module, and the Send feedback button.

Workbench canvas — the windows of the active workbench, and the minimap in the bottom-right corner — Workbenches and the canvas.

Helm — the round sparkle button at the bottom centre of the canvas, the bottom bar, or the side panel at the right edge — Helm assistant.

Status bar (bottom edge, left to right)

Windows over the app

Outside the window — Telegram, through a bot you pair in Settings → Remote — Remote control with Telegram.

All keys in one table: Keyboard shortcuts.

First steps

  1. Download Orkestra from the Linux downloads section. Packages are Linux-only: a .deb for Ubuntu and Debian, or an AppImage for supported systems. Orkestra requires a 64-bit Intel or AMD computer running Ubuntu 22.04, Debian 12, Fedora 35, or later. Install the .deb with sudo apt install ./orkestra_<version>_amd64.deb. For the AppImage, make the downloaded file executable and run it.
  2. Start Orkestra. After a .deb install, use the Orkestra entry in the application menu or the orkestra command. On a new computer the Set up Orkestra window opens. Its System check step shows which agents and tools are installed. See First-run setup, Getting started and tours and System check.
  3. Install and sign in to at least one agent. Use Install and Sign in in System check.
  4. Choose a Default agent. New tasks start with it.
  5. Add your first project: create a folder, clone a Git URL, open an existing folder or scan a folder. See Adding, creating, cloning and importing projects.
  6. Start an agent: click an agent button in the top bar, or create a task in ToDo and click its play button. See Starting terminals and agents.
  7. Watch the status dot of the terminal, or the Agents item in the status bar. An amber dot (Awaiting input) means the agent waits for you. Press Ctrl+Shift+A (Cmd+Shift+A on macOS) to bring it into view. See Agents panel and agent status.
  8. Review and commit the changes in Source Control. See Source control: changes and commits.

After the install, the Getting started checklist in the status bar tracks your first milestones and offers a short tour for each one.

Glossary

One term per concept. Every chapter uses these terms.

Term Meaning Chapter
Activity rail The strip of module icons at the left edge of the window. Window layout
Agent A command-line coding program (Claude Code, Codex, Cursor, OpenCode, Antigravity) that runs in a terminal. Some messages call it a "harness". Starting terminals and agents
Approval request A risky agent action that waits for your Approve or Deny. Approvals
Awaiting input The status of an agent that waits for you (amber dot). Agents panel and agent status
Bottom bar The floating Helm panel at the bottom centre of the canvas. Helm assistant
Budget protection Per-terminal limits on quota, cost or tokens, with an action when a limit is reached. Budget protection
Canvas The endless surface of a workbench that holds its windows. Workbenches and the canvas
Canvas window Any window on the canvas (terminal, file, image, HTML, task, diff, merge, commit, Git console). Canvas windows
Dock To snap a window edge to edge with another window. Canvas windows
Dormant terminal A terminal restored after a restart, with no process (also called a restored terminal). Its window says "Session not live". Terminal states, reconnect and history
Focus mode One window enlarged to about 80% of the screen over a dim backdrop. Canvas windows
Getting started checklist The status bar item with up to eleven first steps and their tours. First-run setup, Getting started and tours
Helm The assistant built into Orkestra. Helm assistant
Launcher An Orkestra entry that starts one agent with its own name, colour, arguments and variables. Set up in Settings → Engines. Settings: task defaults and engines
MCP server The interface through which agents and outside tools control Orkestra. Settings: MCP
Memory (Helm) A short lesson that Helm keeps across chats. Helm memory
Minimap The small map of all windows in the bottom-right corner of the canvas. Workbenches and the canvas
Module One panel of the left sidebar, for example ToDo or Files. Window layout
Notice card A small message card in the bottom-right corner. Feedback, errors and notices
Project A folder on your computer that Orkestra manages, with its own tasks, workbenches and terminals. Projects and the project switcher
Project switcher The project button in the top bar and its list. Projects and the project switcher
Recap A short summary of what a terminal did (Purpose, Done, State, Next). The terminal info menu
Reconnect Start a dormant or sleeping terminal again. Terminal states, reconnect and history
Remote control Use of Orkestra from Telegram through a paired bot. Remote control with Telegram
Routine A standing instruction that Helm runs on a schedule. Scheduler and routines
Session One run of a terminal; closed sessions can be restored. Session history
Shelf Orkestra's own store of changes that you set aside (not Git stash). Branches, log and shelf
Side panel Helm docked as a column at the right edge of the window. Helm assistant
Sleeping terminal A terminal whose process Orkestra stopped to save resources; the window and output stay. Terminal states, reconnect and history
Status bar The bar along the bottom edge of the window. Window layout
Status dot The dot that shows the status of a terminal or agent. Agents panel and agent status
Task A unit of work on the ToDo board. ToDo: the task board
Task group A named group of tasks on the ToDo board. ToDo: the task board
Terminal A canvas window that runs a shell or an agent. Terminal windows
Terminal group A named, coloured frame around terminals on one workbench. Terminal groups
Terminal ID The ID of one terminal window. It does not change when the terminal is renamed. Copy Terminal ID copies it as an orkestra://terminal/ link. The terminal info menu
Terminal-agent protocol The rules that Orkestra gives agents for one-line messages between terminals; agents get it as the terminal-agent-protocol skill. The preferred way for two running agents to work together. The terminal info menu
Tour A guided sequence of callouts that points at controls one by one. First-run setup, Getting started and tours
Usage limits The account limits of agents, shown in the status bar. Usage limits
Workbench One canvas of a project, shown as a tab in the top bar. Workbenches and the canvas
Worktree A separate Git checkout of the project on its own branch and folder. Worktrees