> ## 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.

# Cloud delegation

> Keep working in Claude Code or Codex while Aether runs tasks in the cloud

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](/guides/github-integration) with a [cloud agent provider connected](/guides/connect-agent-providers). 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](/cli/installation) 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](/concepts/billing-and-credits), including when the task is read-only.

## Connect your client

<Steps>
  <Step title="Run setup">
    ```bash theme={"dark"}
    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.
  </Step>
</Steps>

To do the same by hand:

```bash theme={"dark"}
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:

```text theme={"dark"}
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](/guides/environment-json). 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](/guides/teleport) |
| Start and follow a cloud task directly from a terminal | [`aether run`](/cli/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/`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.