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,
innerWidthand 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_clippedis true anddescendant_countsays how much was left out; picking<body>gives a bounded answer rather than the whole document.boxand a cropped screenshot of the element, attached to the result.stale: trueonce 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:
Navigation & tabs
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 JSpasteevent with{mime: contents}for editors (Monaco, ProseMirror) that ignore the OS pasteboard;browser_set_clipboardwrites the real system clipboard instead.browser_until— repeat anybrowser_*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 ofrole,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/_deletebrowser_storage_get/_set(localStorage / sessionStorage)browser_viewport(innerWidth/innerHeight, DPR, mobile flag)browser_user_agent(setsWKWebView.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. Passclearto remove them. Flatter aliases:browser_geolocation_set,browser_timezone_set,browser_offline.browser_grant_permission(aliasbrowser_permission_grant) — make the page seegranted/denied/promptfor geolocation, notifications, camera, microphone, clipboard or persistent storage without a promptbrowser_service_worker_bypass— unregister a tab's service workers so their fetches show up in the network logbrowser_mock_route/browser_mock_clear(fetch/XHR mocks per tab;browser_mock_list/browser_mock_reorderto 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_diffcompares two recordingsbrowser_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: truefor 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 defaultbrowser_action_record_start/_stop— capture browser calls into a named recordingbrowser_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— recordbrowser_*calls in memory and replay them on a sibling tab (same-tab replay is refused unless you allow it); unlikebrowser_action_record_*, nothing is saved to disk.browser_replay_logged— re-run one of the agent's recentbrowser_*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 viaBrowserAccountAutofill. 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 forprompt)browser_dialog_list— drain the per-tab buffer (kind, message, default, returned, timestamp)- With a
holdpolicy the dialog waits instead:browser_dialog_textreads it andbrowser_close_dialogaccepts or cancels it (with an answer forprompt). 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.