Setup & CLI

Install local capture prerequisites and learn the ade proof commands agents use to record intentional evidence.

Prerequisites

On macOS, ade proof reuses a handful of built-in command-line tools to capture screenshots and short recordings:

• screencapture — bundled with macOS; takes PNG/JPEG screenshots
• osascript — used to coordinate permission prompts
• open — used to surface captures in Finder

No extra install is required on a standard Mac. Agents that need richer browser-level evidence (DOM traces, console logs) should use a browser automation tool of their choice and pipe the results into ADE via ade proof ingest — ADE does not bundle its own browser.

The first time ade proof capture runs, macOS asks for Screen Recording permission. Grant it in System Settings → Privacy & Security → Screen Recording, then restart ADE. macOS requires the process to restart after granting screen recording permission.

---

The ade proof CLI

All proof flow happens through the ade CLI. Agents call these commands from terminal sessions inside a lane, and the results are stored in .ade/artifacts/computer-use/ and linked to the lane, chat session, PR, or Linear issue they originated from.

Command	What it does
ade proof status --text	Show which local backends are available and their capability matrix
ade proof list --text	List captured proofs for the current scope
ade proof screenshot	Capture a screenshot artifact
ade proof record --seconds 20	Capture a short screen recording
ade proof ingest --input-json '{...}'	Ingest proofs produced by external tools (browser traces, verifications, console logs)

ade proof accepts the same --lane, --chat-session, --pr, and --linear-issue owner flags as the rest of the ADE CLI, so agents can attach the captured proof to one or more owners in a single call.

Typical Flow

1. Agent decides to capture evidence

   Mid-task, the agent determines the step deserves a proof — for example, after finishing a UI change that is ready for review.

2. Call the CLI

   The agent runs ade proof screenshot --lane <laneId> (or record --seconds 20) from its terminal.

3. ADE stores and links

   ADE stores the file under .ade/artifacts/computer-use/ and records a ComputerUseArtifact row with kind, owner, and metadata. A link is created to the lane, and any additional owners passed via flags.

4. Review in the UI

   The proof shows up in the chat artifact panel, the PR attachments panel, or the Linear issue attachment list depending on its owners.

Ingesting External Evidence

For proofs that come from outside ADE — a Playwright trace, a browser verification script, a console log bundle — the agent uses ade proof ingest:

ade proof ingest --input-json '{
  "backend": { "name": "my-external-runner" },
  "inputs": [
    { "kind": "browser_trace", "title": "checkout flow", "path": "/tmp/trace.zip" },
    { "kind": "console_logs", "title": "checkout console", "text": "..." }
  ],
  "owners": [
    { "kind": "worker_task", "id": "worker_task_abc" }
  ]
}'

ADE normalizes each entry into a proof record of the declared kind and links it to the declared owners.

---

Storage Layout

.ade/artifacts/computer-use/
  <artifact-id>.png         # screenshot
  <artifact-id>.mp4         # video recording
  <artifact-id>.zip         # trace or log bundle

Each artifact has a row in ADE’s SQLite database with pointers to the file, the owners, the review state, and the workflow state. See Configuration for retention settings.