Skip to content
Aether

Orchestration

A lead chat can start child agent chats, send them messages, read them and stop them. It does this through an MCP server, and that server is Aether itself: the same binary run as aether mcp, speaking MCP over stdio. Tool calls travel over a local Unix socket to the running Aether window, which carries them out in the UI.

Turn a chat into a lead

Section titled “Turn a chat into a lead”

Toggle Lead with the chip in the composer or from the command palette. Aether wires the MCP server into that chat’s CLI when it launches:

Provider How Aether injects the server
Claude Code --mcp-config pointing at a temporary JSON file, plus --allowedTools mcp__aether
Codex -c mcp_servers.aether.command=<aether exe> and -c mcp_servers.aether.args=["mcp"] on the app-server launch
Pi A Pi extension, pi-lead.ts in Aether’s config folder, loaded with -e. Tools appear as aether_*
OpenCode OPENCODE_CONFIG_CONTENT with an aether MCP entry for its local server
Antigravity A one-time global registration with agy mcp add aether <aether exe> mcp. Aether offers to run it the first time a lead starts

Tools are injected when the CLI starts. Turning Lead on for an existing chat restarts its driver.

Some chats can’t be leads: OpenRouter chats, and chats that are themselves children.

Tools

Section titled “Tools”
Tool What it does
list_agents Lists this lead’s children and their state.
spawn_agent Starts a child chat. Takes an optional nonce so a retried call doesn’t start the same child twice.
message_agent Sends a child a message.
read_agent Reads a child’s transcript.
stop_agent Stops a child.

Children’s results are delivered back to the lead automatically. A lead should not poll read_agent to wait for completion.

Limits

Section titled “Limits”

A lead runs at most max_children children at once. The default is 8. Set it in settings.json; values are clamped between 1 and 50.

Manual setup

Section titled “Manual setup”

You only need this to call the orchestration tools from an agent running outside Aether, or to debug what Aether injects. The server command is always the Aether binary with the mcp argument:

{
  "mcpServers": {
    "aether": {
      "command": "/usr/local/bin/aether",
      "args": ["mcp"],
      "env": {
        "AETHER_ORCH_SOCK": "<config dir>/orchestrator.sock",
        "AETHER_ORCH_TOKEN": "<lead token>"
      }
    }
  }
}
  • command: the Aether executable. For Linux installs from the tarball or .deb this is /usr/local/bin/aether, or wherever which aether points. A symlink is fine.
  • AETHER_ORCH_SOCK: the running window’s socket in Aether’s config folder. If unset, the server uses that default path.
  • AETHER_ORCH_TOKEN: minted by the running Aether for each lead chat, stable for the app’s lifetime. Without a valid token, tools/list returns an empty list and tools/call answers not an Aether lead. A manual config only works while the window that minted the token is open.

Where the block goes for each agent:

  • Claude Code: pass it with --mcp-config <file>, or save it as .mcp.json in the project.
  • Codex: in ~/.codex/config.toml as [mcp_servers.aether] with command, args = ["mcp"] and env_vars = ["AETHER_ORCH_SOCK", "AETHER_ORCH_TOKEN"], exporting both variables.
  • Pi: Aether writes pi-lead.ts, which implements the tools directly. A manual .pi/mcp.json is not used.
  • OpenCode: pass the block as OPENCODE_CONFIG_CONTENT, or add it to opencode.json as {"mcp": {"aether": {...}}}.
  • Antigravity: run agy mcp add aether /usr/local/bin/aether mcp once. It writes ~/.gemini/config/mcp_config.json. The token reaches the server through agy’s environment at launch and is never stored in that file.

If orchestration doesn’t work, see troubleshooting.