BETAv0.24.11
GitHub Install
Agent mode
Docs/ADE/Agent mode

Agent mode

Edit on GitHub
docs-site/ade/agent-mode.md

The ADE is the Orrery desktop app. It has two modes, switched in the top bar: Agent mode and IDE mode.

Agent mode runs Orrery harness sessions, drawn as a chat. It has no terminal and no CLI agents; those live in IDE mode.

First open

The ADE does not ship orrery. The first time you open Agent mode without it, the ADE offers to install it into ~/.orrery/bin, from the same release files and checksums as the install scripts. It shows progress, lets you cancel, and says what to do if it fails.

At connect, the ADE checks the harness version. It offers an update, or says that the ADE itself is too old.

The path to the binary is the setting harness.bin. Setting it by hand does the same as the install button.

The rail

The rail lists every harness session on your machines, whoever started it: the TUI, the ADE, Orrery Cloud or the phone. Each row shows the machine, the state, the cost and the context. Rows are grouped by repository.

Sessions on other machines appear once you sign in to Orrery Cloud (Settings → Orrery Cloud). An offline session opens in a read-only view instead of being greyed out.

Orrery Cloud in the ADE

Use this computer. After your first Cloud sign-in the ADE asks once: Use this computer as a machine in Cloud. Yes joins this computer's node (orrery node join, with a one-time token; no device code) and restarts it so it dials the relay. Its sessions then show on your other screens. The answer is remembered; Settings → Orrery Cloud has the same switch. Turning it off stops nothing: remove the machine in Cloud to leave. Opening the ADE again never adds a second machine.

Status bar. The Cloud item shows the link, and a click opens Settings → Orrery Cloud.

ShowsMeans
Cloud: signed outYou are not signed in.
Cloud: connecting…Connecting.
Cloud (green dot)Connected. Changes from other screens arrive at once.
Cloud unreachable · retry in 12sCloud did not answer. The ADE retries on its own, waiting 1 s up to 30 s; Retry now in Settings tries at once.
Cloud: sign in againThe sign-in expired. Use Sign in again in Settings.

Auto-reattach. An open chat reconnects by itself when the link returns and continues from where it stopped, with no Retry.

See Orrery Cloud and your machines for joining, config history and continuing offline sessions.

Start a session

New session asks three things:

  1. Machine: this one, or another on your account.
  2. Repository: each new session gets its own worktree on a branch agent/<id>, so two sessions on one repository never share a folder.
  3. Provider and model: skipped once providers.default is set on that machine. A first-time setup on this machine writes the same keys orrery providers add writes. A remote machine without providers says to set them in Orrery Cloud.

Work in it

  • The chat draws the same thread as the TUI: messages, folded tool lines, reasoning, the consent bar, the status line and the mark.
  • Consent prompts appear inline. Needs you, in the top bar, counts the prompts waiting across every session; open it to jump to one and answer it.
  • The changes column lists the session's live changes. A file opens its diff.
  • Commit, Push and Open file run on the session's own machine, as your action, not the agent's. They need no consent prompt and are audited as yours.

A turn typed in the ADE shows in an attached TUI, and the other way round.

Keys

Ctrl+K shows every command. j / k walk the sessions; Alt+N jumps to the next blocked one. Settings → Keymap lists every binding, with a VS Code and an IntelliJ preset.