arul28/ade/ade-cli-control-plane

ADE CLI control plane

Core rule

Use normal shell commands for local repo edits, tests, and local Git. Push, pull and fetch with ade git (see ade-lanes-git). Use ade when you need ADE state or ADE-owned services: lanes, chats, PR metadata, proof/artifacts, managed terminals, App Control, iOS Simulator, browser, settings, project secrets, usage, updates, or service actions.

Do not route ordinary repo commands through ADE chat-attached terminals. Those terminals exist so ADE Work chats can expose long-running process logs or let a user inspect/control a chat-owned shell. In a tracked CLI session, run normal shell commands through the CLI's own shell/tooling; use ade terminal ... only to inspect or control an existing ADE-owned terminal session.

First checks

1. Run ade doctor --text when the ADE environment is unclear.
2. Run ade help <command> or ade help <command> <subcommand> before guessing flags.
3. Prefer --text for human-readable output and JSON output when scripting.
4. Use ade actions list --text or ade actions list --domain <domain> --text as the escape hatch for service methods without a typed command.
5. Before running an action, ade actions describe <domain.action> --text prints its read/write access, description, documented input fields and an example (actions without a documented contract say so).

Detail files

Rarely needed detail lives next to this file. Read one when its topic comes up (or ade skill show ade-cli-control-plane references/<file>):

Secrets

Never ask the user to paste a secret into chat. Ask with the private card: ade secrets request NAME --reason "<why>" (add --generate to suggest a strong one). Use a stored secret by name without printing it: gh secret set X --body "$(ade secrets get NAME --text)". Read secrets only when the user names one. Webhooks (run an agent when another service does something) are the ade-webhooks skill. Full detail: references/secrets-and-webhooks.md.

Connecting an integration

GitHub, Linear and Jira are ADE integrations: ADE holds the credential, and you use them through ade prs, ade github, ade linear and ade jira. Agent 37 (cloud Linux machines) is one too: once connected, the person makes machines from Add a computer in ADE; there are no ade verbs for it yet. Never ask for a key in chat. Check, then ask with the connect card:

ade integrations status --text
ade integrations connect linear --reason "To read the issues you mentioned and move them to In Review"

The card offers a browser sign-in where the provider has one, otherwise the key fields; ADE checks the key, then saves it. The command blocks and prints only the outcome: {provider, connected: true, method, account, next} or {provider, connected: false, declined: true} (method: "already" when it was connected). If the person named the integration, raise the card at once; if it was your own idea, ask in words first.

The running app

Browser, App Control, Apple device and proof commands talk to the running ADE app. They find it on their own; you do not need --socket. When ADE is not running they fail with a clear error instead of acting on a copy. To show a surface to the user: ade ui show browser|apple|proof. To take over a surface you did not start: that surface's claim command. Detail: references/app-surfaces.md.

Linear issues attached to your session

The ade-linear skill is the home for working an attached Linear issue: the env vars ADE injects, the read/write commands, and attach/detach. You never need a Linear token — ade linear ... routes over the daemon to the desktop runtime, which holds the credentials. Two attachment commands live outside that skill's ade linear surface:

ade chat attach-linear-issue <session> --issue-id ENG-431
ade lanes link-linear-issue <lane> --linear-issue-json '{...}'

Sync and pairing

• ade sync web [--open] — print + copy the web-client pairing link and code (pair a browser to this machine).

Starting chats

Do the user's work in this chat and this lane. Start another chat or lane only when the user asks, or when they ask another model to do part of the work (below). ade new chat is the launch command:

ade new chat --mode chat --provider codex --model openai/gpt-5.6-sol --reasoning-effort xhigh --prompt "Fix the issue"
ade new chat --mode chat --lane auto --lane-name fix-issue --prompt "Fix the issue"     # only when the user asks for a new lane
ade lanes create --name ENG-431 --issue-id ENG-431 --start-chat --provider codex --model <m>   # a lane for an issue, when asked

Always use --mode chat. --mode cli starts the provider's own CLI in a terminal instead. ADE cannot tell reliably when a terminal finishes a task, so it is told it is your subagent and messages you its reports itself. Use it only when the user asks for a terminal.

Spawning agents

When the user asks you to have another model or agent do work, start a subagent. Do this unless they ask for a separate chat:

ade new chat --mode chat --provider <p> --model <m> --prompt "<task>"

From an agent this is your subagent. It runs in your lane, under your chat, and reports back after every turn it finishes: ADE steers you if you are busy and wakes you if you are idle. Two opt-outs, used only when the user asks:

• --type peer: linked to you, leaves only a quiet note when it finishes.
• --no-parent: a separate top-level chat that does not report back.

ADE is a mesh. You can read, message, interrupt, or stop any chat, whoever started it, but act on a chat that is not yours only when the user asks. Stop a chat with ade chat interrupt <session>. A chat with no parent can be made your subagent with ade chat set-parent <session> --parent $ADE_CHAT_SESSION_ID.

For persistent Work chats, a subagent turn reports back with its child turn id and latest assistant summary whenever the parent still owns the child's mission — including turns the child's own scheduled wakeups start, so a long self-paced mission still reports when it actually finishes. ADE steers an active parent or wakes an idle parent. Once a human messages the child directly, ownership moves to the human and completions become quiet notes until the parent dispatches again. The persisted parent link and turn metadata survive brain restarts; a missing parent is noted once in the child and stops the report channel. A delivery failure against a parent that still exists retries and then becomes one visible warning in the child. Every child receives ADE_PARENT_CHAT_SESSION_ID and direct-report guidance while that parent is reachable.

A --mode cli child sends its own report with ade chat message when it finishes a task, and ADE adds one more when its process exits. Check any child with ade chat status <id> (running / blocked / waiting / idle; waiting means its turn ended but work it started still runs, so it is not done yet) and read it with ade chat read <id> (ade terminal read <id> for the full output). To give it a new instruction, type into it: ade terminal write --terminal <id> --data "<text>\n".

Which lane a child goes in. An ADE child chat is a subagent that can run another provider, so it works where a native subagent would: in your lane, under your chat. Leaving --lane out picks your lane when ADE_LANE_ID is set (it is in an ADE chat or lane shell); elsewhere pass --lane <your lane>. Create a new lane for it (--auto-create-lane, ade lanes create) only when the user asks. Agents in one lane share its Apple device: let one agent drive it and hand that agent the device work (see ade-apple).

When the new work must carry the current lane's unmerged commits, use ade lanes create --name <n> --from <your branch> --on local to continue unmerged work. Use --on uncommitted to copy uncommitted changes too.

Transcript reads are silent and available for any project-backed chat in any registered project on this machine. Personal/no-project chats remain on the separate --personal surface and are not included. Reads are bounded by default; inspect a recent window, then page older content deliberately:

ade chat read <session> --limit 20 --max-chars 8000 --text
ade chat read <session> --page --cursor <nextCursor> --limit 20 --max-chars 8000 --text

The first read returns truncated when more content exists. A paged read returns nextCursor; repeat only while you actually need older context. Do not dump an entire long transcript into the model context. --max-chars is a hard response ceiling; a single oversized entry is visibly clipped and the response sets truncated. This machine-wide route is read-only; it does not broaden cross-project message or mutation routing.

Claude models in a Claude chat

In a Claude chat, run another Claude model (Opus, Sonnet, Haiku) with the native Agent tool and its model override. It is a subagent in the same thread. Use an ADE subagent chat for a model from another provider.

A raw background CLI (codex exec in a shell) is not tracked by ADE. Prefer an ADE subagent chat. If you must, close its stdin (</dev/null), capture the PID, and wait "$PID" for its exit status; never use a bare pgrep, which matches your own shell.

Messaging and stopping other chats

Any chat, whoever started it. Act on a chat you did not start only when the user asks.

• Send: ade chat message <session> --text "...". ADE picks the route: an

active chat is steered, an idle one gets a new turn. This is the only send verb you need.

• Stop: ade chat interrupt <session>. To redirect, stop it, then

ade chat message the new instruction.

• Long or multi-line text goes through --text-file - (stdin) or a path,

never an argument. A long first prompt for a new chat is --prompt-file -:

``bash ade chat message "$ADE_PARENT_CHAT_SESSION_ID" --text-file - <<'REPORT_END' ...the report... REPORT_END ``

On Windows, never pass multi-line text to ade.cmd (cmd.exe cuts it at the first line break). In PowerShell, write the text to a file and pass --text-file $f, or call & $env:ADE_CLI_PATH. In Git Bash, call ade with a here-doc.

• A chat waiting on a question or approval refuses messages (error

-32011). When your subagent asks a question, ADE forwards it to you with the options. See it with ade chat pending <session> --text, then answer with ade chat respond <session> --option 2 (or --text "<answer>"; --answer 1=<v> --answer 2=<v> for several; --item <id> when more than one is open). Questions that need the person (money, credentials, a product call) and every approval are theirs: tell them, and do not start a second chat for the same work.

• Restart: only when the user asks (to pick up new skills, plugins, MCP

servers or instructions), run ade chat restart. It restarts your chat after this turn; finish your reply first.

Waiting for work to finish

Never poll and never block on a long wait. Match the thing you wait on: