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:

State	Description
created	Task is queued with your prompt
running	Agent is actively working and streaming output
waiting	Agent asked a question and is waiting for your response
completed	Agent finished the task successfully
failed	Agent encountered an unrecoverable error
aborted	You cancelled the task before completion

Creating Tasks

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.

CLI (Interactive)

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.

CLI (Managed)

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.

Watching Task Output

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

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 waiting state. The agent presents one or more questions.

Web

Questions appear inline in the chat. Type your response and press Enter.

CLI

aether task respond <task-id> --message "Use the shadcn/ui Switch component"

If you’re using aether run, questions are handled interactively — they appear in your terminal and you can respond directly.

Aborting Tasks

To cancel a running task:

Web

Click the Stop button in the chat view.

CLI

aether task abort <task-id>

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

Listing Tasks

# 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    completed   Add dark mode toggle            2025-03-15 14:30
task-002    running     Fix login page validation       2025-03-15 15:10
task-003    waiting     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	Task completed
finish_task	Agent signaled task completion

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.