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 session. Your local agent can read the result, answer follow-up questions, and bring the findings back into your work. Each delegated task runs in an Aether cloud workspace. You can follow it from your local conversation or open its task link in the web app.

Before you start

Install the latest Aether CLI.
Use a Git checkout linked to an Aether project, with a cloud agent provider connected.
Use a stable local client on macOS or Linux: Claude Code 2.1.257 or newer, or Codex CLI 0.153.4 or newer. Setup accepts newer stable releases. Prerelease builds and custom CODEX_HOME or CLAUDE_CONFIG_DIR directories are currently unsupported.

Both clients support linked Git worktrees. Run aether setup in each checkout where you want delegation. If you installed Codex delegation with an older Aether CLI, upgrade and rerun setup to update its hooks, then restart Codex and review the changed hook commands. Our latest compatibility smoke passed with Claude Code 2.1.272 and Codex CLI 0.154.0. Aether validates the hook fields it uses and reports incompatible payloads instead of guessing their meaning. 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.

Set up your checkout

Run setup in your repository

From the checkout where you use your local coding agent, run:

aether setup

Confirm the project matches this repository. If a CLI default is already set, setup keeps it; use aether setup --project <project-uuid> to select a different project for this run.Answer yes to Enable Aether cloud delegation in this checkout? Setup installs the connection, lifecycle hooks, and aether-delegate skill for each detected supported client.

Connect your coding client

Setup opens each client’s native browser sign-in. Use the same Aether account as the CLI, review the requesting client and return address, and choose Allow access. Complete the browser flow on the computer running setup so it can return to the local client.Setup waits for authorization and prints Cloud delegation connected for claude-code or Cloud delegation connected for codex-cli. When both clients are installed, it connects both. You do not need a separate mcp login command.

Start your local agent

Launch a new session in this checkout, or restart your existing one after setup:

Claude Code
Codex

claude

codex

Review and approve the client’s project MCP and hook trust prompts. The connection appears as aether_delegation; the installed skill teaches your agent how to use it.

Delegate your first task

Paste this into your local coding 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.
Give me the task link. While it runs, help me plan my next local change.

Your local agent creates the cloud task and gets a task link. A task being accepted means it has been queued; the result is ready when the cloud agent finishes its turn. As you continue the local conversation, hooks check for updates and tell your agent when there is a result or a request for input. The agent can read the full response, summarize it, and acknowledge the update after handling it. If the local conversation has paused, send:

Check the Aether task. Read its full result and summarize the findings.

A successful first run leaves you with a cloud task link and a result you can use in the original local conversation.

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 delegation request. A 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 that branch in the request. Configure required dependencies and secrets in the project environment. Cloud changes stay in the cloud task’s branch. Ask for a PR, review it, and decide how to bring the changes into your work. Receiving a result does not merge or apply it to your local checkout.

How results reach your session

While you work: hooks check at session start, prompts, and supported tool events. Your agent gets a notice when unread updates are available.
When your agent finishes a turn: the Stop hook can ask it to continue once for an actionable unread update. It does not keep the agent running indefinitely.
When the task needs input: your local agent can read the question or plan and send an answer or decision through the same connection.
When your local agent is idle or closed: cloud work can continue, but hooks cannot wake that agent. Resume the session or ask it to check the task.

Reading a result does not clear its unread state. The installed skill tells the agent to acknowledge the exact update only after reading or handling it.

Delegation, Teleport, or a CLI task?

What you want to do	Use
Keep a local session 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`

Delegation keeps the local conversation in charge of the handoff and result. Teleport carries the current session itself into the cloud.

Connection and permissions

The connection uses hosted MCP at https://api.runaether.dev/mcp. Setup supplies the project configuration; adding only this URL to a generic MCP client does not install the hooks or establish a local session. Claude Code and Codex store and refresh their own OAuth credentials. Those credentials permit cloud delegation, including billable task creation, but exclude account settings, billing details, and direct database access. Hooks use your saved Aether CLI login separately. Keep both signed in to the same Aether account. Hooks send session identifiers and event metadata. They do not upload prompt text, transcripts, local files, or tool output. Information your local agent explicitly puts in a delegated task or follow-up is sent to Aether.

Troubleshooting

What you see	What to check
Setup never offers cloud delegation	Run it inside a Git checkout, select a project, and make sure `claude` or `codex` is on `PATH`.
Setup reports that your client is too old or its version cannot be parsed	Check `claude --version` or `codex --version`, then install a stable release at or above the minimum above. If an older Aether CLI says `unverified host version`, update Aether too.
`delegation setup requires the host's default configuration directory`	Use the client’s default profile without `CODEX_HOME` or `CLAUDE_CONFIG_DIR` overrides.
Browser sign-in was cancelled or failed	Run `aether setup` again in this checkout and complete the connection. Setup reports the failure rather than marking it connected.
The connection needs authentication after restarting	Rerun setup with working native credential storage. On macOS, use your normal home and an accessible login keychain; a temporary `HOME` without a default keychain can make the native login fail to persist.
Tools are missing, or the agent has no Aether session handle	Confirm setup enabled delegation, launch the agent in the installed checkout, and approve its project MCP and hooks. Restart the session after installing.
Hooks report an authentication or project mismatch	Check `aether auth status`. Use the same account for CLI and MCP, and confirm setup targeted the right project.
The cloud task finished but nothing appeared locally	Send a new prompt asking your agent to check the task. Hooks do not wake an idle or closed session.

For installation files, organization selection, and removal, see the aether delegation reference.

Getting Started

Using Aether

Cloud delegation

Before you start

Set up your checkout

Delegate your first task

Useful ways to split the work

How results reach your session

Delegation, Teleport, or a CLI task?

Connection and permissions

Troubleshooting

​Before you start

​Set up your checkout

​Delegate your first task

​Useful ways to split the work

​How results reach your session

​Delegation, Teleport, or a CLI task?

​Connection and permissions

​Troubleshooting

Before you start

Set up your checkout

Delegate your first task

Useful ways to split the work

How results reach your session

Delegation, Teleport, or a CLI task?

Connection and permissions

Troubleshooting