# Tasks and the task main version

Think of a task as **a group chat**: several chats push the same larger piece of work forward **in parallel**, and once they're all done the changes merge into the default branch together. It exists to fix the inefficiency of chats — the AI works one chat at a time, so separate changes would otherwise have to queue.

## When to use a task

If any of these is true, reach for a task rather than a chat:

- The work is large and splits into pieces that can move **at the same time** (chats inside a task run in parallel)
- The change spans several files, or several conversations
- You need to pause partway — waiting on a review, waiting on a revised spec — and pick it up later
- You'd rather accumulate the code on a "task main version" and ship it all at once

If you just want to fix a line of copy or tweak a constant, use a [Chat](#/chats).

## Creating a task

1. Open [Tasks](#/tasks)
2. Click **+ New task** in the top right and fill in:
   - **Title** — one line, shown in the list
   - **Description** — the background, the goal, what "done" looks like
   - **Owning app** — which codebase the AI works on
3. Save. The task card appears in the list with status "Not started".

## The four task states

| Status | Meaning | How you get there |
|--------|---------|-------------------|
| Not started | created, nothing running yet | the default |
| In progress | a chat inside the task is running | start a chat in the task |
| Suspended | paused, but the task main version and history are kept | "Suspend" on the detail page |
| Finished | everything merged and confirmed live | "Finish task" on the detail page |

The task list can be filtered by status — tick "Finished" to dig up old work.

## What you can do on the task detail page

Click a task row to open it. The usual moves:

- **New chat** — start a conversation scoped to this task; its changes merge into the **task main version**, not the app main version
- **View changes** — every chat under this task and every merged commit
- **Merge into task main version** — fold the current chat's changes into the task's long-lived branch
- **Merge into app main version** — when the whole task is done, merge the task main version back into `main`
- **Suspend / resume** — a suspended task stops running by itself but keeps all its state

## What the task main version is

The task main version is a **long-lived branch that belongs to this task**, built up chat by chat.

- It **does not touch the app main version**, so you can iterate on it freely
- Once the task is complete, **merge into app main version** ships it in one go
- Until the task is deleted, you can always pull a copy of the task main version to look at locally

## How tasks and chats fit together

```
Task (owns the task main version)
 ├─ Chat #1 ──► merge into task main version
 ├─ Chat #2 ──► merge into task main version
 └─ Chat #3 ──► merge into task main version
                    │
                    └─► merge into app main version (when the task finishes)
```

`04-chats.md` has the detailed comparison.

## Common questions

**Q: Can I move someone else's chat under my task?**
A: No — chats and tasks are bound at creation time.

**Q: Can one task span several apps?**
A: No, a task belongs to exactly one app.

**Q: Can I continue a suspended task?**
A: Yes. Resume it and all the context — task main version, past chats — is still there.

Read next: `04-chats.md`