Cloud delegation

Give your local coding agent a cloud teammate. Delegate a repository review, a test investigation, or an independent change to Aether, then keep working in the same Claude Code or Codex conversation. Each delegated task runs in an Aether cloud workspace on its own branch, and its report comes back into the conversation that started it. Aether is one MCP server in your client. There is nothing to install per checkout: the project comes from the checkout’s Git origin remote.

Before you start

The repository you work in is connected to an Aether project with a cloud agent provider connected. A repository is connected once per organization.
Claude Code 2.1.280 or newer, or Codex CLI 0.154.0 or newer, and the Aether CLI 0.2.21 or newer on PATH. Both clients start the CLI’s aether mcp serve as their Aether MCP server.

Cloud tasks use the project’s normal agent, model, and workspace-size defaults. They consume workspace runtime credits, including when the task is read-only.

Connect your client

Run setup

aether setup

Setup finds Claude Code and Codex on this machine and, asking first, registers aether mcp serve as the Aether MCP server in each, replaces the connection Claude Code used before CLI 0.2.21 and removes its two hooks, and signs the bridge in once through your browser. Run it again after installing a client; steps already done are skipped.

To do the same by hand:

claude mcp add --scope user aether -- aether mcp serve --client claude-code
codex mcp add aether -- aether mcp serve
aether mcp login

Each client starts aether mcp serve for each session and stops it when the session ends. The command forwards Aether’s tools to the hosted endpoint, knows which conversation it serves (Claude Code’s session registry, Codex’s thread id), and wakes that conversation when a delegated task reports back. aether mcp login stores the credential in ~/.aether/mcp-oauth/ (readable only by you), shared by every Claude Code and Codex session on the machine; a session that finds no credential opens the browser itself, which takes longer than either client allows a server to start. Codex users may add required = true to the [mcp_servers.aether] table in ~/.codex/config.toml so a turn waits for Aether instead of starting without it.

Delegate your first task

From a checkout of the connected repository, paste this into your conversation:

Delegate a read-only repository orientation to Aether using the project's
default branch. Ask the cloud agent to identify the main entry points and
test commands, and report its findings with file paths. Do not change files.
Have it send the findings back to this conversation when it is done.
Give me the task link. While it runs, help me plan my next local change.

Your agent calls aether_spawn_task and gets a task link. The cloud agent sends its report with aether_respond_to_parent, exactly as a child of a cloud task does, so the prompt should say what to report. The task starts from pushed repository state: your local uncommitted changes and conversation transcript are not uploaded. Push a branch first if the cloud agent needs your latest code, and name it in the request. A successful first run leaves you with a task link and the cloud agent’s report in your conversation.

How results reach your conversation

The cloud task reports back through aether_wait_for_tasks, which returns each report, question, and failure framed as a message from that task.

Claude Code: aether mcp serve watches the conversation and sends it a message when a report arrives (it appears as a message from another Claude session), asking Claude to call aether_wait_for_tasks. /clear, /resume and reopening a closed session are followed: a report that arrived while a conversation was not showing is announced as soon as it shows again.
Codex: aether mcp serve watches the conversation and queues a message into the thread when a report arrives, asking Codex to call aether_wait_for_tasks.
When the task needs input: the report is a question. Your agent answers it with aether_respond_to_task.
When the task’s pull request is ready: a report says it is clean and mergeable at its current head, with no failing or pending external check runs recorded (Aether’s own checks are not counted). Readiness is a snapshot: inspect the pull request before acting, and whether to merge is your call.
When your client is closed: cloud work continues. Reports wait; reopen the conversation and Claude Code is woken for them, Codex after its first Aether tool call in the resumed thread. Either way aether_wait_for_tasks returns everything the conversation has not acknowledged yet.
Acknowledging: after reading, your agent calls aether_wait_for_tasks again with acknowledge set to the ids it received. An update stays unacknowledged, and is announced again, until it does. The acknowledging call returns at once, with anything still unread, even while other children run; only a call without acknowledge waits.
When a task’s run ends: every run ends with one ended update, finished or stopped, whatever the task reported along the way, so a task that stops working without reporting still wakes your conversation. A stop your own conversation made is not reported back. Your agent reads a task that ended without a report with aether_read_task_messages.

Each conversation sees only the tasks it spawned. Other tasks stay visible in the web app and the CLI.

Useful ways to split the work

Keep doing locally	Delegate to Aether	Ask for
Plan or implement a change	Review the relevant code on a pushed branch	File references, edge cases, and missing tests
Work on the next feature	Reproduce a test failure in a cloud environment	The command, failure output, and likely cause
Build one part of a feature	Implement a separate, clearly scoped part	Changes, verification results, and a PR for review

Include the branch, scope, and completion criteria in the request. Configure required dependencies and secrets in the project environment. Cloud changes stay on the task’s branch: ask for a PR, review it, and decide how to bring it into your work. A report does not merge or apply anything to your local checkout.

Delegation, Teleport, or a CLI task?

What you want to do	Use
Keep a local conversation going and give a separate task to a cloud agent	Cloud delegation, from this guide
Move the current conversation and working state to Aether to continue there	Teleport
Start and follow a cloud task directly from a terminal	`aether run`

Connection and permissions

The server is https://api.runaether.dev/mcp. Its credential permits delegation, including billable task creation, and excludes account settings, billing details, and direct database access. Only what your agent explicitly puts in a task or a reply is sent to Aether. The bridge sends the conversation’s id with each call and asks the server which of that conversation’s reports are unread; it does not upload prompt text, transcripts, local files, or tool output. Other MCP clients can add the hosted server directly at https://api.runaether.dev/mcp. Without the bridge, a conversation lasts as long as the client’s connection: reconnecting starts a new one, and its earlier tasks no longer report to it.

Troubleshooting

What you see	What to check
`Task unavailable`	Each conversation reaches only the tasks it spawned. A new or switched conversation (after `/clear`, or a new session opened from Claude Code’s agent view) cannot reach an earlier conversation’s tasks; resume that conversation (`claude --resume <id>`, `codex resume`) to continue with them, or open them in the web app.
`repository_not_connected`	The checkout’s `origin` remote is not connected to a project in any of your organizations. Connect the repository under Settings → Projects.
`repository_ambiguous`	The repository is connected in more than one of your organizations. Pass `org` to `aether_spawn_task` with the organization the error lists.
`repository_duplicated`	The repository is connected to more than one live project in that organization. Pass `project` to `aether_spawn_task` with the project id or name the error lists, or archive the projects you no longer use.
`bridge_required` in Claude Code	Claude Code is still connected to the hosted server directly, the setup from before CLI 0.2.21. Run `aether setup`; it replaces that connection and removes the hooks, then start a new session.
A hook error naming `aether_hook`	The two hooks from before CLI 0.2.21 are still in `~/.claude/settings.json`, and the tool they call no longer exists. Run `aether setup`, or delete them by hand (below).
A task spawned after in-process `/fork` belongs to the original conversation	In-process `/fork` is not supported for delegation: Claude Code runs the fork’s tool calls through the original session’s connection, so its tasks and reports go to the original. Fork a delegating conversation as its own process instead: `claude --resume <id> --fork-session`.
Claude Code shows no Aether tools	Run `aether version` to confirm the CLI is on `PATH`, then `claude mcp list`. Run `aether mcp login` before the first session: a session that has to sign in itself does not finish inside Claude Code’s server-startup timeout.
Codex shows no Aether tools	Run `aether version` to confirm the CLI is on `PATH`, then `codex mcp list`. Codex reports the server’s startup error in its MCP status.
Sign-in problems	Run `aether mcp login`. If it reports the stored credential no longer signs in, delete `~/.aether/mcp-oauth/api.runaether.dev.json` and run it again.
`listen on 127.0.0.1:39862 for the OAuth redirect`	Sign-in uses this fixed port. Finish the sign-in another session started, or stop whatever holds the port, then start the client again.
A report arrived while the client was closed	Reopen the conversation (`claude --resume`, `codex resume`): Claude Code is woken for it, Codex after its first Aether tool call. Or ask your agent to call `aether_wait_for_tasks`; it returns every report the conversation has not acknowledged.

Remove an older install

Before CLI 0.2.21, Claude Code connected to the hosted server directly and needed two hooks. aether setup replaces the connection and removes the hooks; by hand, run claude mcp remove --scope user aether and delete the UserPromptSubmit and Stop entries that call aether_hook in ~/.claude/settings.json. The tool those hooks call has been removed, so a leftover hook reports an error on every prompt and at the end of every turn until it is deleted; it does not block the turn. Earlier still, Aether CLI releases installed delegation per checkout with aether setup. Those files are no longer used; delete them from each checkout:

.aether/delegation-*.json and .aether/delegation-setup.lock
Claude Code: the aether_delegation entry in .mcp.json, the aether hooks in .claude/settings.local.json, and .claude/skills/aether-delegate/
Codex: the aether_delegation entry in .codex/config.toml, .codex/hooks.json, and .agents/skills/aether-delegate/

Getting Started

Using Aether

Cloud delegation

Before you start

Connect your client

Delegate your first task

How results reach your conversation

Useful ways to split the work

Delegation, Teleport, or a CLI task?

Connection and permissions

Troubleshooting

Remove an older install

​Before you start

​Connect your client

​Delegate your first task

​How results reach your conversation

​Useful ways to split the work

​Delegation, Teleport, or a CLI task?

​Connection and permissions

​Troubleshooting

​Remove an older install

Before you start

Connect your client

Delegate your first task

How results reach your conversation

Useful ways to split the work

Delegation, Teleport, or a CLI task?

Connection and permissions

Troubleshooting

Remove an older install