Skip to main content
Glama

CI License: MIT

Let Claude use your Zen browser. Works with Claude Desktop and Claude Code, kind of like Claude in Chrome but for Zen.

zenpilot demo: install, set up, then Claude fills in and submits a form in Zen

There's no browser extension. zenpilot opens Zen with its remote control turned on and talks to it directly.

Alpha. Built and tested on macOS with Zen 1.23. Linux support is newer: it's been tried on NixOS (Wayland) with Zen 1.23.

Install

You need a Mac with Zen in /Applications, or Linux with Zen installed (on PATH, in /opt/zen, ~/.local/share/zen or as the Flatpak). If zenpilot can't find it, set ZENPILOT_ZEN to the command that starts it.

Linux: popups use zenity (or kdialog) and notify-send, so install one of them. Without any, zenpilot can't ask you, so allow sites ahead of time with zenpilot allow <site>. Claude Desktop has no Linux app, so use Claude Code.

Claude Desktop: download zenpilot-<version>.mcpb from the latest release and open it. That's it.

Claude Code (or both): with uv installed, run:

uv tool install zenpilot
zenpilot setup

Setup asks which Zen profile to use and which sites Claude may visit. Then it connects zenpilot to Claude Code (and Claude Desktop, if you have it) and opens Zen. Restart Claude Desktop afterwards.

Either way, zenpilot updates itself to the newest release each time Claude starts it. To stay on one version with uv, install it pinned: uv tool install zenpilot==0.5.0.

Related MCP server: agentify-desktop

Use it

Just ask Claude: "order a large pizza with bacon on httpbin.org/forms/post for Sam, then submit it".

The first time, a few popups may show up. Only you see them, not Claude:

  • Which profile? zenpilot is a fresh profile that isn't logged in to anything. Pick your own profile if you want Claude to use sites you're logged into.

  • Reopen Zen? If Zen is already open without remote control, zenpilot offers to restart it. Your tabs come back on a Mac; on Linux, tabs you opened in the last few seconds may not.

  • Allow this site? Claude only works on sites you allow. Choose Don't Allow, Allow for 12 Hours or Always Allow. If you miss it, it asks again next time. After Don't Allow it waits 10 minutes before asking again, or run zenpilot allow <site>.

Pressing Enter always picks the safe answer.

While Claude works in a tab, an orange glow goes around the page and a zenpilot badge in the bottom-left corner says so. Press Stop on it and Claude stops and asks you what to do. If it tries again anyway, a popup asks whether to let it continue.

Claude can open, switch and close tabs, go to a URL, read the page, its console errors and its network requests with their responses, find a control by name, click, type, pick from dropdowns, hover, press keys, answer a page's alert, confirm and prompt dialogs, wait for text or a URL, scroll, take screenshots and resize a tab's page to check phone and tablet layouts (your window keeps its size). Network requests are only recorded on sites you've allowed and kept in memory, with the values of cookie and authorization headers left out. Claude can save them as a HAR file, in ~/.local/state/zenpilot/har/ or the temp folder, never overwriting one; response bodies are only included if asked for. If you set allow_request_mocking = true, Claude can also make a request to one exact URL fail or return stub data, to test how your app copes; this is off by default, only works on allowed sites and ends when zenpilot disconnects. It can attach files to upload, but only from folders you list in upload_dirs. It can't touch cookies, passwords or downloads, and it can't run its own JavaScript.

When it gets stuck

zenpilot is far from perfect, and every site is different. When Claude can't do something (say, drag and drop), it notes what it tried. zenpilot also notes tool calls that failed or took over 5 seconds. If anything went wrong, a notification at the end of the session points you to a report in ~/.local/state/zenpilot/reports/.

zenpilot report           # show the latest report
zenpilot report --issue   # open a GitHub issue with it filled in

What you typed and the pages' text stay out of it, Claude is asked to leave out personal data, and URLs lose their ?query part. Still, read it before you submit.

Staying safe

  • Allowlist. Claude only works on sites you've allowed. Add one with zenpilot allow github.com.

  • Stick to the zenpilot profile if you can. It's logged out of everything. On your main profile, a shady page could try to trick Claude into doing stuff in your accounts, so only allow sites you trust.

  • Read-only mode. Set read_only = true and Claude can look but not click or type.

  • Log. Everything Claude does is written to ~/.local/state/zenpilot/audit.jsonl, with what it clicked. Typed text isn't logged, only its length. zenpilot log shows it as a timeline.

  • Remote control is open while Zen runs this way. Other apps on your computer could connect to it too, and some sites (banks, Cloudflare checks) may think you're a bot. Some CAPTCHAs fail however well you solve them (hCaptcha, as on Lever job forms); submit those from another browser. When you're done, quit Zen and open it normally.

zenpilot also stops Zen from switching off its own protections (Safe Browsing, the popup blocker and so on), which would otherwise happen when remote control is on.

Commands

Command

What it does

zenpilot setup

Set everything up (see above)

zenpilot allow [site...]

Allow sites. --remove takes them off (12-hour ones too). No sites lists them.

zenpilot launch

Open Zen with remote control on

zenpilot doctor

Check your setup and say how to fix anything that's broken

zenpilot report

Show the latest session report. --issue files it on GitHub, --list lists them all.

zenpilot log

Show what Claude did lately. -n 200 for more, --errors for failures only

Settings

They live in ~/.config/zenpilot/config.toml, and changes apply right away. See all settings.

Good to know

  • Only one Claude can drive Zen at a time. zenpilot lets go after 2 minutes of doing nothing, so Claude Desktop and Claude Code can take turns.

  • Zen can be hidden or behind other windows. It still works.

  • Zen loads restored tabs lazily, so Claude only sees an old tab once you've opened it.

  • Stuck? Run zenpilot doctor. If Zen says it already has a session after a crash, restart Zen.

Hacking on it

Setup and test commands are in docs/dev/hacking.md.

License

MIT

Available Tools

26 tools
clickA

Click an element by ref (from read_page) with a real mouse event.

Reports what changed on the page: + lines appeared (new controls get refs), - lines went away.

Inputs: ref (required).

close_tabC

Close a tab.

Inputs: tab_id (required).

findA

List only the interactive elements whose read_page line contains query, ignoring case.

Cheaper than read_page on a long page when you need one control, e.g. find("save") or
find("email"). Its refs work with click, type and select, and replace earlier refs like read_page's.

Inputs: query (required), tab_id.

get_textC

Readable main text of the page (prefers or a single ).

Inputs: tab_id, max_chars.

handle_dialogA

Answer the alert, confirm or prompt dialog a page opened, which blocks the page until answered.

accept=true presses OK, false presses Cancel. text is typed into a prompt before pressing OK. Reports a navigation, or what changed on the page, like click.

Inputs: text, accept, tab_id.

har_exportA

Save the requests read_network_requests lists for a tab as a HAR 1.2 file, e.g. to attach to a bug report.

It goes in zenpilot's har folder, or at path: an absolute path ending in .har, in zenpilot's state
folder or the temp folder. Existing files are never overwritten. Response bodies are left out unless
include_bodies, and cut at 100 KB each. Cookie and authorization header values show as [redacted].

Inputs: path, tab_id, include_bodies.

hoverA

Move the mouse over an element by ref, to open menus or show tooltips.

Reports what changed on the page, like click.

Inputs: ref (required).

list_tabsA

List open tabs with ids. The active tab is marked with *. A tab keeps its id while it's open.

Inputs: no named parameters.

network_requestB

One request from read_network_requests: its headers and response body (cut at 20000 characters).

Cookies and authorization headers show as [redacted].

Inputs: request_id (required), tab_id.

network_routeA

Make a tab's requests to url fail (abort) or get a stub response (respond), to test how the page copes.

url must match exactly, query included: no wildcards. respond answers with status, body and content_type.
It applies to that tab and its frames, and only while the tab is on an allowlisted site. Returns a route id
for network_unroute. Routes are kept in memory and end when zenpilot disconnects from Zen, after 2 minutes
without tool calls. Off unless the user set allow_request_mocking = true in zenpilot's config.

Inputs: url (required), body, action, status, +2 more.

network_unrouteB

Stop a route network_route set up, so its requests reach the network again.

Inputs: route_id (required).

new_tabB

Open a new tab (it becomes active), optionally loading url.

Inputs: url.

press_keyA

Press keys in a tab, e.g. "Enter", "Tab", "Escape" or "ctrl+a". Separate several with spaces.

The keys go to the focused element, so click or type first. Reports a navigation, or what changed on the page, like click. Paste shortcuts are refused, to keep the user's clipboard out of the page.

Inputs: keys (required), tab_id.

read_consoleA

Console messages and uncaught errors the page logged, oldest first, up to limit (max 200).

Only what the current page logged while zenpilot was connected: the list empties when the tab
navigates, and zenpilot disconnects after 2 minutes without tool calls, so messages from before
that are gone. Messages from iframes aren't included. Long messages are cut, and the oldest go
first if the output is too long. level shows one level only. clear empties the tab's list after reading it.

Inputs: clear, level, limit, tab_id.

read_network_requestsA

Requests the page made, oldest first, up to limit (max 500): id, method, status, type, time and URL.

Only the current page's, from while zenpilot was connected: the list starts over when the tab navigates
(keeping the request that loaded the new page), and zenpilot disconnects after 2 minutes without tool
calls. Requests from iframes aren't included. url_pattern keeps requests whose URL contains it. clear
empties the tab's list after reading it. network_request shows one request's headers and response body.

Inputs: clear, limit, tab_id, url_pattern.

read_pageB

Outline of the page's visible interactive elements and text.

Interactive elements get refs like r12 for click and type. Checkboxes, radios and
switches show checked or unchecked. "clickable" marks an element with a pointer
cursor but no role, often a custom toggle; its label is usually the text before it.
An open dropdown's options are listed under it, the first few only; select picks any.
Refs expire when you call read_page again or the page navigates. Refs that click, type
and select give for new controls count as this read_page's.

Inputs: tab_id.

report_limitationA

Tell the zenpilot developers about something you couldn't do in Zen with these tools.

Call it once per problem when a task needs something the tools lack (drag and drop, a
widget that ignores clicks, typing or select, content read_page doesn't show) or only
works after a workaround. goal: what you were trying to do, in a few words, like "pick a
date on a booking form". problem: what you tried and what happened, naming the elements, refs'
roles and errors. workaround: what worked instead, if anything. It's saved on the user's
computer for them to review and file as a GitHub issue, so leave out personal data and anything
the user typed.

Inputs: goal (required), problem (required), workaround.

resize_windowA

Set a tab's viewport to width x height CSS pixels (200 to 4000 each), e.g. to check a phone layout.

Only the page inside that tab changes size; Zen's window stays as it is. The size stays through
reloads and navigations in the tab, even after zenpilot disconnects, until you call resize_window
without width and height. Do that when you're done.

Inputs: width, height, tab_id.

screenshotC

Screenshot of the visible part of a tab.

Inputs: tab_id.

scrollC

Scroll the page with the mouse wheel by amount pixels.

Inputs: amount, tab_id, direction.

selectA

Choose an option in a dropdown (by ref): a , a combobox or a listbox.

Opens it, types to filter if it's a text field, clicks the option whose text is option
(or the only one starting with or containing it), then checks the choice took. Reports
what changed on the page, like click.

Inputs: ref (required), option (required).

switch_tabC

Make a tab the active one.

Inputs: tab_id (required).

typeA

Replace the content of a field (by ref) with text using real key events.

To choose from a dropdown, use select. Date, time, color and range inputs take
their value format instead: date YYYY-MM-DD, time HH:MM (24-hour), datetime-local
YYYY-MM-DDTHH:MM, month YYYY-MM, week YYYY-Www, color #rrggbb. Newlines in text are typed as
Shift+Enter, so they don't send chat messages; submit=true presses Enter after. Reports what
changed on the page, like click.

Inputs: ref (required), text (required), submit.

uploadA

Attach files to a file input (by ref), as if the user picked them.

paths are absolute file paths. Only files in the folders the user listed in upload_dirs
in zenpilot's config are allowed. Uploads are logged.

Inputs: ref (required), paths (required).

wait_forA

Wait until everything given holds: text is on the page, the ref's element is visible, the URL has url_contains.

Gives up after timeout_ms (100 to 30000). Use it after an action that loads or updates the page,
instead of guessing a pause. Each poll checks the site, so a redirect to a blocked one ends the wait.

Inputs: ref, text, tab_id, timeout_ms, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 26 tools

    Disambiguation5/5

    Each tool targets a distinct browser-automation operation: tab management, page reading, interaction, network inspection, screenshots, dialogs, and viewport resizing. The apparent overlaps like read_page/find/get_text and read_network_requests/network_request/har_export are clearly differentiated by scope and output.

    Naming Consistency4/5

    Tool names consistently use lower_snake_case and are mostly readable action-oriented names. There are minor deviations such as single-word verbs (click, type, select) and noun-first names (screenshot, har_export, network_request), but no jarring mixed conventions.

    Tool Count4/5

    At 26 tools, the surface is slightly above the typical ideal range and feels heavy, but the broad browser-automation scope justifies most tools. Each capability is distinct enough that the count is reasonable rather than bloated.

    Completeness4/5

    The set covers core browser automation well: tabs, navigation, reading, clicking/typing/selecting, waiting, dialogs, screenshots, network inspection, HAR export, and request mocking. Gaps remain around drag-and-drop, iframe content, browser history/reload shortcuts, cookies/storage, and direct JS evaluation, but these are mostly edge or advanced operations.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers