zenpilot
<h1>
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/beSaif/zenpilot/main/docs/logo-wordmark-dark.svg">
<img alt="zenpilot" src="https://raw.githubusercontent.com/beSaif/zenpilot/main/docs/logo-wordmark.svg" height="56">
</picture>
</h1>
<!-- mcp-name: io.github.beSaif/zenpilot -->
[](https://github.com/beSaif/zenpilot/actions/workflows/ci.yml)
[](LICENSE)
Let Claude use your [Zen browser](https://zen-browser.app). Works with Claude Desktop and
Claude Code, kind of like Claude in Chrome but for 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](https://github.com/beSaif/zenpilot/releases/latest) and open it. That's it.
**Claude Code (or both):** with [uv](https://docs.astral.sh/uv/) installed, run:
```sh
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`.
## 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/`.
```sh
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](https://github.com/beSaif/zenpilot/blob/main/docs/configuration.md).
## 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](https://github.com/beSaif/zenpilot/blob/main/docs/dev/hacking.md).
## License
[MIT](LICENSE)
TDQS
Scored across 26 tools
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.
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.
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.
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.