> ## Documentation Index
> Fetch the complete documentation index at: https://ade-app.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the ADE brain, project state, the desktop app, the web client, iOS, and optional remote runtimes over SSH fit together.

ADE is local-first. The center is the **brain** — the always-on, machine-owned ADE process for a channel. The brain owns the project catalog, the durable project state, the sync websocket, and the authority to run agents. Everything you see is a **client** of that brain: the desktop app, the web client, the `ade` CLI, the iOS app, and any SSH-attached desktop window.

```mermaid theme={null}
flowchart TB
  Desktop["ADE desktop app"]
  CLI["ade CLI"]
  IOS["iOS app"]
  Brain["ADE brain<br/>~/.ade/sock/ade.sock"]
  Project["Project .ade/<br/>database, worktrees, artifacts"]
  Remote["Remote ADE brain<br/>(another machine)"]

  Desktop --> Brain
  CLI --> Brain
  IOS <-->|"paired sync + commands"| Brain
  Brain --> Project
  Desktop <-->|"SSH · ade rpc --stdio"| Remote
```

## The brain

The brain is the source of truth on a machine. It owns lanes, agent chats, terminals, Git operations, PR actions, provider sessions, proof artifacts, the project catalog, and the sync service. It runs every supported provider runtime against the same projects. Because desktop and CLI clients call the same brain, a chat you start in the app and one you start with the `ade` CLI operate on the same project state.

The brain installs as a per-user login service — launchd on macOS, a systemd user service on Linux, a per-user startup entry on Windows — so it stays running even when no window is open. None of them need administrator rights. The [one-command install](https://ade-app.dev/docs/getting-started/install.md) sets this up, and [`ade connect`](https://ade-app.dev/docs/getting-started/connect-machine) publishes the machine to your account so every client can find it.

Because the brain is the whole engine, a machine does not need a desktop app to be useful. On Linux there is no ADE desktop app at all: you install the brain on the server and drive it from a client elsewhere.

## Clients

> [card] Desktop app
>
> The Electron control plane — windows, navigation, the renderer UI, and platform integrations. Each window attaches to a local brain, or binds to a remote one over SSH. macOS-only integrations such as the iOS Simulator drawer are hidden on [Windows](https://ade-app.dev/docs/getting-started/windows.md).

> [card] iOS app
>
> A SwiftUI controller that pairs with a machine over WebSocket. It mirrors state and sends commands; it never runs agents itself.

> [card] [ade CLI](https://ade-app.dev/docs/reference/cli.md)
>
> The typed control plane for any shell — used by humans and by the agents running inside ADE.

> [card] [Web client](https://app.ade-app.dev)
>
> The same workspace in a browser, for any machine you have connected to your account.

> [card] [ADE SDK](https://ade-app.dev/docs/sdk/overview.md)
>
> Third-party apps spawn an embedded runtime as a guest sidecar (`@ade-dev/sdk`, `@ade-dev/chat-ui`). Not a client of the machine brain — an isolated child process.

## Project state

ADE writes local state under each repository's `.ade/` directory and leaves your source tree under Git's control:

```text theme={null}
.ade/
  ade.db        # the project database
  worktrees/    # one git worktree per lane
  artifacts/    # proof and capture artifacts
  secrets/      # encrypted project credentials
```

A **lane** is a git worktree under `worktrees/`. ADE uses real Git branches, worktrees, commits, and PRs rather than replacing them, so a lane is a normal checkout on disk you can also open in any editor.

## Remote runtimes over SSH

A desktop window can bind to a brain on **another machine** over SSH. ADE runs `ade rpc --stdio` on the remote and tunnels the same JSON-RPC back, so lanes, chats, diffs, and PRs behave exactly as they do locally — but the agents, builds, and tests run on the remote, against its filesystem and its own GitHub, Linear, and provider credentials. The desktop stays local and stays the control plane.

This is the no-account path: the desktop bootstraps the runtime on the far side itself. The alternative is to install the brain on that machine and run [`ade connect`](https://ade-app.dev/docs/getting-started/connect-machine), which publishes it to your account directory so desktop, web, and iOS can all reach it without SSH.

> [!NOTE]
>
> iOS does not SSH into machines. The phone pairs with a brain and connects to its sync websocket over the LAN or a Tailscale tailnet — install Tailscale on both when they aren't on the same network.

> [card] [Key concepts](https://ade-app.dev/docs/key-concepts.md)
>
> The product vocabulary — brain, lane, stack, CTO — in two minutes.

> [card] [ade CLI](https://ade-app.dev/docs/reference/cli.md)
>
> The typed control plane behind everything ADE does.


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