# Tasks

> Hand long work to an agent on your desk. It keeps going after your session ends and tells you when it starts, needs you and is done.

A task is a piece of work for an agent on your desk: Claude Code, Codex or another agent you set up on the [Agents](/docs/agents) page. You write what to do and how to check it. The agent works in a folder on the desk until it is done.

## A task's life

```flow
Waiting → Starting → Running → Done · Failed · Stopped
Running → Needs you → Running
```

A task waits its turn (one task per folder at a time), starts, and runs. When the agent needs a login, a code or a choice, the task needs you: it waits until you answer, then runs again. It ends **Done**, **Failed** or **Stopped** (by you).

Your devices get a push at three points: when the task starts, when it needs you and when it is done.

## Start a task

On the **Tasks** page, type what to do in the box under **What should your agent do?**. The menus under it pick the **Agent** and the **Machine**, and once your desk has folders, the **Folder** it works in. Press **Start**.

From the CLI:

```sh
maindesk send "Run the tests and fix any failures" --agent claude
```

`maindesk agents` lists the agent names `--agent` takes. With none named, the task goes to your default agent (Settings, Tasks).

From the API: `POST /v1/tasks` with `task`, `agent` and `folder`. See [API: Tasks](/docs/api/tasks).

The answer has a `watch_url`: the task's page, to open or to send to your human.

## Follow up

You can send a message to a task while it runs or after it ends. While it runs, the message waits for the agent: Claude Code reads it after its current step; another agent reads it when its turn ends. On the task's page, type in the follow-up box and press **Send**. From the CLI:

```sh
maindesk send --task <id> "Start the database first, then run the tests again"
```

From the API: `POST /v1/tasks/{id}/messages`.

## Answer questions

When the agent needs you, it opens an ask: a login, a two-factor code, a spend approval, a choice or a check. Your phone gets a push. Open the **Inbox** or the task's page to answer. Only you can answer, on the web page.

`maindesk inbox` lists what needs you, with a link for each. From the API: `GET /v1/inbox`.

## Wait for tasks

One call waits for several tasks and answers as soon as one ends or needs you:

```sh
maindesk task wait t_1 t_2          # the first of them to end or need you
maindesk task wait t_1 t_2 --all    # every one of them, one line each as it ends
maindesk task wait --mine           # any of your tasks
```

The exit code is 0 when every task ended well, 1 when one failed, 2 when one needs you, 3 when one was stopped, 4 for a change that is not an end (`--until change`) and 5 when there is nothing to wait for.

From MCP: `task(op="wait", ids=["t_1", "t_2"], until="end", wait_s=50)`. From the API: `GET /v1/tasks/wait?ids=t_1,t_2&until=end&wait_s=50`. A call waits at most 50 seconds and then answers `timed_out: true`; pass the `cursor` it returns as `since` on the next call, so no change is missed or seen twice.

## Limits

Each task has a time limit and a desk minutes limit. They come from **Settings**, **Tasks**. When a task reaches a limit it stops and waits for you. Raise the limit on the task's page and it carries on. Only a person can raise a limit.

## Results, files and screenshots

When a task ends, its page shows a summary and the files or screenshots the agent attached. An agent attaches a file from the desk with:

```sh
maindesk attach /desk/shot.png --caption "The result"
maindesk screen --on windows
```

The second line takes a picture of the Windows screen and attaches it. From the API: `POST /v1/tasks/{id}/media` or `POST /v1/tasks/{id}/media/screen`.

Files and screenshots stay on your desk. The desk serves them when someone opens them, so it must be awake.

## Share a result

A finished task's result can be a read-only link that opens without sign-in. Make it with `POST /v1/tasks/{id}/share`; stop it with `DELETE /v1/tasks/{id}/share`. The link lasts two weeks.

## Scripts: read --json

The CLI's text is for people and may change. A script reads `--json`: every command takes it, and a task's answer always has `task_id`, `state`, `outcome` and `view` (`word`, `tone`, `group`, `line`). The same answer comes from `GET /v1/tasks/{id}` and MCP `task(task_id=...)`.

```sh
maindesk task t_1 --json | jq -r '.state, .view.word'
```

## Next steps

- [Agents](/docs/agents): set up the agents tasks run on
- [Plans and desk minutes](/docs/money): what a task's desk minutes count
- [API: Tasks](/docs/api/tasks): every task call