Projects and workbenches

Projects and the project switcher

Switch between projects, organize them in groups, edit their details, IDE links and file-opening rules, and remove them.

On this page

A project is a folder on your disk that Orkestra manages. Each project has its own task board, workbenches, terminals and worktrees. It also has its own Helm notes and Helm chats. Only one project is active at a time. Use the project switcher to change the active project, to sort projects into groups, to edit them and to remove them. To bring a new folder into Orkestra, see Adding, creating, cloning and importing projects.

Where to find it

The switcher is in the top bar, on the left, next to the Orkestra mark. A row of small project marks sits on its left. The project button sits on its right. Click the project button to open the list of projects.

What you see

  • Recent projects (a row of small marks) — up to four shortcuts to the projects you used last. Each mark shows the project's initials. The row is hidden when there is no other project.
    • Oldest is on the left. The project you used just before this one is on the right, next to the project button.
    • The active project is not in this row.
    • Hover a mark to see the project name and its folder path.
  • Project button — shows the active project:
    • A mark with up to two initials of the project name.
    • The project name.
    • The current Git branch name, when the folder is a Git repository.
    • A down-arrow.
    • With no project, the button shows No project.
  • Switch project (the list that opens from the project button), from top to bottom:
    • Search projects field.
    • New group button (a + icon) — creates a project group.
    • Add project button (a folder icon with a plus) — opens the add-project dialog.
    • A red message line, only after a failed action.
    • Sections, in this order. A section appears only when it has content.
      • Pinned — pinned projects, newest first.
      • Projects — your groups, with the projects inside them.
      • Recent — projects that are not pinned and not in a group, newest first.
    • Open… button and New project button in the footer.
  • Group row — a coloured mark, the group name and a number badge. The badge counts all projects in the group, including projects in nested groups. Nested groups are indented. Click the row to expand or collapse it.
  • Project row — one row per project:
    • The mark and the project name.
    • The folder path under the name, or "no location set".
    • During a search, the text "in Group › Subgroup" for a grouped project.
    • A pencil icon (tooltip "Edit project"). It shows when you point at the row.
    • At the right end, a pin icon (tooltip "Pin" or "Unpin"). It shows when you point at the row, and it stays visible for a pinned project.
    • The active project shows a check mark instead of the pin icon.
  • Project row menu (right-click a project row or focus it and press Shift+F10): Open project in <IDE> or Link an IDE…, then a divider, Edit project…, Project details…, Move to…. The open row shows a short IDE monogram. A linked editor that is missing from a loaded editor list shows <IDE> — not found and Relink IDE…; an unsupported system shows Not available on this system. Link an IDE… and Relink IDE… open Edit project with the IDE field focused. Press Esc to close the menu and return focus to the project row.
  • Group row menu (right-click a group row): Rename…, Delete group, Move to….
  • Move to menu — Move to top level, then one entry per group, shown as a tree: Move to “<group name>”.
  • Edit project dialog — fields Project name, IDE, the group File opening, Location on disk and Helm notes. The IDE field has Rescan editors, Choose editor…, and Unlink when its saved editor is missing. Footer buttons: Delete, Cancel, Save.
    • File opening says what a double-click or Enter on a file in the Files panel does for this project. Default (hint "When no rule matches") is a row of three choices: Orkestra (the file opens in an Orkestra window, as before), Default application (the program your system uses for the file) and Project IDE (the IDE in the IDE field). Rules (hint "Extensions, comma separated") lists exceptions: each rule has an Extensions field (for example ".png, .jpg"), an Action list with the same three choices, and a remove button (tooltip "Remove rule 1", 2, …). Add rule adds a row. With no rules the list says "No rules". A rule beats the default; when two extensions match a file name, the longer one wins (".d.ts" beats ".ts").
    • While IDE says None, Project IDE is grey and a line says "No project IDE — Link IDE…". Link IDE… moves the cursor to the IDE field. Choose an IDE there and Project IDE works at once. If Project IDE was the default and you set IDE back to None, the default changes to Orkestra.
  • <project name> — details dialog — fields Display name, Helm notes and Location. Footer buttons: Cancel, Save.
  • New group dialog and Edit group “<name>” dialog — fields Name, Parent group and Tab colour (eight colour swatches). Footer buttons: Cancel and Create group (new) or Save (edit).
  • Remove <project name>? dialog — see Remove a project.

How to

Switch to another project

  1. Click the project button in the top bar.
  2. Click a project row in the list.

Result: The list closes. The project button shows the new project. The task board, workbenches and Helm chat of that project appear. The project you left moves to the right end of the recent marks.

Go back to a recent project

  1. Look at the recent marks on the left of the project button.
  2. Hover a mark to read the project name and path.
  3. Click the mark.

Result: The project becomes active. The project you left moves to the right end of the row.

Find a project

  1. Click the project button in the top bar.
  2. Type in the Search projects field.
  3. Click the project row you want.

Result: The list shows only matching projects. The search ignores letter case. It matches the project name, the folder path and the group name. A group name that matches shows all projects of that group. The matching letters in a name are highlighted. Results are in two flat sections, Pinned and Projects. Group rows are hidden during a search.

Pin or unpin a project

  1. Click the project button in the top bar.
  2. Point at a project row that is not the active one.
  3. Click the pin icon at the right end of the row.

Result: A pinned project moves to the Pinned section at the top, out of its group. Click the icon again (tooltip "Unpin") to return it.

Rename a project or edit its Helm notes

  1. Click the project button in the top bar.
  2. Point at a project row.
  3. Click the pencil icon (tooltip "Edit project"). Or right-click the row and choose Edit project….
  4. Change the text in the Project name field.
  5. Optional: choose an editor in IDE, or select None to unlink it.
  6. Optional: in File opening, choose the Default (Orkestra, Default application or Project IDE). Click Add rule, type extensions such as ".png, .jpg" and choose an Action to send those files somewhere else.
  7. Change the text in the Helm notes field. These notes go to Helm as standing instructions for this project.
  8. Click Save.

Result: The dialog closes. The new name shows in the list and on the project button. The IDE link and the File opening settings are saved with the project. Your folder on disk keeps its old name.

You can also open this dialog from the Files panel: right-click a file and choose File opening settings…. The cursor then starts on the Default choice.

Attach a folder to a project that has no location

  1. Click the project button in the top bar.
  2. Right-click the project row and choose Project details…. The row path says "no location set".
  3. Type a folder path in the Attach location field. Or click the folder icon next to it (tooltip "Choose folder…").
  4. Click Attach location.

Result: Orkestra checks the folder. The dialog then shows the folder path under Location, and the project has a location. If the folder is refused, a red message shows under the field (for example "No folder at <path>.").

Read the details of a project and copy its path

  1. Click the project button in the top bar.
  2. Right-click the project row and choose Project details….
  3. Click the copy icon next to the path under Location (tooltip "Copy path").

Result: The text "Path copied" appears. The path is in your clipboard.

Create a project group

  1. Click the project button in the top bar.
  2. Click the New group button (the + icon).
  3. Type a name in the Name field.
  4. Choose a group in the Parent group list, or keep Top level.
  5. Click a colour swatch under Tab colour. The dialog starts with the next unused colour.
  6. Click Create group.

Result: The new group appears in the Projects section with a count of 0. A group with a parent appears inside that parent.

Rename a group, change its colour or its parent

  1. Click the project button in the top bar.
  2. Right-click a group row and choose Rename….
  3. Change the Name, the Parent group or the Tab colour.
  4. Click Save.

Result: The group row shows the new name, colour and place.

Move a project into a group

  1. Click the project button in the top bar.
  2. Right-click the project row and choose Move to….
  3. Click Move to “<group name>”. To take the project out of a group, click Move to top level.

Result: The project shows inside the group. A moved project is not pinned any more. A project moved to the top level shows in Recent.

Move a group into another group

  1. Click the project button in the top bar.
  2. Right-click the group row and choose Move to….
  3. Click the new parent group, or Move to top level.

Result: The group and everything in it move. The group goes to the end of the new parent's list.

Expand or collapse a group

  1. Click the project button in the top bar.
  2. Click a group row.

Result: The projects and groups inside it show or hide. Orkestra keeps this state after a restart.

Delete a group

  1. Click the project button in the top bar.
  2. Right-click the group row and choose Delete group.

Result: The group and all groups inside it disappear at once. There is no confirmation. No project is deleted. The projects move to Recent, or stay in Pinned if they were pinned.

Remove a project

  1. Click the project button in the top bar.
  2. Point at the project row.
  3. Click the pencil icon (tooltip "Edit project").
  4. Click Delete in the footer of the Edit project dialog.
  5. Read the text in the Remove <project name>? dialog.
  6. Click Remove project.

Result: The project leaves Orkestra. Its folder and files stay on your disk. If the project was active, another project becomes active. If no project is left, the project button shows No project.

What happens, exactly:

  • The dialog says: "<project name> is removed from Orkestra. The files on disk at <path> are kept."
  • Orkestra also closes the terminals of the project. It removes the tasks, workbenches, windows, Helm chats and routines of the project from Orkestra.
  • Orkestra saves a recovery copy of unsaved file edits before it removes the project.
  • Worktree folders stay on disk, unless you tick the box in the next recipe.

Remove a project together with its worktrees

  1. Open the Remove <project name>? dialog as in the recipe above.
  2. Tick the box Also remove <number> managed worktree(s). This box shows only when the project has worktrees.
  3. Read the line under the box: "deletes <paths> from disk — uncommitted changes are lost".
  4. Click Remove project and worktrees.

Result: The project leaves Orkestra. The folders of its managed worktrees are deleted from disk. The project folder stays. See Worktrees.

Add a project

  1. Click the project button in the top bar.
  2. Click the Add project button (folder icon with a plus), the New project button or the Open… button.

Result: A dialog opens. The steps for each way to add a project are in Adding, creating, cloning and importing projects.

States and messages

  • No projects yet — use Create new, Clone from URL, Open existing folder or Scan a folder to add one. No projects match “<text>” means the search found no results.
  • No project means none is active. A project marked no location set has no folder yet; open Project details… to attach one.
  • A red line in the switcher reports the last failed project or group action. Close the switcher to clear it. In group dialogs, a red message means the parent group is missing or the move is invalid. The Move to and Parent group menus disable the current group and its descendants to prevent moving a group into itself.
  • In Edit project, an attached location is fixed. For a project without a folder, choose a valid path under Location on disk. Save stays disabled if the name is blank, Helm notes exceed the limit, or a file-opening rule is invalid. Rules need at least one extension; duplicates and paths or patterns such as *.png are rejected. Extensions are normalized when you leave the field. A Project IDE rule remains saved without a linked IDE, but matching files cannot open until you link one.
  • If a saved editor is no longer detected, it remains selected with Not found; use Unlink to remove it. Rescanning does not replace the saved editor.
  • Helm notes allow at most 2,048 bytes. The counter turns red and Save is disabled above that limit.
  • Project details asks you to choose a folder when none is attached. An invalid or unreadable folder is rejected with a reason. An attached location is fixed; move the folder on disk and add it again to change it.
  • During removal, Removing… disables the dialog buttons. If removal stops to preserve unsaved file recovery, the project remains. Removal may also wait if a person controls a terminal through Telegram; try again after the displayed wait intervals. Removed, with one leftover means the project was removed but one or more worktree folders could not be deleted; Open Worktrees shows them.

Limits and tips

  • A project location is fixed after you attach it. The Edit project dialog and the details dialog cannot change it.
  • Renaming a project or a group changes only the name in Orkestra. It does not rename any folder.
  • Groups only organize the list. They have no effect on the files on disk.
  • The mark colour comes from the project's place in the list. The initials come from the project name. You cannot change either.
  • Pinned and Recent are always in order of last use. Inside a group, projects are also in order of last use. The list has no drag and drop and no manual order. Use Move to… to change the place of a project or a group.
  • Moving a project with Move to… unpins it. Pin it again if you want it in Pinned.
  • Click outside the list or press Escape to close it. The search text is cleared when the list closes.
  • Press Escape in the Edit project dialog to cancel it. Click Save or press Enter in the Project name field to save. The Default choice is one stop for the Tab key; use the Left and Right arrow keys to change it. The round close button at the top right of the dialog is skipped by Tab: use Escape or Cancel.
  • Helm chats belong to one project. When you switch project, Helm shows the latest chat of the new project. See Helm.