Tasks

How tasks work

A task is a piece of work written down before anyone builds it. It has a title, a spec in Markdown, a status and a priority, and it belongs to one project.

Saving a task starts nothing: no agent runs and no worktree is created. When you are ready, the work happens in a thread, the task's execution thread, where you follow it like any other conversation.

Use a task to plan work you want to read and edit before an agent builds it, or to keep a backlog. An agent can also save a task for you when you want work noted for later instead of done now.

Create a task

From the Tasks view

1. Click Tasks on the sidebar's rail and choose New task, or press ⌘⇧N from anywhere.
2. Write a title. Under it, pick a priority and the project.
3. Write the spec below.
4. Choose Create task, or press ⌘↵.

The task is saved to Backlog and opens on its Overview. While you write, the draft is kept on your computer, so leaving the screen loses nothing.

From a thread

Choose Tasks in the thread's header, then Add. The new task is linked to the thread, belongs to its project and uses its location.

By an agent

Agents in a thread have task tools. Ask one to "add a task for the login redirect" and it saves the task with task_create. The task appears as a card in the transcript and under the thread's Tasks. Agents can also list, read and update tasks in the project. If the thread already has a task with the same title, or with mostly the same words, OpenOrc returns that task instead of saving a second one.

Write the spec

The spec lives on the task's Overview tab, in an editor that saves Markdown.

• Type / to insert a heading, a list, a checklist, a quote, a code block, a divider or an image.
• Select text to make it bold or italic, or to add a link.
• Paste or drop images into the spec.
• Choose Markdown to edit the source, and Rich text to go back.

Changes save shortly after you stop typing, and ⌘S saves at once. The footer says Saved when the task is up to date. Below the spec, Labels takes a comma-separated list. Further down are the task's comments (see Task discussions), its Execution settings, a short history and Delete task. Deleting a task removes it and its discussion; its thread keeps its messages and changes.

Status and priority

Change a status from the status menu on the Overview, or click a task's status icon in the Tasks list. When an agent starts the work, the task moves to In progress, and the agent records later progress with its task tools, so a task can reach Review or Done without you. You can always set the status yourself.

Priority is one of No priority, Low, Medium, High or Urgent. The Tasks list shows it as an icon at the start of each row.

The task's tabs

Changes, Commits and Memory show the panel of the task's thread, so they stay empty until the task has one. Changes and Commits say No execution yet until then.

Start a task

1. Choose Open thread at the bottom of the task's Overview. In the Tasks list, a backlog task's row has the same button as a message icon.
2. OpenOrc opens the task's thread. If the task has none yet, it reuses the thread the task came from when that thread is idle and works in the same place. Otherwise it creates a thread named after the task, with the task already written in the message box.
3. Check the model in the message box, add any direction, and send. Opening a thread starts nothing; the agent starts when you send.

The work runs in that thread's folder: your checkout, or a worktree of the thread's own. When OpenOrc creates a thread for the task, the task's Execution location decides where it works: Local checkout or Worktree, under Execution settings on the Overview. A new task takes the location of the thread it came from, or else your New thread workspace setting. Once the thread has started, changing the location moves the thread and its uncommitted changes. See Git and worktrees.

You can also start the work from the task's comments, by asking a model to build it. See From discussion to work.

The Tasks list

• Active, Done and Archived split the list. Active holds every task that is neither done nor archived.
• On Active, the status menu narrows the list to one status. Each option shows how many tasks it has.
• Filter tasks… matches titles and labels.
• The project chip in the header switches between one project and All projects. With all projects, each row names its project.
• Tasks are grouped by status. Click a group's heading to fold it.

The list works from the keyboard: j and k, or the arrow keys, move between tasks, and ↵ opens one.

Next steps