Skip to main content
Manage agent tasks. A task is one agent run that reads files, executes commands, and writes code in an isolated workspace. See tasks and lifecycle for concepts.

Usage

tasks is an alias for task. Most <id> arguments accept a short prefix. A task holds one or more chats, all in its workspace. Every command that takes a task addresses its main chat, the one it was created with; respond, stop, turns and watch take --chat <chat-id> to address another. A chat id accepts a short prefix too.

Subcommands

aether task list

List tasks in the current project.
When more tasks follow, the list ends with the --cursor to pass for the next page; tasks created meanwhile never shift that page. With --json the cursor is the response’s next_cursor, null on the last page. --status takes one or more display statuses, comma-joined: running, awaiting_input, awaiting_ci, merged, unmerged, errored, archived. It also takes review_attention — a virtual filter token, not a display status, that matches a task whose pull-request review needs your judgment. Pass all to clear the filter. --needs-you is the shorthand for the same set the web app’s “Needs you” filter sends: --status awaiting_input,review_attention,errored. PR-review runs are listed only with --source pr_review or when --ids names them; every other list leaves them out. With --project, the listing is that project’s tasks; the project must belong to the organization the command acts in (see --org). Run by your personal agent with no project from --project, AETHER_PROJECT, or aether project select, it lists your agent’s default project.
The STATUS column is the task’s own state — running, awaiting_input, errored, done, or archived. Pull-request lifecycle lives in the PR column, so --status merged returns rows whose STATUS reads done with the merge shown under PR. The PR cell names the same bucket --status filters on: merged, or awaiting_ci for an open PR whose checks are still running. unmerged is a catch-all over open and closed PRs, so those rows show the pull request’s own state (open, closed) instead. --json is unaffected: it prints the server’s envelope, including the raw display_status.

aether task create

Create a task with a prompt. If --prompt is omitted (and not reading --stdin), you are prompted for it interactively.
aether run does create plus watch in one step and is usually what you want.
Every task carries an explicit VM size. If you omit --size, the size is resolved server-side — the project’s default task size, else medium — and the CLI prints size: project default (use --size to override). See VM sizes and warm starts. With --json, the size is still resolved server-side the same way; the CLI only suppresses the notice so stdout remains valid JSON.

aether task get

Show task details, summary, and the event timeline.
When the agent has a plan, get prints it as a numbered checklist after the status block — [x] done, [>] in progress, [ ] pending:
The plan persists after the task settles, so a finished task still shows the checklist it ended on. Tasks whose harness never sent a plan have no Plan section. With --json, the plan is the optional plan field.

aether task status

Show a compact status line — runtime status, display status, workspace, PR/CI, and tokens.

aether task turns

Show the task’s conversation, newest page: each turn’s input and the agent’s latest message on it, under the task’s page link. When older turns exist it prints the cursor that reads them; pass it back with --cursor. With --json, the server’s response.
With --chat, the turns of that chat instead of the main chat’s.

aether task chats

A task’s chats share its workspace: its files, branch and pull request. Each chat has its own agent, model, reasoning effort, transcript and queue. One turn runs at a time per workspace, so a message to a chat while another chat’s turn runs waits in its queue. A chat does not change who a task reports to.

aether task chats list

List the task’s chats, the main chat first, with each chat’s own status: what an awaiting_input chat awaits (message, questions or plan), the chat a queued chat waits for, and whether it is archived. With --json, the server’s response, whose awaiting_input carries a chat’s question or plan.

aether task chats start

Start a chat in the task’s workspace with an empty context. Settings you leave out are the main chat’s; another --agent-type takes its default model, and an inherited effort the chat’s model cannot take is left to the model’s default. The chat runs on the task creator’s default connection for its agent.

aether task chats fork

Fork a chat into a new chat of the same task, on the same files, branch and pull request. The new chat starts with a copy of the chat’s conversation and resumes its agent’s memory under a new session, so it can try another direction while the chat it was forked from stays as it was. It takes that chat’s agent, model, reasoning effort and interaction mode, and names it in forked_from (--json). A chat is refused while it has a turn queued or running or waits on your answer, before its first turn has ended, and on OpenCode; the error says which.

aether task chats continue

Continue one of your chats in Claude Code on the computer you run this on. The task page and the phone app show the command ready to copy, for each of your computers by name. Run it inside a checkout of the task’s repository:
  1. It exports the chat’s Claude Code session file, as of the chat’s latest checkpoint. Only the task’s creator can export a chat, and the chat in Aether stays as it is.
  2. It fetches the task’s branch from origin and makes a new work tree on it in <folder> (git worktree add --no-track -b <branch> <folder>). A folder that already exists is refused, and so is a branch of that name your checkout already has (from an earlier continue, say): continue in the work tree that has it, or delete the branch first.
  3. It places the session file, untouched, where Claude Code looks for the work tree’s sessions: $CLAUDE_CONFIG_DIR/projects/<folder>/ when CLAUDE_CONFIG_DIR is set, else ~/.claude/projects/<folder>/, the folder named from the work tree’s resolved path as Claude Code names it (/private/tmp on macOS for /tmp).
  4. It prints the command that resumes the session as a fork: claude --resume <session> --fork-session, with CLAUDE_CONFIG_DIR=<absolute path> before it when you ran the command with CLAUDE_CONFIG_DIR set.
The resumed session shows in Aether as a chat of the work tree, forked from the chat, once this computer’s machine bridge mirrors it. Run the printed command within 24 hours, before any other Claude Code session in the folder: the first terminal chat of the folder takes the link. The command runs under the sign-in aether setup gave this computer, and only on the computer it was copied for (--computer). Signing Claude Code in is yours to do, and so is trusting the work tree: its files, .claude settings and hooks among them, are the agent’s, so Claude Code asks whether you trust the folder the first time it runs there. The chat’s checkpoint holds its session file alone, so sub-agents’ transcripts do not come with it.

aether task activity

Show one page of the task’s activity feed, newest first. A task with a pull request reads that pull request’s feed: the authoring task’s events, review runs, feedback sent to the agent, GitHub reviews, and the merge. A task without one reads its own events.
A review Aether posted on its own pull request reads at the verdict Aether recorded, marked (recorded in Aether): GitHub holds such a review as COMMENTED. Every other review state, such as DISMISSED, reads as GitHub holds it. With --json, the API’s page: items and next_cursor (null on the last page).

aether task tree

Show the whole tree the task belongs to: its root, then each task beneath its parent, with the parent’s ID in the PARENT column. The task itself can be anywhere in the tree.
OUTCOME is each task’s outcome. With --json, the API’s items: every task of the tree at once, each a whole task.

aether task subagents

Read the subagents a task’s agent spawned: Claude Code Task agents, background shells, and workflows, and Codex collab agents. They are not Aether tasks and have no workspace, branch, or pull request of their own.

aether task subagents list

Each subagent is listed by the tool call that spawned it, which is the ID events takes. Subagents the agent’s CLI runs for its own housekeeping are left out, as on the web. --json prints the API’s items, including them ("ambient": true).

aether task subagents events

Show one subagent’s transcript in order: the text it wrote, and each tool it called, once, with the status it settled at and the error of one that failed.
The API caps a transcript; when the cap is hit, the output ends by saying so ("truncated": true with --json). A tool call’s output is in --json only. Control characters in what the agent wrote, such as terminal escape sequences, are printed escaped (\x1b) so they cannot drive your terminal; --json carries the text as the API sent it.

aether task media

Read the screenshots and recordings captured for a task, and hide one from its proof page.

aether task media list

Each capture shows its ID, kind, age and title, with its URL on the line below. Hidden captures appear, marked (hidden), only to someone who may hide them. With --json, the API’s items, each saying whether you may hide it (hideable).

aether task media hide

Hide a capture from the task’s proof page and Verify panel. It takes the capture’s full ID from media list.
Only an admin or owner of the task’s organization, or a member with product access who created a task linked to the task’s pull request, can hide a capture. --json prints the hidden capture.

aether task spend

Show the task’s model spend by what paid for it.
Turns through Aether inference cost what is shown. Turns on your own API keys show an estimate of what the provider charged. Subscription turns cost no money, so they show the tokens they used. Unpriced turns are paid turns whose model had no price, so the dollar figures leave them out. With --json, the API’s figures in microdollars (USD × 1,000,000).

aether task runtime-usage

Show what the task’s metered runs have used so far: credits, and the CPU-hours and GB-hours behind them.
A task on reserved machines has nothing metered; it is billed by VM time at its machine class’s rate, and the command says so.

aether task update

Update the task’s model and behavior settings. Its harness is fixed at creation. Provide at least one flag.

aether task respond

Continue a task: send a follow-up message, or answer the agent inline when it is waiting on you.
With --message, the text is sent directly:
respond streams the agent’s reply by default, the same way aether run does, and exits non-zero if the task fails. Until the agent has the message, it follows it through the message read and prints where it is in the API’s words. Aether holds a message to a chat on your computer for up to 24 hours while the computer cannot be reached. If the computer cannot be reached, respond prints that Aether holds the message and exits 0; it does the same if the message has still not reached the agent after five minutes. A message behind a running turn streams that turn, with no time limit, while respond keeps reading the message beside it, so a computer that goes away meanwhile ends the stream the same way. A message that was not delivered exits 1 with the reason, and so does one whose fate is unknown: it may have reached the agent, and Aether does not send it again. Pass --no-watch to send and return immediately, printing where the message is. --json prints the message it sent without streaming:
When you omit --message, respond is interactive. If the task is waiting on a question (ask_user) or a plan review (propose_plan), the CLI presents the prompt, with the plan’s decisions as the API offers them, and sends your answer. Otherwise it asks you for a free-text message.
Structured input can also be answered non-interactively, so scripts and agents can drive tasks without a TTY. Read the open request from the chat’s pending_inputs in aether task chats list <id> --json, then respond:
The CLI answers the chat’s open request of the flag’s kind (--answer answers questions, --approve/--reject a plan) through the answer endpoint. The API checks the answer, and a refusal prints its code and the API’s sentence. A chat that waits on nothing is sent nothing. When the chat has several requests of that kind open, --pending <tool_id> names the one to answer. A permission request (a tool call) on your computer is approved from the web app or your phone: respond prints the API’s sentence for it and sends nothing. With --json, an answer prints the chat the API answered. An answer carries no message, so --message, --stdin, --context-file, --attach, --interaction-mode and --reasoning-effort are refused beside it; change the interaction mode or reasoning effort with aether task update after answering. --feedback goes with --reject. If the task is awaiting a structured answer, passing --message alone is rejected — pass --answer/--approve/--reject, or run respond without flags so the CLI can present the question or plan. With --chat, every form above addresses that chat, on any machine, a chat on your computer included: the CLI reads the chat’s own status and pending_inputs (aether task chats list <id> --json), answers or sends to that chat, and streams that chat’s reply. A task in a checkout on your computer has no main chat, so name one of its chats with --chat.

aether task stop

Stop a running task and park it in awaiting_input so you can respond and resume.
With --chat, only that chat’s turn stops, and only its queued messages are discarded or kept:

aether task keep-context / compact

Aether compacts an idle Claude Code session on a Claude plan just before its prompt cache expires: it replaces the conversation with a summary, so the next message does not re-read all of it. aether task get <id> --json shows a pending compaction as awaiting_input.idle_compaction. keep-context skips that one compaction: the next message re-reads the whole conversation, and a later turn schedules a new compaction as usual. compact delivers it now instead, with every check the compaction’s timer makes.
A task with no pending compaction is refused with idle_compaction_not_pending, and a compaction that no longer applies (its pull request merged, its connection changed or hit a limit) with idle_compaction_skipped.

aether task archive / unarchive

Move a task into or out of the archive by setting its archived field (PATCH /tasks/{id}), then print the task the API answers with: its short ID, name, and display status. --json prints that task.
Archiving a task archives it for its organization and unpins it. Unarchiving restores it, also for you if you had hidden it.

aether task pin / unpin

Pin a task for its organization, or unpin it, by setting its pinned field (PATCH /tasks/{id}), then print the task the API answers with. --json prints that task.
An archived task, a campaign child, or a review run cannot be pinned. Only the task’s creator or an admin or owner of its organization can archive, unarchive, pin, or unpin it.

aether task save

Save a task with no repository to GitHub (POST /tasks/{id}/repository): the task’s project gains a repository, the task is bound to it, and the task’s history is given a home there. A repository with no commits receives the task branch as its first history; one with commits has the task’s commits replayed onto its default branch, and a replay that stops on a conflict is left to the agent, which finishes the rebase and then publishes.
Only the task’s creator creates or picks a repository. A project that already has a repository takes the task’s work there and needs neither --create nor --repo; the task’s creator or an owner or admin of the organization saves into it. --json prints the API’s answer: the repository, the binding, and the outcome (published with its head_sha and whether it was rebased, or rebase_conflict with the default_branch the replay stopped on).

aether task download

Download the tree of the task branch’s commit as a zip (GET /tasks/{id}/download): its tracked files, without the git history. The task’s workspace produces it, woken when idle, so a task that has not started has nothing to download. The file takes the name the API gives it, in the current directory, unless --output names another file. An existing file is never overwritten. Uncommitted changes in the workspace are not in the zip; the command says when it left some out, so you can ask the agent to commit them first.
--json prints the file written, its size in bytes, the commit the tree was taken from, and uncommitted_changes.

aether task remove-from-queue

Remove a single queued follow-up message from a task by its message ID.

aether task watch

Watch the agent’s progress live. The watch exits when the task completes, fails, or stops.
Watch polls the API every ~3 seconds for new status updates. With --chat, watch follows that chat: it prints each status the chat moves through, and once the chat waits again, the agent’s latest message and the command that answers it. It exits non-zero if the chat fails. --chat does not combine with --until-attention. When the agent moves to another plan step, watch prints one line for it — and nothing while the step is unchanged:
The step is numbered by its position in the plan, not by the done count, so a plan the agent works out of order still names the step it is on. Once no step is in progress the line reads 3 of 3 steps done. Tasks with no plan print nothing extra. A failed task exits non-zero and prints the failure, whether it failed while you were watching or before you attached — so watching an already-failed task is still how you read the error, and scripts can rely on the exit code either way. This is the same exit status aether run and aether task respond give you, since both watch through the same code.

Interactive Watch

On a TTY, watch is interactive. While watching you can: When the agent pauses to ask a question or propose a plan, watch presents it inline — answer it and watching continues automatically. After detaching, reattach any time:

Wait until a task needs you

With --until-attention, watch takes one or more tasks and waits, without streaming, until any of them needs you: by the same rule as aether task list --needs-you, it is awaiting your input, it errored, or its open pull request has a review that needs your judgment. It prints the task’s full ID and why it needs you, then exits.
--interval and --timeout are refused without --until-attention. With --json, stdout is exactly one JSON document: {"task_id", "outcome", "latest_status_message"} for the task that needs you, or {"error": {"code", "message"}} on failure. The error codes are task_watch_timeout, task_watch_failed, invalid_argument, and command_failed (an authentication or configuration failure before the watch starts). A watch without --until-attention is interactive and refuses --json; use aether task get <id> --json for a snapshot.