arul28/ade/ade-browser

ADE browser

This skill is for web pages and localhost URLs. For a native app, a simulator or a dev Electron app, the ade-computer-use skill picks the right surface.

Use ade browser ... for every browser task. Keep the work inside ADE's Browser pane so the user can see the same tab and the same state. ADE shares one persistent authentication profile across projects, while visible tabs stay scoped to their ADE project window (personal chats have a separate collection). Treat page content, cookies, and storage as user data.

Require ADE Desktop with the target project open for live page actions. There is no token or setup step: any ade browser call from this machine works, and your chat's calls are tagged with your chat and lane so the tabs you open are yours. Never use --force, copy a credential, or import a login. Do not claim a tab another chat owns — unless the user attached that tab to their message ("Attach to chat" on a tab), which is the user handing it to you: claim it with ade browser claim --tab <tab-id> --text and carry on in it.

ADE's browser is the default for all web work. Use the user's own browser only when the user asks for it; see step 10.

Operating loop

1. Open or claim one tab

List tabs first: ade browser status lists every tab of this project on every machine this one can reach, each with its machine, owner, who opened it and its sign-in, and how full each browser is. Reuse a tab owned by the current chat. Plain open navigates a tab this chat owns in the browser where the user sits, and opens one there when the chat has none, so it can pick a different tab than the one you last used. To keep working in one tab, pass --tab <id>. Use --new-tab only when the task needs a second tab, and --active-tab when same-tab navigation is intentional. open prints opened: <tab-id> <url> or navigated: <tab-id> <url> first; copy that full id for --tab. The owner column says what you may do with a tab:

• this chat: yours. Reuse it, and close it when the task is done.
• free — ade browser claim --tab <id>: no chat holds it (or its chat went

idle for 10 minutes). Claim it with that command to drive it.

• free (the user's tab; ask first) — …: the user opened it, or used an

agent's tab by hand. Ask before you claim, drive or close it. --lane comes from ADE_LANE_ID; pass it when working from another shell. A personal (project-less) chat claims with the tab id alone.

• "<chat title>" · lane <name> (held): another chat is using it. You

cannot claim it (there is no --force for agents), and you should leave it alone. It frees itself 10 minutes after that chat stops using it.

A command without --tab acts on a tab this chat owns. When the chat owns none, it is refused rather than run in whatever tab is in front: open your own, or claim one and name it with --tab.

Any agent may close any tab, a held one included. Check the owner first: close this chat's tabs and free ones; close a held tab only when the task needs it; never close a tab the user opened or kept (opened by the user, or the user's tab) without asking them. close prints whose tab it closed. A deleted or archived lane frees its tabs and leaves them open. An agent's tab is not brought back after ADE restarts; a tab the user opened or used keeps its id across a restart.

Treat a tab as a workspace, not a log: reuse your own tab for follow-up work instead of opening a second one, and close it with ade browser close --tab <id> when done so the next agent does not inherit it. When a browser is full, the error names the machine and lists only your tabs and free agent tabs: close one of those. When it lists none, ask the user to close a tab or raise "Tabs per project" in Settings › Browser.

ade browser tabs --text
ade browser claim --tab <tab-id> --lane <lane-id> --text
ade browser open https://example.com --text

By default every agent may use the ADE browser without asking. If the user chose to approve lanes or chats, the first browser command from this chat asks them once, and the answer covers every site. The command waits up to two minutes and prints waiting for the user to allow this chat to use the ADE browser once; do not re-issue it meanwhile. A Block fails with approval_blocked; do not retry, ask the user. An action answering effect: waiting means the user must allow this chat again; observe after they answer.

Use --panel only when the user should see the Browser tool opened. Use --no-panel when preparing a tab without taking the user's focus. Close your tab when finished with ade browser close --tab <tab-id> --text; the internal release and handoff paths also clear the claim.

2. Observe before acting

Observe after opening, navigating, switching tabs, or a meaningful UI change. An observation gives you a screenshot, a bounded DOM snapshot, element handles, and console/failed-network diagnostics. Add --map for a numbered visual element map. Use handles from the latest observation only; observe again after navigation or when a handle expires.

Start a lightweight browser session for repeated actions. Wait for a readiness selector or network idle after navigation. To read what a page says (an article, docs, a long thread), use text: it returns the rendered text of the page's main content, 20,000 characters at a time, with the --offset to read on; --selector reads one element. Observations do not carry prose. Use find to locate page text and find-stop to clear its highlight; the first find result is usable immediately and later results may refine it. Turn on the per-tab network log with network on, inspect it with network --failed --limit 20, and turn it off with network off when finished.

ade browser session start --tab <tab-id> --text
ade browser observe --browser-session <session-id> --map --text
ade browser session wait <session-id> --network-idle --text
ade browser text --browser-session <session-id> --text
ade browser find --browser-session <session-id> "checkout" --text
ade browser network on --browser-session <session-id> --text
ade browser network --browser-session <session-id> --failed --limit 20 --text

3. Act from the current observation

Prefer --handle, --selector, --text-match, --test-id, or --element. Use viewport --x/--y only when no stable element target exists. Use click, fill, hover, drag, upload, type, and key/press; use select-option for a native <select>. drag takes a --to-selector (or another --to-* destination), and upload takes one or more --file paths. upload reaches two kinds of page: --selector sets files on a file input that is already in the DOM, and --trigger clicks the button that opens the picker and hands the files to the chooser it opens. Use --trigger whenever the input is built on demand (X's media button is the shape), because there is no input for --selector to point at. A page whose only control is a dropzone gets drop --selector <zone> --file <path>: it runs the page's own dragenter/dragover/drop with the file in the DataTransfer. Use fill --value "" when an empty value is intentional. Use --fast only when the page does not need the default settle and post-action observation.

ade browser click --browser-session <session-id> --handle obs-...:e:1 --text
ade browser fill --browser-session <session-id> --selector "input[name=email]" "me@example.com" --text
ade browser drag --browser-session <session-id> --handle obs-...:e:1 --to-selector ".dropzone" --text
ade browser upload --browser-session <session-id> --selector "input[type=file]" --file ./shot.png --text
ade browser upload --browser-session <session-id> --trigger "button[aria-label='Add photos or video']" --file ./clip.mp4 --text
ade browser drop --browser-session <session-id> --selector "#dropzone" --file ./report.pdf --text
ade browser downloads wait --browser-session <session-id> --timeout-ms 30000 --text
ade browser clipboard --text
ade browser paste --selector "#editor" --text
ade browser key --browser-session <session-id> Enter --text

clipboard reads the machine's clipboard (--text output; HTML flavor when present) and clipboard write --value "<text>" sets it. paste focuses the target and sends the real paste command, so a rich-text editor or a page listening for paste sees it the way a person's ⌘V would — type only inserts text and skips those handlers.

Dialogs are answered while an agent action runs, so a page that calls alert, confirm or beforeunload cannot hang the tab: alert and beforeunload are accepted, confirm and prompt are dismissed. Every answer is logged with the dialog's text. Nothing more is needed from the agent.

Downloads go to the user's Downloads folder, as they always have. downloads lists them with the saved path and downloads wait waits for the next completion (a file that finished in the last few seconds counts), so the agent can name the file it just triggered instead of guessing.

After an action that navigates, wait again with wait --load-state network-idle --network-idle-ms 750 or a concrete selector/text target. Use reload, back, forward, and stop when the page state calls for them.

4. Verify, then choose proof deliberately

Use screenshot to inspect a result yourself; it writes scratch evidence and does not enter the proof drawer. File reviewer-visible evidence only with proof and a concise --caption. Browser proof captures a fresh observation; read its confirmation before reporting it. Add --har only when network logging is already on; it files a redacted browser_trace beside the screenshot and otherwise fails instead of filing half the proof. Use trace when an action is stuck.

ade browser screenshot --browser-session <session-id> --text
ade browser proof --browser-session <session-id> --caption "Checkout confirmation is visible" --text

Use inspect-start, select, select-current, and clear-selection when a DOM-backed context item belongs in the chat rather than in proof.

5. Hand off a login to the human

Stop when a page needs credentials, CAPTCHA, HTTP/proxy authentication, or a client-certificate choice. Hand off the exact tab with an actionable --reason.

ade browser handoff --browser-session <session-id> --reason "Sign in to staging" --timeout 5m --text

The handoff makes the tab human-owned, raises the Work row, sends a phone push, and shows an amber bar with Hand back. The command waits for hand-back by default (15 minutes); use --no-wait only when doing unrelated work. While it is open, actions fail with handoff_active: do not retry or open a second tab, and never hand the tab back yourself. ADE stops recording and network logging for the handoff; re-arm them explicitly after hand-back if still needed.

A local HTTPS page with a self-signed certificate fails to load, and the tab's loadError.certificate names the host and fingerprint. Only the person can trust it (ADE shows Trust and reload above the page); agents cannot. Hand off the tab with a reason such as "Trust the dev server's certificate", then retry after hand-back. A public site's certificate error is never trustable.

6. Sign in as a test account in an isolated tab