# Tasks





<DocVideo src="features/tasks/parallel-tasks" alt="New tasks branching off the main lane and running side by side while Main keeps going, until each one is Ready" width="1000" height="560" maxWidth="800" />

## What is a Task? [#what-is-a-task]

A task gives you a fully isolated sandbox to work on your project — completely separate from main version. Each task carries its own conversation history and session, so context never leaks between workstreams. You can start any task in [**Build Mode**](/docs/features/build-mode) or [**Plan Mode**](/docs/features/plan-mode), and create as many as your project needs. The **Tasks Panel** gives you a bird's-eye view of all tasks within a project, organized in one place.

### Task Lifecycle [#task-lifecycle]

Tasks move through a defined set of states as work progresses. Adding a new task from the Tasks Panel starts it in **Active** state immediately. To begin in **Draft** first, create the task from the Kanban view.

<SpinnerStyles />

<Steps>
  <Step>
    **Draft** *(optional)* — stage the task without starting it.

    <DraftTaskCard />
  </Step>

  <Step>
    **Selected** *(idle)* — the task is open but the agent is not running.

    <CurrentTaskCard />
  </Step>

  <Step>
    **Active** — agent is building in its own isolated sandbox.

    <ActiveTaskCard />
  </Step>

  <Step>
    **Ready** — task is complete and waiting to be merged.

    <ReadyTaskCard />
  </Step>

  <Step>
    **Merged** — changes are part of your main version.

    <MergedTaskCard />
  </Step>
</Steps>

<Callout type="warn">
  Task states are one-directional, except that transitions between ready and active are supported in both directions.
</Callout>

## Creating a Task [#creating-a-task]

Click **Add task** in the Tasks Panel to get started. Two paths are available depending on whether you want to begin immediately or stage the work first.

<DocImage src="features/tasks/new-task-options" alt="Add task menu open in the Tasks Panel with New Task and Draft Task options" width="480" height="352" />

### New Task [#new-task]

Describe what you want to build in the message box and send. The task goes **Active** immediately and Ideavo begins preparing its isolated sandbox.

### Draft Task [#draft-task]

Drafts let you stage work without starting it — useful when the task isn't ready to run or you want a teammate to kick it off later.

<DocVideo src="features/tasks/draft-to-active" alt="Writing a draft task, parking it in the Draft column, then starting it so the card moves to Active on the board" width="1000" height="560" maxWidth="800" />

<Steps>
  <Step>
    **Title and description** — Enter a title and an optional description. For existing drafts you can **Save** any changes or **Start** directly from here.

    <Callout type="info">
      The description is for context only — it is not sent to the agent. To use it as the starting prompt, check **Use description as prompt** in the next step.
    </Callout>
  </Step>

  <Step>
    **Confirm the prompt** — Review or edit the prompt the agent will use. Check **Use description as prompt** to carry it over automatically, then hit **Proceed**. The draft goes **Active** and execution begins.
  </Step>
</Steps>

## Kanban Board [#kanban-board]

The board organizes all tasks by state — **Draft**, **Active**, **Ready**, and **Completed** — giving you a clear picture of where every workstream stands at a glance. On desktop, open it from the **View Board** button at the bottom of the Tasks Panel.

<DocImage src="features/tasks/kanban-board" alt="Kanban board with Draft, Active, Ready and Completed columns of tasks, next to the Tasks Panel with View Board selected" width="1536" height="660" />

On mobile, the board is accessible directly from the board icon in the top bar. Use the **dropdown** at the top to switch between states — **Draft**, **Active**, **Ready**, and **Completed** — viewing one panel at a time. Hit the **+** button next to the dropdown to add a new draft task.

<div
  style="{
  display: &#x22;flex&#x22;,
  gap: &#x22;1rem&#x22;,
  alignItems: &#x22;center&#x22;,
  justifyContent: &#x22;center&#x22;,
}"
>
  <DocImage src="features/tasks/mobile-board-icon" alt="Board icon in the mobile top bar" width="748" height="1332" maxWidth="280" />

  <span style="{ flexShrink: 0, fontSize: &#x22;1.5rem&#x22; }">
    →
  </span>

  <DocImage src="features/tasks/mobile-kanban" alt="Kanban board on mobile showing the Active state in a dropdown, a + button, and the Main version above the active tasks" width="748" height="800" maxWidth="280" />
</div>

<Callout type="info">
  To return to your main version — whether you've just created a new task or are
  currently inside another task — open the Kanban board and tap the first entry
  in the **Active** column. That item always represents your main version.
</Callout>

## Managing a Task [#managing-a-task]

Right-click a task in the Tasks Panel (or long-press on mobile) to open its context menu.

<DocImage src="features/tasks/task-context-menu" alt="Task context menu showing Mark Ready, Rename, and Delete options" width="480" height="400" />

* **Mark Ready / Mark Active** — manually move the task between **Active** and **Ready** states. Use this when you want to signal a task is done without waiting for the agent, or pull it back to active to continue work.
* **Rename** — update the task title at any point.
* **Delete** — permanently removes the task and its sandbox. This cannot be undone.

## Merging a Task [#merging-a-task]

The **Merge** button appears in the task toolbar once a task reaches **Ready** state — meaning the agent has finished and is no longer running. It is disabled at all other times.

<DocImage src="features/tasks/merge-button" alt="Merge button in the task toolbar, next to the GitHub icon" width="248" height="88" />

The GitHub icon next to the button reflects your repository connection status at a glance.

Clicking **Merge** opens a panel that walks you through the merge flow. If no remote repository is connected, the panel prompts you to connect one first before proceeding.

### Connect Repository [#connect-repository]

If your project is not linked to a remote repository, clicking **Merge** shows the **Connect Repository** panel instead of the pre-flight check.

<DocImage src="features/tasks/merge-connect-repo" alt="Connect Repository popover under the Merge button, with a Click here link to connect a GitHub repository" width="576" height="320" />

Click **Click here** in the panel to open the [GitHub integration flow](/docs/features/github#2-create-a-repository) and link a remote repository. Once your project is connected, clicking **Merge** again will proceed to the pre-flight check.

### Check Merge [#check-merge]

This pre-flight step runs entirely inside your **task sandbox**. Ideavo fetches the latest default branch from the remote, rebases your task branch on top of it, and inspects the result.

* **No conflicts** — the rebased branch is pushed back to the remote and the panel advances to **Ready to Merge**.
* **Conflicts detected** — the conflicting files are listed. Hit **Resolve with Agent** to close the panel and hand the problem straight to the AI in your current session with a pre-filled prompt. Pick your preferred model, send, and once the agent finishes hit **Re-check**.

### Merge Changes [#merge-changes]

Because the pre-flight already pushed a clean, rebased branch to the remote, this step has nothing to reconcile. Ideavo checks out the default branch on the **main sandbox**, pulls the latest remote, and merges the task branch in with a no-fast-forward merge commit. The result is pushed, the task is marked **Merged**, and a system message summarising the merge is added to your main session — leaving a conflict-free history throughout.

<Callout type="warn">
  The merge button is only enabled when the task is in **Ready** state and
  neither the task nor your main version is currently running.
</Callout>

Try the full flow below — use the toggle to simulate both the success and conflict paths.

<TaskMergeMock />

## What Can You Do with Tasks? [#what-can-you-do-with-tasks]

Tasks work for any project. Here are a few patterns where they shine:

* **Explore multiple UIs** — Spin up a separate task for each design direction, compare the results, and merge the winner. No branch switching, no lost work.
* **Break down complex changes** — Split a large feature into sequential tasks — data model first, then API, then frontend — so each piece is reviewable and mergeable on its own.
* **Experiment without risk** — Try a risky refactor or architectural spike in isolation. If it doesn't pan out, delete the task and your main version is completely untouched.
* **Ship features in parallel** — Run independent workstreams simultaneously so one feature never blocks another.

## FAQ [#faq]

<Accordions>
  <Accordion title="Can I run multiple tasks at the same time?">
    There is no hard limit on how many tasks you can create or run in parallel. That said, running 4–6 tasks simultaneously is not recommended. Every active task keeps an agent running until it is deleted, so memory usage adds up quickly — how many you can comfortably run depends on your machine's specs.
  </Accordion>

  <Accordion title="Do tasks share context with each other or my main version?">
    No. Each task has its own isolated conversation history and session. Context never leaks between tasks or back to your main version.
  </Accordion>

  <Accordion title="Can I go back from Ready to Active?">
    Yes. Transitions between **Ready** and **Active** are supported in both directions. All other state transitions are one-directional.
  </Accordion>

  <Accordion title="What happens if there are merge conflicts?">
    The pre-flight check during merge will detect conflicts and list the affected files. Hit **Resolve with Agent** to hand the problem to the AI in your current session, then hit **Re-check** once it's done to proceed.
  </Accordion>

  <Accordion title="Who can manage tasks?">
    All collaborators can create, delete, and update tasks. Viewers have read-only access and can see tasks but cannot make changes.
  </Accordion>

  <Accordion title="Is there any extra cost to run tasks?">
    No. Tasks are included as part of your plan with no additional charges.
  </Accordion>

  <Accordion title="Can the agent make mistakes?">
    Yes. Agents are not perfect and can occasionally produce incorrect or incomplete changes. Use the **Ready** state as a checkpoint to review the work before merging it into your main version.
  </Accordion>
</Accordions>
