Tasks

A task is a unit of agent work. Each task binds to exactly one agent and one workspace VM: you describe what you want, the agent executes inside the VM, and you steer it with follow-up messages.

Prerequisites

A task can only run against a project linked to a GitHub repository, on a base branch. Before you start a task, connect the GitHub App and import a repo. Starting a task also consumes credits — see Costs and admission below.

Task Lifecycle

Aether persists four task states:

State	Description
`queued`	The task and its messages are queued, waiting for a workspace and the agent to start
`processing`	The agent is actively working and streaming output
`awaiting_input`	The agent finished its turn and is waiting for you
`errored`	The agent hit an unrecoverable error

There is no terminal “done” state. A successful agent turn parks the task back in awaiting_input, ready for your next message.

Why a task waits

awaiting_input has three kinds, all surfaced inline in the chat:

message — the agent returned a response, or you stopped it. Send any follow-up to continue.
questions — the agent asked one or more questions and needs answers before continuing.
plan — the agent proposed a plan (in Plan mode) and is waiting for you to approve or revise it.

Display statuses

The states above are the persisted contract. The web app and usage filters group tasks by display status, which folds in pull-request outcomes: running · awaiting_input · awaiting_ci · merged · unmerged · errored · archived

Creating Tasks

Web
CLI (Interactive)
CLI (Managed)

Click New task (or press C) to open the composer. Pick the project, base branch, and VM size, optionally adjust the agent settings, type your prompt, and submit:

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

The composer requires the selected project to have a linked repository and a base branch. The task starts and its work streams into the workspace screen.

aether run "Add a dark mode toggle to the navbar" --size medium

run creates a task and watches its progress in your terminal, polling for status updates and printing the agent’s summary when it finishes its turn. Pass --no-watch to create without watching. If you omit --size, the size is resolved server-side — the project’s default task size, else small — and the CLI prints size: project default (use --size to override).

aether task create --prompt "Add a dark mode toggle to the navbar" --size medium

Creates the task and returns its ID without watching. Watch it later with aether task watch <id>. If you omit --size, the size is resolved server-side — the project’s default task size, else small — and the CLI prints size: project default (use --size to override).

VM Size

Every task is created with an explicit vm_size, and Aether initially creates its workspace at that size. The task keeps its original vm_size if you later resize the workspace. See the VM size catalog for each size’s CPU, memory, storage, and credit rate. The web composer always has one of the three sizes selected and sends it explicitly. Its picker shows every size and credit rate using availability for the selected project: a Warm badge marks a size with a ready machine, while Warming marks configured warm capacity that does not yet have a ready machine. Every plan can select every size. A matching warm pool makes startup immediate. Without a ready machine for the exact (project, size) pair, the task cold-starts at the requested size — Aether never substitutes another size during startup.

Plan vs Chat mode

The composer’s settings menu offers two interaction modes:

Chat (default) — the agent implements directly.
Plan — the agent proposes a plan first and parks in awaiting_input (plan kind) so you can approve or revise before any edits.

Set the mode per task in the composer, or set a project default in task defaults. See the workspace screen for how plan approval surfaces.

Follow-ups and Queued Messages

When a task is in awaiting_input, send another message to continue the conversation — it re-queues the task and the agent picks up where it left off. You can also send messages while the agent is still processing. They are held as queued messages and delivered after the current turn. Queued messages appear as pills above the composer; remove one before it is delivered with the trash icon, or via the CLI:

aether task remove-from-queue <task-id> <message-id>

Responding to Questions

When the agent asks questions, answer them inline.

The question form takes over the composer. Fill it in and submit.

# Free-form follow-up or message-kind response
aether task respond <task-id> --message "Use the shadcn/ui Switch component"

# For structured questions or plan review, omit --message to answer interactively
aether task respond <task-id>

# ...or answer non-interactively, e.g. from a script
aether task respond <task-id> --answer 0:1
aether task respond <task-id> --approve

See aether task respond for the full --answer/--approve/--reject reference.

Checkpoints (Truncate and Rewind)

The agent commits as it works, so the conversation has restore points. In the workspace screen you can restore the conversation to an earlier checkpoint: Aether rolls the workspace back to that point and truncates the conversation after it, discarding the later turns. Use this to undo a wrong direction and try again from a known-good state.

Restoring to a checkpoint rewinds the workspace and drops the conversation history after that point. It cannot be undone.

Stopping a Task

Stopping interrupts the agent mid-turn and parks the task in awaiting_input (message kind) — it does not throw away the workspace.

Click Stop in the composer while the agent is running.

aether task stop <task-id>

Files already written and commands already executed are not rolled back by a stop — use a checkpoint restore for that.

Listing and Archiving Tasks

# List tasks for the current project
aether task list

# Filter by display status (comma-separated)
aether task list --status awaiting_input,errored

# Archive / unarchive
aether task archive <task-id>
aether task unarchive <task-id>

Costs and Admission

Starting a task runs a workspace VM, which spends credits. Before the agent starts, an admission check verifies that:

your plan is in a billable state,
you have at least one minute of spendable credit for the task’s runtime class.

If a check fails the task does not start, and Aether reports why (for example, credits exhausted or billing blocked).

Getting Started

Using Aether

Prerequisites

Task Lifecycle

Why a task waits

Display statuses

Creating Tasks

VM Size

Plan vs Chat mode

Follow-ups and Queued Messages

Responding to Questions

Checkpoints (Truncate and Rewind)

Stopping a Task

Listing and Archiving Tasks

Costs and Admission

​Prerequisites

​Task Lifecycle

​Why a task waits

​Display statuses

​Creating Tasks

​VM Size

​Plan vs Chat mode

​Follow-ups and Queued Messages

​Responding to Questions

​Checkpoints (Truncate and Rewind)

​Stopping a Task

​Listing and Archiving Tasks

​Costs and Admission

Prerequisites

Task Lifecycle

Why a task waits

Display statuses

Creating Tasks

VM Size

Plan vs Chat mode

Follow-ups and Queued Messages

Responding to Questions

Checkpoints (Truncate and Rewind)

Stopping a Task

Listing and Archiving Tasks

Costs and Admission