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

# aether delegation

> Configure or remove the hosted Aether integration for local Claude Code and Codex sessions

For the full setup and native browser sign-in, run `aether setup` from your checkout. See [cloud delegation](/guides/cloud-delegation) for a first task and the supported client versions.

`aether delegation` manages the integration's local files. It does not launch a coding client or run a local MCP server. Launch `claude` or `codex` normally after setup.

## Commands

| Command                     | Purpose                                                                     |
| --------------------------- | --------------------------------------------------------------------------- |
| `aether delegation install` | Write native HTTP MCP configuration, hooks, and the `aether-delegate` skill |
| `aether delegation remove`  | Remove that runtime's installed integration files and entries               |
| `aether delegation hook`    | Process native lifecycle events; invoked by the installed hooks             |

## Install

Use this command when configuring one runtime or selecting an organization explicitly:

```bash theme={"dark"}
aether delegation install --runtime claude-code --project <project-uuid>
```

For Codex, use `--runtime codex-cli`.

| Flag        | Applies to      | Description                                                                   |
| ----------- | --------------- | ----------------------------------------------------------------------------- |
| `--runtime` | Install, remove | Required: `claude-code` or `codex-cli`                                        |
| `--root`    | Install, remove | Installed checkout root; defaults to the current directory                    |
| `--project` | Install         | Full project UUID; otherwise uses the configured CLI project                  |
| `--org`     | Install         | Organization UUID for a project outside the credential's default organization |

Unlike commands that resolve a short project prefix or name, delegation installation requires a full project UUID. Run manual installation from the checkout root, or specify that root with `--root`.

```bash theme={"dark"}
aether delegation install --runtime codex-cli \
  --root /path/to/checkout \
  --project <project-uuid> \
  --org <organization-uuid>
```

Install requires a supported native client in its default configuration directory. It writes configuration but does **not** complete OAuth login. Run `aether setup --project <project-uuid>` interactively from that checkout to finish native sign-in. Setup preserves an explicitly installed organization when reinstalling.

Codex CLI 0.153.4 does not load checkout-only MCP configuration for a bare `codex mcp login aether_delegation`. Setup supplies the installed server as an invocation-only override, so it can authenticate without changing saved checkout trust. The normal project trust prompts still apply when you launch the client.

## Installed files

| Runtime     | MCP configuration    | Hooks                         | Skill                                     |
| ----------- | -------------------- | ----------------------------- | ----------------------------------------- |
| Claude Code | `.mcp.json`          | `.claude/settings.local.json` | `.claude/skills/aether-delegate/SKILL.md` |
| Codex CLI   | `.codex/config.toml` | `.codex/hooks.json`           | `.agents/skills/aether-delegate/SKILL.md` |

Each runtime also gets `.aether/delegation-<runtime>.json`, which records the installation identity. Task tracking and unread updates live on Aether. OAuth credentials stay in the native client's credential store, outside these project files.

For Codex linked Git worktrees, `.codex/hooks.json` lives in the repository's main checkout, where Codex discovers it. The MCP configuration, skill, and installation identity stay in each checkout. Run setup in each worktree; the shared hooks select that checkout's binding from the native session's working directory.

For repositories with separate Git metadata, Aether follows Codex's discovery rules: hooks stay local unless Codex recognizes a shared main checkout.

Reinstalling updates Aether's owned entries and hook executable path while preserving the installation identity and unrelated configuration. Conflicting edits fail visibly. If installation is interrupted, rerun it to finish.

## Remove

From the installed root:

```bash theme={"dark"}
aether delegation remove --runtime claude-code
# Or remove the Codex integration:
aether delegation remove --runtime codex-cli
```

Use `--root /path/to/checkout` when running elsewhere. Removal does not stop cloud tasks or revoke native OAuth credentials. Stop any running task explicitly from its Aether task page or through your connected local agent before removing the integration if you want that work to end.

Removing Codex delegation from one checkout preserves the shared hooks while another installed worktree still needs them. They are removed after the last checkout's integration is removed.

Native MCP logout and `aether logout` manage separate logins: the former clears the client's saved MCP credentials, while the latter removes the CLI login used by hooks. Removing local credentials is not server-side grant revocation.