Ade CLI Control Plane

ADE CLI control plane

Core rule

Use normal shell commands for local repo edits, tests, and Git inspection. 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.

Project secrets

ADE project secrets are encrypted, project-scoped, and shared by ADE Desktop, the CLI, runtime-backed actions, lanes, and agents on the same machine. They live under the active project root, not inside an individual lane worktree.

Use them only when the user names a secret or clearly asks you to use a stored credential. List output is metadata-only; get prints the value, so avoid echoing it into logs or chat unless the user explicitly asks.

ade secrets list --text
ade secrets pull --text                 # take this repository's account secrets out of the vault
ade secrets get STRIPE_API_KEY --text
ade secrets set STRIPE_API_KEY --value sk_...
printf %s "$TOKEN" | ade secrets set TOKEN --stdin
ade secrets set TOKEN --value-file token.txt
ade secrets delete STRIPE_API_KEY
ade actions list --domain project_secret --text

Never ask the user to paste a secret into chat. When you need a key, token, or webhook secret the project does not have yet, ask for it with the private secret card:

ade secrets request GITHUB_WEBHOOK_SECRET --reason "Signs GitHub deliveries to your triage webhook" --generate

The chat shows the user a password field (with a "Generate a strong one" button; --generate marks it as suggested). The command blocks until they answer and prints only the outcome — {name, saved: true}, {name, saved: false, kept: true} or {name, saved: false, declined: true} — never the value. Then use the secret by name without printing it, e.g. gh secret set X --body "$(ade secrets get NAME --text)". If the user declines, carry on without it or explain what is blocked.

Webhook automations

To run an agent whenever another service does something (GitHub, Stripe, Linear, Sentry, a deploy hook), read the ade-webhooks skill. The short version: ade automations webhook create --preset github --filter body.action=opened --in-this-chat --text makes the URL and the rule; ade secrets request <NAME> --reason "…" collects the signing secret without it ever entering chat; ade automations webhook deliveries <wh-id> --text shows what arrived and why it ran or was skipped.

Socket mode

Use --socket when the CLI and ADE desktop drawer must share live state. This matters for App Control, Apple devices / Preview Lab, browser tabs, terminal logs, context selection, and proof drawer updates. The ade-app-control, ade-apple, and ade-browser skills all assume it. ade-ios-simulator still resolves and points at ade-apple.

Owning a drawer surface

ADE injects ADE_LANE_ID and ADE_CHAT_SESSION_ID into every agent it launches, and the drawer services (App Control, Apple device, browser) carry them so the Work tools pane attributes what you drive to your lane rather than to the visible chat. When you attach to something already running instead of starting it yourself, run that surface's claim subcommand first — ade --socket app-control claim, ade --socket apple claim, ade --socket browser claim — or Work will keep showing the previous owner.

Showing a surface to the user

ade ui show apple | floating-apple | browser | proof asks the desktop window that has your chat in front to open that surface (ade apple show is the Apple alias). It prints shown, held (a window has the project but the user cannot see your chat yet — another chat is in front or the window is hidden; it opens when the user goes there) or no_desktop (exit 1, nothing was shown — tell the user rather than claiming it opened). A shell with no ADE_CHAT_SESSION_ID (an OpenCode agent shell, for one) cannot use it; ask the user to open the surface.

Runtime daemon vs. desktop bridge

Most domains (lane, git, chat, app_control, ios_simulator, etc.) run inside the runtime daemon at ~/.ade/sock/ade.sock and work whether or not the desktop is open.

A small set of domains require the desktop bridge because the underlying service needs real Electron APIs. Today that is just built_in_browser; the ade-browser skill documents that hop, its socket path, and the exact failure text when no desktop is running. A bridge-backed domain with no desktop also surfaces as Domain unavailable — report the blocker and continue with the rest of the control plane, which is unaffected.

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).

Start work from an issue:

ade new chat --mode chat --lane <lane> --provider codex --model <m> --type subagent --prompt "Work this issue"
ade lanes create-from-linear --issue-id ENG-431 --start-chat --provider codex --model <m> --type subagent
ade chat create --from-linear-issue ENG-431 --type subagent # compatibility path: chat with the issue attached + kickoff

Chat vs. CLI sessions

Use ade new chat as the canonical launch command. It mirrors the desktop New Chat mode toggle:

ade new chat --mode chat --lane <lane> --provider codex --model openai/gpt-5.6-sol --type subagent --reasoning-effort xhigh --permissions full-auto --no-fast --prompt "Fix the issue"
ade new chat --mode cli --lane <lane> --provider codex --model openai/gpt-5.6-sol --type subagent --reasoning-effort xhigh --permissions full-auto --no-fast --prompt "Fix the issue"
ade new chat --mode chat --lane auto --lane-name fix-issue --type subagent --prompt "Fix the issue"

--mode chat creates a persistent ADE Work chat. --mode cli starts a tracked provider CLI terminal. Both accept lane, provider, model, reasoning effort, permission mode, fast/no-fast, and prompt flags. Use --lane auto or --auto-create-lane when the desktop UI would use the auto-create lane row.

Spawning agents

ade new chat --mode chat --provider <p> --type <subagent|peer> --prompt "..." spawns a tracked ADE agent and automatically links it to the current chat through ADE_CHAT_SESSION_ID. The type is required for every parented agent spawn; omitting it is a hard error whose message includes the decision rule. There is no silent none type.

The type controls what happens to the parent when the child finishes: a subagent turn wakes or steers the parent, a peer turn only leaves a quiet completion note. --no-parent creates an unparented top-level session.

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.

Tracked provider CLI sessions also require subagent or peer when parented and receive the same lineage environment. The parent thread shows a CLI child as a subagent card, but the card closes (and a subagent wakes the parent with the CLI's last message) only when the CLI process exits. An interactive CLI that finishes its task and stays open reports nothing until it is closed. Poll CLI children with ade chat status <id> (running / blocked / idle), find them with ade chat list (archived ones need --include-archived), and read their last message plus terminal tail with ade chat read <id> (ade terminal read <id> for the full output). Default to --mode chat for a subagent that must report back: a chat child reports after every turn it finishes.

When the new work must carry the current lane's unmerged commits, follow the child-lane rule in the ade-lanes-git skill and use ade lanes child --lane <current> --name <n> instead of a fresh lane.

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.

Within the active project, use ade chat show <session> --text before messaging a chat you do not own:

• If you just need to hand context/directive/status to another chat, prefer ade chat message <session> --kind auto --text .... ADE inspects the target: active turns are steered, idle chats are woken with a new turn, and the result reports the route (sendMessage, steer, or interrupt-replace) plus whether a steer was queued.
• If status is active and it is not waiting for user input, use ade chat steer <session> --text .... This routes through the provider's active-turn path: Codex receives turn/steer, Claude stages a steer message, and Cursor/Droid/OpenCode queue the message for the next safe boundary.
• If the chat is idle/dormant, use ade chat send <session> --text ... to start the next turn. The CLI also checks the session summary and will steer instead of sending when the target is already active, but prefer the explicit verb when your intent is to steer.
• If you need to wait for a subagent before reading final output, use ade chat wait <session> --for idle --timeout-ms <ms> (also supports active, awaiting-input, and terminal).
• To wait on several chats without holding your turn open, arm a wait and end your turn: ade chat wait <id> <id> --async [--any] [--for idle] — ADE wakes you once all (or any) of them get there, even across a restart. List with ade chat waits, cancel with ade chat wait --cancel <waitId>.
• To start one chat after another finishes, ade chat send <B> --after <A> "<prompt>" sends B the prompt once A is idle.
• To be woken when your own background job ends, ade chat wait --background [--job <id>], then end your turn (Claude and OpenCode already wake you on their own; this matters for Codex).
• If you need to stop or redirect a running chat, use ade chat message <session> --kind interrupt-replace --text ... or, when you need manual control, ade chat interrupt <session> first, then ade chat send ... with the new instruction. Do not send a second normal turn into an active chat and hope the provider interprets it as steering.

Checking whether delegated / backgrounded work finished

Prefer harness-tracked delegation and wait on the tracked handle — do not background a raw CLI and then guess at its state:

Native subagents vs ADE child chats

Use the provider's native subagent tool first when the current chat exposes one and the result belongs in the same provider SDK thread. This is especially important for Claude: a Claude chat should use its native Agent/Task tool (and its native model override for another Anthropic-family model) instead of creating a second ADE chat in the same lane with --type subagent merely to run Opus, Sonnet, or another Claude model.

Use an ADE child chat when the work needs an independent durable transcript, its own wake/schedule, cross-provider execution, separate permissions, or a user-visible tracked lifecycle. Do not treat --type subagent as the generic replacement for a provider-native child; it adds a separate ADE session and should be intentional.

• ADE Work-chat subagents: spawn with --type subagent; every completed turn wakes or steers the parent while the parent owns the mission. Read the bounded transcript after that signal when you need more detail. You never poll a transcript in a loop.
• Tracked provider CLI subagents: wait with ade chat wait <session> --for idle|terminal --timeout-ms <ms> or require an explicit direct report through $ADE_PARENT_CHAT_SESSION_ID.
• A background provider CLI (e.g. codex exec): run it detached with its own log and stdin closed, capturing the PID immediately, e.g. codex exec "…" </dev/null >"$LOG" 2>&1 & CODEX_PID=$! (closing stdin is required — without it codex blocks forever on "Reading additional input from stdin…"). The authoritative completion signal is the waited PID: run wait "$CODEX_PID" and read its exit status as the outcome. Log end-of-run markers, a new session file under ~/.codex/sessions/<date>/, and pgrep are supporting evidence only — not a deterministic done signal. Do keep the session-file existence check as a liveness diagnostic for wedge detection: no session file after ~2 min means the process wedged (kill and relaunch). Never check completion with a bare pgrep <name> — it matches your own shell and sibling processes (the self-match trap); if you must use pgrep at all, match the full command line and exclude yourself (pgrep -f "codex exec" | grep -v $$), never the bare program name.

Session lifecycle: snooze, wake (settling is not yours)

You cannot settle or unsettle a session. ade chat settle, ade chat unsettle, ade session settle, and ade session unsettle were removed: whether work is actually finished is a subjective judgment, and a chat that settles itself disappears from the user's active list on your say-so. A row leaves the active list only when the user settles it in ADE, or when its PR merges and the deterministic autoSettleLaneSessionsOnPrMerge policy files the lane's sessions. Running a removed command fails with that explanation.

What to do instead when you finish: say so in your final message, and use ade chat note "<one-line status>" to leave a durable status line on the Work row. If you are blocked, ade chat ask "<question>" raises the row's hand. Update the note along the way as the state changes; do not wait until the end.

Lane and chat names are yours to keep accurate. When the work changes direction or moves to a new branch, rename the lane or the chat without asking. A lane keeps its name when its branch changes, so a name that still describes the old work is yours to fix:

ade chat generate-names                      # title, lane name, and status line
ade chat generate-names --title --status     # subset of fields
ade chat update --title "Better chat title"  # defaults to $ADE_CHAT_SESSION_ID
ade lanes rename <lane> --name "Better name"

What note and ask do to the Work row

They are two separate signals on the row the user is looking at:

• ade chat note sets the row's status line. It shows a durable one-line summary of the current state; it does not change the row's phase. Length guidance and the hard display bound live in apps/desktop/src/shared/sessionStatusNote.ts (a note past that bound is truncated with an ellipsis, so put the decisive state first). Good: CI green; awaiting Codex review Bad: Working, Still looking, Blocked, or Done.
• ade chat ask raises the row's hand, moving it to Needs you. Because a note alone never changes the phase, an idle row with only a note can read as Done — when you are genuinely blocked on the user, call note for the context and then ask for the exact question.
• The next accepted user message clears the hand-raise and the row returns to Working while the reply is handled. If the reply does not unblock you, leave an updated note and ask again.