Tasks and schedules

Task window

Write the description of a task, set how it launches, plan a scheduled launch, link worktrees to it and see its sessions, all in one window on the canvas.

On this page

The task window is the detail page of one task. It is a window on the workbench canvas. You write the task text in it. You set the type, group and name of the task. You choose the agent, model and permission mode that the task uses. You plan a launch for a later time. You link worktrees to the task and open its sessions again.

Where to find it

The window floats on the canvas of the active workbench. A task has one window per workbench. Open the task again and Orkestra brings that window to the front. You open a task window from these places:

  • ToDo in the left sidebar: click a task row, or click the + button (tooltip "new task"), or right-click a group and click New task in group. See Tasks.
  • A terminal: open the Terminal info menu and click the title in the Task row. See The terminal info menu.
  • Scheduler in the left sidebar: click the arrow icon button of a scheduled task (tooltip "Open in task Schedule tab"). The window opens on the Schedule tab. See Scheduler and routines.
  • The Getting started list (button New task, see First-run setup, Getting started and tours) and an approval request for a task (button Open task details, see Approvals).

A window opened this way opens large, in focus mode, over a dim backdrop. Leave focus mode to see it on the canvas. See Canvas windows.

What you see

Title bar, from left to right (the frame is in Canvas windows):

  • Type mark — "◈" Task, "◉" Bug, "?" Question, "◇" Idea, "—" Note. An untyped task shows a blank.
  • Window name — the task name. Double-click it to rename the task (see Limits and tips). The new name shows on the ToDo board too.
  • Editor mode buttons (icon buttons, tooltips "Source", "Rich", "Preview") — only on the Description tab. See Markdown documents.
  • ● N running — a pill with the count of live terminals of the task. It shows only when N is more than 0, and only on the canvas, not in focus mode.
  • Focus button (tooltip "Focus (≈80% of screen)") and Close button (tooltip "Close task window").

Tab bar, below the title bar:

  • Description — the text of the task.
  • Settings — type, group, name and launch settings.
  • Schedule — two scheduled launches.
  • Worktrees & Terminals — the linked worktrees. A badge shows the count of live terminals.
  • History — the sessions started from the task. A badge shows the count of sessions.
  • Launch — a button with a play icon at the right end. It shows on every tab.

Description tab — the Markdown editor with its toolbar (Undo, Redo and the formatting buttons). It fills the window. An empty text shows "Start writing…". See Markdown documents.

Settings tab — one block, Task settings. - Type — buttons None, Task, Bug, Question, Idea, Note.

  • Group — a list with Ungrouped and the groups of the project.
  • Name — a text field, a disabled Auto button (tooltip "Generate name with an LLM (planned)") and the note "The task name is inserted into the launched agent's prompt." The hint says "currently derived from the description" or "set manually".
  • Default launch mode — buttons Current repository and Separate worktree.
  • Launcher — one button for each agent launcher. The chosen one is pressed.
  • Model — a list with Default (engine-managed), the models of the launcher and Custom model id…, and a reload icon button (tooltip "Reload model list").
  • Reasoning effort — a list with Default (harness-managed) and the levels, and a reload button. It shows only for a launcher that has an effort setting.
  • Permission mode — a list of the modes of the launcher and a reload button (tooltip "Reload permission modes").
  • Run automatically — a switch. The hint is "the prompt is sent and the agent starts immediately" (on) or "the prompt is only typed in — review it, then press Enter" (off).

Schedule tab — two blocks. Each header has a switch.

  • Scheduled launch (switch name "enable schedule") — Time, Repeat (Once, Every day, Weekdays, Weekends), Launcher, Model, Permission mode (hint "unattended runs usually need elevated access") and, only when Default launch mode is Separate worktree, Worktree (hint "reuse the last one or mint fresh each run"; Reuse last or Fresh each run).
  • Helm scheduled launch (switch name "enable helm schedule") — Time and Repeat only.

Worktrees & Terminals tab — one block, Worktrees & terminals.

  • Attach button (link icon) and New worktree button (plus icon), at the top right.
  • One card for each linked worktree: branch name, folder path, Open terminal or Launch (play icon), and an X icon button (tooltip "Detach worktree from task").
  • The Attach existing worktree menu opens under Attach. It lists the branch of each project worktree that is not linked to the task.

History tab — one block, Session history. Each row shows:

  • A dot (live sessions have a lit dot), the agent name with its mark (or "shell"), and the state "● running" or "closed".
  • A line such as "via single · 14m ago". The word after "via" is "single", "group launch", "manual" or "schedule".
  • Open (live session) or Restore (closed session).

How to

Open the window of a task

  1. Open ToDo in the left sidebar.
  2. Click a task row. Do not hold Ctrl or Cmd. (A click with Ctrl or Cmd selects the row.)

Result: the task window opens in focus mode on the Description tab.

Write the description of a task

Before you start, open the window of the task.

  1. Click in the editor on the Description tab.
  2. Type the text.

Result: Orkestra saves the text on every change. There is no Save button. While the name is "derived", it follows the first line of the text.

Undo or redo a change of the description

  1. Click Undo in the editor toolbar of the Description tab. Ctrl+Z (Cmd+Z on macOS) does the same.
  2. Click Redo to go forward. Ctrl+Y or Ctrl+Shift+Z (Cmd+Y or Cmd+Shift+Z on macOS) does the same.

Result: the text goes back or forward by one step. The task keeps up to 50 versions of the text.

Rename the task from the title bar

  1. Double-click the name in the title bar. (You can also move to the name with the keyboard and press Enter or Space.) A field opens with the name in it.
  2. Type the new name.
  3. Press Enter.

Result: the task has the new name. The title bar and the row on the ToDo board show it. The hint under Name in the Settings tab says "set manually". To get the derived name back, clear the field and press Enter: the name is again the first line of the description. Press Esc to cancel without a change. Clicking outside the field saves the name, as Enter does.

Change the name, type or group of a task

  1. Open the Settings tab.
  2. Type the new name in the Name field.
  3. Click a button in the Type row, for example Bug. Click None to remove the type.
  4. Open the Group list and choose a group, or Ungrouped.

Result: the title bar shows the new type mark and the new name. The hint under Name changes to "set manually". The task moves to its group on the board.

Choose how the task launches

  1. Open the Settings tab.
  2. Click Current repository or Separate worktree in Default launch mode.
  3. Click a button in Launcher.
  4. Open the Model list and choose a model, or keep Default (engine-managed).
  5. Open the Reasoning effort list and choose a level. Skip this step when the field is missing.
  6. Open the Permission mode list and choose a mode.
  7. Click the Run automatically switch to turn it on or off.

Result: Orkestra saves each choice at once. The Launch dialog starts with these values. See Starting terminals and agents.

Launch the task

  1. Click Launch in the tab bar.

Result: the Launch task dialog opens. If the window was in focus mode, Orkestra leaves focus mode first. Continue in Starting terminals and agents.

Plan a launch for a later time

  1. Open the Schedule tab.
  2. Click the switch in the header of the Scheduled launch block.
  3. Type a time in Time.
  4. Open the Repeat list and choose a value.
  5. Click a button in Launcher.
  6. Open the Model list and choose a model.
  7. Open the Permission mode list and choose a mode.

Result: a line shows under the fields, for example "Runs daily at 09:00 in a separate worktree, unattended (while the app is open)." The task shows in the Scheduler panel. To stop the plan, click the switch again: the fields turn grey and Orkestra keeps the values. See Scheduler and routines.

Plan a run in a Helm chat

  1. Open the Schedule tab.
  2. Click the switch in the header of the Helm scheduled launch block.
  3. Type a time in Time.
  4. Open the Repeat list and choose a value.

Result: a line says "… opens a new Helm chat in this project and runs the task there, unattended (while the app is open)." See Helm.

Create a worktree for the task

  1. Open the Worktrees & Terminals tab.
  2. Click New worktree.

Result: Orkestra creates a worktree named after the task and links it to the task. It then starts a terminal in that worktree with the launch settings of the task and the task text. The session also shows in the History tab.

Attach an existing worktree to the task

  1. Open the Worktrees & Terminals tab.
  2. Click Attach.
  3. Click a branch in the Attach existing worktree menu.

Result: the menu closes and a card for that worktree shows in the block. The worktree now shows in the Worktree list of the Launch dialog for this task.

Launch the task in a linked worktree

  1. Open the Worktrees & Terminals tab.
  2. Click Launch on the card of the worktree.

Result: the Launch dialog opens with Separate worktrees and that worktree already chosen. When a live terminal runs in the worktree, the card shows Open terminal instead. Click it to show that terminal on the canvas.

Detach a worktree from the task

  1. Open the Worktrees & Terminals tab.
  2. Click the X icon button (tooltip "Detach worktree from task") on the card.

Result: the card goes away. The worktree stays on disk and in the Worktrees panel.

Restore a closed session of the task

  1. Open the History tab.
  2. Click Restore on a row with the state "closed".

Result: the agent starts again. If the terminal is still on the canvas, Orkestra restarts it. If not, Orkestra opens a new terminal and resumes the saved session. A row with "● running" has Open instead: it shows the live terminal. See Session history.

Close the task window

  1. Click the Close button (tooltip "Close task window") in the title bar.

Result: the window leaves the canvas. The task and its text stay. No question appears, because Orkestra saves the text on every change.

States and messages

  • A task in Trash is read-only and shows This task is in the Trash; restoring it brings its editor and tabs back. A permanently deleted task shows Task removed and cannot be edited.
  • Attach is disabled when every project worktree is already linked. Empty Worktrees & Terminals and History tabs explain that there are no linked worktrees or launched sessions yet.
  • A history row offers Open for a live terminal and Restore for a closed session. The tooltip distinguishes reconnecting a terminal still on the canvas from reopening a saved session. A failed restore reports the reason.
  • Lists show loading… while they are read. If a model or permission list fails, use its reload control. If Rich editing is unavailable, the editor explains why; Source and Preview remain available.
  • Orkestra keeps the task window open if it cannot save description undo history. If saved recovery history cannot be read, the window reports that it is unavailable or unusable.

Limits and tips

  • No status control. The window cannot change the status of the task. Do it in the ToDo panel. See Tasks.
  • One name. The name in the title bar is the name of the task. Renaming it in the title bar and changing Name in the Settings tab do the same thing.
  • Derived name. Until you edit the name, it is the first line of the description. Orkestra removes a leading "#" or list mark and cuts the line at 80 characters. An empty text gives "Untitled task". After you edit the name, clear the field in the title bar and press Enter to make it derived again.
  • A task in Trash. The window of a task in Trash is read-only. It shows no editor and no tabs. The title bar name cannot be changed. Restore the task to work in the window again.
  • Saved at once. The text and every field of the Settings tab save at each change. The undo steps save a moment later and stay after you close the window. A close never asks about unsaved text: Orkestra first applies the edit that is still open in the editor.
  • New tasks start with the launch values of Settings → Task Defaults. Later changes there do not change existing tasks. See Settings: task defaults and engines.
  • Changing the launcher sets Model back to Default (engine-managed).
  • A new schedule starts with the values of Settings → Task Defaults. Its first time is one hour before the moment you opened the tab. A time that is not complete goes back to the last good value when you leave the field.
  • Open terminal shows any live terminal in that worktree, not only terminals of this task. The ● N running pill and the tab badge count live terminals of the task and of its worktrees.
  • The tab and the editor mode are not saved. After a restart, a window opens on Description in Rich mode. Position and size are saved.