> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks

> Create and manage AI agent tasks

# Tasks

A task is a unit of work assigned to the AI agent. Each prompt you send creates a task that the agent processes inside a running workspace.

## Task Lifecycle

Every task moves through a defined set of states:

```mermaid theme={null}
stateDiagram-v2
    queued --> provisioning
    provisioning --> running
    running --> awaiting_input : agent asks question, proposes a plan, or returns a response
    awaiting_input --> running : you respond
    running --> failed : error
    running --> aborted : cancelled
    awaiting_input --> aborted : cancelled
```

| State            | Description                                                                      |
| ---------------- | -------------------------------------------------------------------------------- |
| `queued`         | Task is queued with your prompt or follow-up message                             |
| `provisioning`   | A workspace is being prepared for the task                                       |
| `running`        | Agent is actively working and streaming output                                   |
| `awaiting_input` | Agent is waiting for your next message, an answer to questions, or a plan review |
| `failed`         | Agent encountered an unrecoverable error                                         |
| `aborted`        | You cancelled the task before completion                                         |

## Creating Tasks

<Tabs>
  <Tab title="Web">
    Open your project and type a prompt in the chat input:

    > Add a dark mode toggle to the navbar using Tailwind's dark: variant

    The agent starts immediately and streams its work into the chat view.
  </Tab>

  <Tab title="CLI (Interactive)">
    ```bash theme={null}
    aether run "Add a dark mode toggle to the navbar"
    ```

    The `run` command creates a task and streams output to your terminal in real-time. This is the simplest way to interact with the agent from the command line.
  </Tab>

  <Tab title="CLI (Managed)">
    ```bash theme={null}
    aether task create --prompt "Add a dark mode toggle to the navbar"
    ```

    This creates the task and returns its ID without streaming output. Use this when you want to manage tasks programmatically or watch them later.
  </Tab>
</Tabs>

## Watching Task Output

If you created a task with `task create` or want to reconnect to an ongoing task:

```bash theme={null}
aether task watch <task-id>
```

This streams the agent's output in real-time, including text, tool invocations, and results.

## Responding to Questions

When the agent needs clarification, the task enters `awaiting_input` state. The agent presents one or more questions.

<Tabs>
  <Tab title="Web">
    Questions appear inline in the chat. Type your response and press Enter.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    aether task respond <task-id> --message "Use the shadcn/ui Switch component"
    ```
  </Tab>
</Tabs>

<Note>
  If you're using `aether run`, questions are handled interactively — they appear in your terminal and you can respond directly.
</Note>

## Aborting Tasks

To cancel a running task:

<Tabs>
  <Tab title="Web">
    Click the **Stop** button in the chat view.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    aether task abort <task-id>
    ```
  </Tab>
</Tabs>

Aborting stops the agent immediately. Any files already written or commands already executed are **not** rolled back.

## Listing Tasks

```bash theme={null}
# List all tasks for the current project
aether task list

# Filter by status
aether task list --status running
```

Output:

```
ID          STATUS      PROMPT                          CREATED
task-001    awaiting_input Add dark mode toggle          2025-03-15 14:30
task-002    running     Fix login page validation       2025-03-15 15:10
task-003    awaiting_input Set up PostgreSQL database    2025-03-15 15:25
```

## Event Types

As a task runs, the agent produces a stream of typed events:

| Event             | Description                                                                    |
| ----------------- | ------------------------------------------------------------------------------ |
| `text`            | Agent's text output (reasoning, explanations)                                  |
| `thinking`        | Internal reasoning steps (model thinking)                                      |
| `tool_invocation` | A tool being called (file write, bash command, browser action)                 |
| `result`          | The result of a tool invocation                                                |
| `question`        | Agent is asking for user input                                                 |
| `log`             | System-level log messages                                                      |
| `error`           | An error occurred during execution                                             |
| `done`            | Agent turn finished; a successful response leaves the task in `awaiting_input` |

<Info>
  In the web UI, tool invocations are rendered with expandable details showing the tool name, input parameters, and output. In the CLI, they stream as formatted text.
</Info>