Skip to main content
Most issues come down to one of a few things: the brain isn’t running, a provider isn’t authenticated, two devices aren’t on the same network, or a remote SSH route is down. Two commands answer most questions: 
ade brain status --text   # endpoint, service, and sync state
ade doctor                # local runtime, git, GitHub, Linear, and provider readiness
ade doctor reports local readiness only — it never calls provider, GitHub, or Linear networks and never prints secret values. It’s safe to run anytime.
The desktop app, ade code, and the iOS app are all clients of the brain — the always-on ADE process for your channel. If it isn’t running, clients have nothing to attach to.
ade brain status --text   # is the endpoint listening? is the service loaded?
ade brain start           # load the login service
ade brain restart         # re-exec after an app update
ade doctor                # broader local readiness check
After a desktop update, the brain re-execs the new bundled CLI on first launch. If clients still look stale, ade brain restart forces it. Before restarting, close active chats, terminals, and mobile sessions that depend on the brain.
A provider only lists models once it’s authenticated.
  • Add the key. Open Settings → AI, connect the provider (Claude subscription or Anthropic key, Cursor API key, OpenCode backend, etc.), and confirm a green status.
  • Give discovery a moment. Cursor and Droid model lists are discovered live and served stale-while-revalidate — a freshly connected provider may need a refresh in Settings → AI, or an ADE restart.
  • For CLI-launched agents (a provider run as a terminal session that isn’t installed or signed in), ADE surfaces an inline auth card in chat with install / login buttons that open a tracked terminal on the active machine.
  • Check ade doctor — it reports provider/model readiness from local config, API-key references, and provider CLI availability.
The phone pairs with a brain and connects to its sync websocket. Two things have to be true:
  1. Paired with a PIN. Generate or set a pairing PIN on the machine and enter it on the phone: 
    ade brain pin generate
ade brain pin set 123456
    You can also manage the PIN from the desktop Mobile control.
  2. Reachable on the network. The phone and the machine must be on the same LAN, or both on a Tailscale tailnet. Install Tailscale on both when they aren’t on the same local network.
Confirm the brain’s sync is up with ade brain status --text (it reports sync state). Note that a manual runtime (ade runtime run) has sync off by design — pairing only works against the brain.
A lane is a git worktree, so a normal delete refuses when the worktree has uncommitted changes. Force it (and optionally remove the branch):
ade lanes list --text                            # find the lane id
ade lanes delete <lane-id> --force --delete-branch
If the lane is an attached external worktree (one you created with git worktree outside ADE), ADE tracks it but never moves or cleans it — detach it in ADE and remove the worktree yourself with git worktree remove.
Remote machines connect over SSH and run ade rpc --stdio on the far side. ADE surfaces the specific failure inline on the remote target; common ones:
  • SSH server at <host:port> closed the connection before ADE could finish the SSH handshake — the TCP route opened but the server reset the handshake. Check Remote Login / sshd, firewall rules, and any Tailscale SSH policy.
  • Remote machine was manually disconnected. Connect again to use this remote project. — you explicitly disconnected; ADE won’t reconnect until you press Connect.
  • ADE stopped automatic reconnecting after 10 failed attempts. Press Connect to try again. — implicit reconnects were paused after repeated failures. Press Connect once the box is reachable.
  • ADE service is not installed … no bundled ADE service is available — the desktop has no bundled runtime for that remote’s architecture. Use a release build that includes runtime resources for it, or install ade on the remote.
  • Remote ADE service version mismatch / does not support multi-project mode — the remote is running an older or mismatched runtime. Re-bootstrap from a current desktop build.
Authentication failures for an agent CLI on the remote (Claude / Codex / Cursor / Droid not installed or signed in) appear as an inline auth card whose install / login buttons run on the remote machine.
A remote project uses the remote machine’s GitHub, Linear, and provider credentials — not your laptop’s. Authenticate providers on the box that’s actually running the agents (the inline auth card targets the active runtime), and expect the remote’s Linear and GitHub connections to drive work that happens there.
When in doubt, run ade doctor and ade actions list --text. The first reports what’s ready locally; the second confirms the brain is reachable and lists every action it exposes.

ade CLI

The full command reference behind these fixes.

Architecture

How the brain, clients, and remote runtimes fit together.