All pages

Docs · Right-sidebar surfaces

Browser

Availability: macOS. The cloud workspace has its own browser_* tools against a different engine; the GTK app has none until the CDP backend lands — see Platforms.

The Web tab in the right sidebar is a minimal browser embedded in TRMNLY, running on system WebKit or on the Chrome installed on your Mac. Think of it as a dev-tools-adjacent view, not a daily-driver browser — handy for:

  • Reading docs while you work without context-switching to Safari
  • Loading a localhost dev URL the agent just started
  • Letting the agent navigate, click, screenshot, and automate a page through a Playwright-shaped tool surface

Engine

The chip beside the address bar picks the tab's engine. WebKit is the default; the two Chrome rows are Chrome — TRMNLY profile and Chrome — copy of your profile. With Chrome absent a single disabled Chrome — not installed row takes their place, so a feature you remember is never simply missing from the menu.

A Chrome tab is the Google Chrome on your Mac, driven over the DevTools protocol and painted into the same sidebar. The tab strip, address bar, find bar, console and network panes and every browser_* tool work the same either way. Two caveats: switching engines reloads the page, and cookies and logins don't move between them.

The two profiles differ in what a tab can reach:

  • Chrome — TRMNLY profile uses a directory TRMNLY owns, keyed by browser session. It is the default because an agent driving a tab in it cannot touch your real browsing.
  • Chrome — copy of your profile takes a copy of your Chrome profile, extensions and logins included, the first time you pick it. It is a copy because Chrome refuses remote debugging against the profile it is signed into — so a login you make in Chrome afterwards is not in the copy.

If Chrome can't start, the tab says why and offers Retry or Switch to WebKit rather than sitting blank.

Reach for Chrome when a page needs Chromium specifically: a site that gates on it, a Chrome extension, WebUSB / WebSerial / WebBluetooth, or checking a dev preview in the browser most of your users run.

Choosing an engine from a tool

browser_new_tab takes engine, either webkit (the default) or chrome; with Chrome not installed it refuses with an explanation instead of falling back quietly. Every tab a tool reports carries its engine, so an agent never has to infer which one it is driving. It returns once the tab's first page has loaded (up to 10 s, with a note when it hadn't), so a browser_eval_js sent next runs on that page rather than on the blank one the load would replace.

Every other browser_* tool routes to whichever engine its tab runs — screenshots, PDFs, viewport and user-agent emulation, cookies, data clearing, request blocking, permissions and trusted input all work on a Chrome tab. Three things are better there:

  • Viewport emulation is the browser's own, so the layout viewport really is the size you asked for and CSS media queries, innerWidth and a meta-viewport tag all agree. WebKit approximates the same request with page zoom plus a JS shim.
  • Screenshots don't need the tab on screen.
  • Trusted clicks and typing go through Chrome's input pipeline rather than the window server, so they land with the sidebar collapsed and don't steal your keyboard.

The exception is browser_ax_locate, which is WebKit-only: it reads the macOS accessibility tree, and a Chrome tab has no view in TRMNLY's process. It says so and points you at browser_locator / browser_query_all, which work on both.

Multiple tabs

The browser has its own tab strip. Add a tab (+), close with the × on each tab. Tabs persist across relaunches.

Which tabs the strip shows

The Browser tabs dropdown in the sidebar header picks the set:

  • This terminal tab (the default) — tabs that belong to the terminal tab you are in. Switching terminal tabs switches browser tabs with it.
  • All project tabs — every browser tab of every terminal tab in the current project and worktree, plus a bucket the project shares. A tab from another terminal tab is shown in place; a new tab lands in the shared bucket.
  • All TRMNLY tabs — every browser tab open anywhere in TRMNLY, from every terminal tab and every project, in one strip. A new tab belongs to the terminal tab you opened it in, and every window's strip shows it.

The choice applies to every window at once and is remembered. A tab an agent or an MCP client opens goes into the browser visible in that project's window, whichever mode is on, so it is where you are looking. A tab shown from another terminal tab is the same page, not a copy; if another window is already showing it, this one offers Show Here.

Tab suspension

Browser tabs auto-suspend when none of the following are true: the right sidebar is expanded, the Web pane is active, and the window is key. Suspended tabs pause media playback and let WKWebView throttle JS timers — keeping a sidebar tab open with a noisy WebSocket no longer costs CPU. Resume re-renders the tab but doesn't auto-resume audio (matches Safari).

Design mode — point at an element

The crosshair button next to the address bar puts the tab in pick mode. Hover outlines whatever is under the pointer; click freezes it. While pick mode is armed the page's own handlers never fire — mousedown, mouseup, click and Escape are all swallowed — so picking a "Delete account" button picks it rather than pressing it. Escape leaves pick mode without choosing.

The strip under the address bar then shows what's held: the element's tag, id or first class, its size, the project and worktree the tab is bound to, and buttons to copy the selector or forget the selection.

What the agent sees, on its next browser_state, is a selection block:

  • selector — a stable CSS path it can pass to any other browser tool.
  • styles — only the computed values that differ from a bare element of the same tag, so three meaningful properties aren't buried under three hundred inherited ones.
  • html — the element's markup, pruned past four levels deep and capped at 8 KB. When that bites, html_clipped is true and descendant_count says how much was left out; picking <body> gives a bounded answer rather than the whole document.
  • box and a cropped screenshot of the element, attached to the result.
  • stale: true once the page navigates, because the selector may now match something else entirely.

boundWorktree on the same payload names the checkout the page belongs to, so an agent editing one worktree can tell when the preview it is looking at came from another.

The payload is engine-neutral by design — the same script produces it in Chromium — so this is the shape other TRMNLY hosts will report when their browsers grow a picker.

Agent automation

The agent's browser tool surface is large and Playwright-shaped. Highlights:

browser_state, browser_navigate, browser_back, browser_forward, browser_reload, browser_list_tabs, browser_new_tab, browser_select_tab, browser_close_tab, browser_list_windows, browser_new_window (open a fresh TRMNLY window with its own browser sidebar — handy for comparing two sites side by side). browser_window_position / browser_window_resize move or size the window that owns a tab (for real multi-monitor or screen-edge tests; browser_viewport is cheaper for layout). browser_diff_navigate snapshots the URL, page text, console and network counts, navigates, waits for network idle and returns what changed. browser_prewarm_tab spins up the WebKit process the next tab will use, hiding a few hundred milliseconds of first-load latency.

Pinning a tab. browser_attach_tab pins one browser tab as the target for every browser tool across all windows until browser_detach_tab releases it. Use it so a sequence of calls can't accidentally land on the wrong window's foreground tab.

Tab lifecycle. browser_pin_tab / browser_unpin_tab (keep a tab in the strip), browser_duplicate_tab, browser_undo_close (reopen the last closed tab), and browser_hibernate_tab / browser_wake_tab — hibernation drops the tab's web view but keeps its URL for reload. Idle background tabs also auto-hibernate after a configurable threshold (default 30 minutes).

Page inspection

browser_eval_js, browser_get_text, browser_screenshot, browser_console, browser_network, browser_wait_for, browser_outer_html, browser_describe_at (pick element at viewport coords), browser_inspect_at (the same point, answered as a handle), browser_describe_locator (natural-language → top-N candidates), browser_list_frames, browser_list_inputs, browser_shadow_query, browser_frame_eval, browser_a11y_tree, browser_pdf, browser_find (count find-bar matches without opening it), browser_reader_text (Readability-style article extraction), browser_dom (rendered HTML and/or a compact tree of visible elements — prefer it over browser_get_text when you need structure).

More inspection helpers: browser_extract (a {key: selector} schema in, typed JSON out — one call instead of get-text-then-parse per field), browser_observe (start / peek / stop a window over the console and network, for everything a multi-step flow logged in between), browser_network_pattern_wait (block until a request matching a URL, method or status arrives), browser_wait_for_idle (network quiet for quiet_ms), browser_console_clear, browser_perf_record (Web Vitals — LCP, CLS, INP, FCP — plus long tasks; arm, read, clear), browser_repl (a JS namespace that keeps state across evals until the page navigates; same allow_eval gate as browser_eval_js), and browser_text_diff (line, word or character diff of two strings). browser_screenshot_elements clips one PNG per selector; browser_screenshot_all tiles every tab (or a chosen few) into one captioned grid for design QA across breakpoints or accounts. browser_annotate_screenshot opens a screenshot in a markup overlay so you can circle or label something, and hands the annotated PNG back to the agent when you click Save.

browser_inspect_at { x, y } takes a viewport coordinate in CSS pixels — usually the middle of something the agent spotted in a screenshot — and returns the topmost element under it: a ref, plus tag, ax_role, ax_name, selector, bbox and attributes (id, classes, data_testid, aria_label). The ref is what closes the screenshot → action loop: hand it straight to a click or type tool instead of turning the pixel into a selector first. Nothing under the point comes back as ok: false with reason: "no_element_at_point".

Assertions for test-style flows: browser_expect (auto-waiting, Playwright-shaped), browser_assert_text, browser_assert_url, browser_screenshot_compare (pixel-diff two PNGs), browser_visual_assert (compare against a stored per-project baseline).

Interactions

browser_click, browser_type, browser_key_press, browser_hover, browser_drag, browser_scroll, browser_touch (mobile viewports), browser_upload (files via DataTransfer, with no picker; a person clicking an upload button in the WebKit tab gets the standard file picker, multi-file and folder uploads included), browser_form_fill (multi-field), browser_form_submit (fill, then requestSubmit() so the page's submit listeners fire), browser_select_option (native <select> by value or label), browser_key_chord (a sequence like ["Cmd+S","Enter"]; trusted for real OS keystrokes).

  • browser_act — click, wait (idle, a selector or a URL), then optionally assert text or URL, in one call.
  • browser_click_at — click at viewport coordinates with a real OS click, for canvas, video and map widgets a selector can't reach.
  • browser_drop — synthesize an HTML5 drop of files or DataTransfer data on a drop zone.
  • browser_paste — fire a JS paste event with {mime: contents} for editors (Monaco, ProseMirror) that ignore the OS pasteboard; browser_set_clipboard writes the real system clipboard instead.
  • browser_until — repeat any browser_* call until a selector, URL or text condition holds (at most 50 times).
  • browser_login_with — navigate to a saved account's site, autofill, submit and wait, with the account's host enforced (see Accounts vault).

Playwright-shaped locators

browser_locator (getByRole, getByText, getByLabel, getByPlaceholder, getByTestId, getByTitle, getByAlt), browser_query_all, browser_xpath. Returns CSS selectors that the interaction tools accept.

browser_click, browser_type and browser_screenshot also take a locator directly, instead of a selector or ref (exactly one of the three). It can be a plain string:

  • a real ARIA role and its accessible name — button "Sign in";
  • kind=value, with kind one of role, text, label, placeholder, testid, title, alt — label=Email, testid=submit;
  • Playwright's own form — role=button[name="Sign in"];
  • or just the visible text — Sign in.

An object {kind, value, name?, exact?} works too.

Stable element references via the handle registry: browser_handle_acquire, browser_handle_eval, browser_handle_release, browser_handle_list — survive re-renders until detach or navigate.

Storage, emulation, mocking

  • browser_cookies_get/_set/_delete
  • browser_storage_get/_set (localStorage / sessionStorage)
  • browser_viewport (innerWidth/innerHeight, DPR, mobile flag)
  • browser_user_agent (sets WKWebView.customUserAgent)
  • browser_init_script (documentStart script for every nav on the tab)
  • browser_emulate — document-start shims for geolocation, color scheme (prefers-color-scheme), reduced motion, IANA timezone, locale (navigator.language), and offline. These are JS shims over WKWebView, so apply them before the page loads. Pass clear to remove them. Flatter aliases: browser_geolocation_set, browser_timezone_set, browser_offline.
  • browser_grant_permission (alias browser_permission_grant) — make the page see granted / denied / prompt for geolocation, notifications, camera, microphone, clipboard or persistent storage without a prompt
  • browser_service_worker_bypass — unregister a tab's service workers so their fetches show up in the network log
  • browser_mock_route / browser_mock_clear (fetch/XHR mocks per tab; browser_mock_list / browser_mock_reorder to inspect the rule stack)
  • browser_block_route (WKContentRuleList resource blocking)
  • browser_har_record_start / _stop / _list — capture a tab's network traffic into a HAR file (metadata only, no request bodies); browser_har_diff compares two recordings
  • browser_har_replay (HAR file → mock rules)

Sessions

  • browser_session_save / _list / _restore / _delete — named snapshots of the open URL set (per window, active tab marked); no scripted clicks, just the tabs.
  • browser_session_bucket_create / _list / _clone / _set_expiry / _export / _import — named cookie/storage buckets. A tab binds to a bucket via the address-bar session picker or a tool call, so the agent can hold two logins to the same site side by side.
  • browser_session_open — create a bucket and open a tab bound to it in one call (incognito: true for a throwaway tab).
  • browser_sessions_diff — which cookies (names, never values) and site-data origins differ between two buckets, e.g. "did the login persist?".

Recordings & batches

  • browser_batch — run up to 50 actions in one round trip, stop on first error by default
  • browser_action_record_start / _stop — capture browser calls into a named recording
  • browser_action_save / _list / _run / _delete — manage saved sequences; replay steps through the approval rules. Saved actions also show up in the Flows sidebar for one-click replay.
  • browser_record_gif — snapshot the active tab over a duration into a looping GIF (default 3s at 5fps; max 10s, 20fps, 200 frames). Requires the browser sidebar open. Returns the file path and frame count.
  • browser_record_video — same idea as an H.264 mp4 (smaller and higher quality than a GIF; capped at 600 frames).
  • browser_codegen — turn a saved recording into source text: Playwright spec (default), Puppeteer, or an MCP-callable JSON sequence.
  • browser_step_through — record browser_* calls in memory and replay them on a sibling tab (same-tab replay is refused unless you allow it); unlike browser_action_record_*, nothing is saved to disk.
  • browser_replay_logged — re-run one of the agent's recent browser_* calls with the same inputs, through the usual approval rules.

Accounts vault

The vault stores site credentials so the agent can log in without ever seeing the password.

  • browser_lookup_credentials — returns metadata only (label, username, match strength). The password is never returned.
  • browser_autofill_credentials — injects the password into the page inside the browser process via BrowserAccountAutofill. Plaintext never crosses the tool boundary.

Manage saved accounts from the Accounts panel adjacent to the browser sidebar.

Importing from your browser

⋯ menu → Import from Browser… (also a button in the session manager) brings your bookmarks bar over from an installed Chromium browser — Chrome, Arc, Brave, Edge, Vivaldi, Opera, or Chromium — as one-click shortcuts. It defaults to your system default browser and its last-used profile, flattens nested bar folders (the shortcut list has none), and skips duplicates and chrome:// entries. Re-run it any time; already-saved shortcuts are skipped.

The two other things people mean by "import my browser" are handled outside this sheet, and it says so:

  • Sign-ins — open a tab and switch its engine to Chrome — copy of your profile. That runs a copy of your real Chrome logins, so the tab is already signed in. TRMNLY never decrypts your cookies to do it.
  • Passwords — export a CSV from your browser, then use Accounts → Import.

Dialogs and downloads

JavaScript alert / confirm / prompt / beforeunload are handled without wedging the page:

  • browser_dialog_policy — set per-tab response (accept/cancel per kind, default text for prompt)
  • browser_dialog_list — drain the per-tab buffer (kind, message, default, returned, timestamp)
  • With a hold policy the dialog waits instead: browser_dialog_text reads it and browser_close_dialog accepts or cancels it (with an answer for prompt). A held dialog resolves itself after about 10 seconds.

Downloads routed through WKDownload (attachments or non-renderable MIME types) land in:

~/Library/Application Support/TRMNLY/agent/downloads/

browser_downloads_list enumerates them. PDFs from browser_pdf go to agent/pdfs/. Screenshots from browser_screenshot go to agent/screenshots/, pruned with an LRU at 300 files / 200 MB.

Network egress

Browser navigation respects the app-wide egress allowlist. When a navigation is denied, the denial card surfaces browser_request_allowlist so the agent can ask for one specific exception:

Tool Use
browser_allowlist_list Snapshot mode + hosts
browser_allowlist_add Add a host suffix (requires approval)
browser_request_allowlist Alias of add framed as an explicit user request

See Agent safety → Network egress allowlist for how this interacts with the app-wide egress policy.

When to use it vs a real browser

  • Use the in-app browser when the agent is doing the driving, or for quick reads.
  • Open URLs externally (right-click → "Open in default browser") for anything that needs your full session state, extensions, or password manager.