What is the PocketHook Safari Extension?#
A macOS Safari extension that lets your self-hosted Agent Server work inside your real browser: open and close tabs, read pages, find and click controls, fill forms, and capture screenshots — in your session, with your logins, on your machine.
Everything runs locally. The extension only talks to the Agent Server on your own Mac (loopback), and nothing is sent anywhere else.
Install#
The extension ships with the Agent Server as a notarized macOS app — no App Store, no Xcode:
bun run safari:install
This installs Pockethook Safari.app into /Applications and launches it. Then, in Safari:
- Settings → Extensions — enable PocketHook Safari and grant website access.
- Generate a one-time pairing code on the server:
bun run safari:code
- Open the extension popup in Safari’s toolbar, enter the code, and press Pair. A green dot means you are connected.
Check the connection anytime with bun run safari:status.
Permission levels#
You decide how much autonomy the agent gets, per server, with bun run safari:config:
| Level | What it means |
|---|---|
confirm (default) | Every click with external effects (vote, submit, publish, purchase…) asks you first |
autonomous | Votes, follows, and submits run without asking; payments, permanent deletions, and account or security changes still ask |
readonly | Navigate, inspect, and capture only — clicking and typing are disabled |
What the agent can do#
- Open, navigate, and close tabs
- Inspect a page: visible controls with stable selectors, state, and semantic attributes
- Find controls by their visible text or identifying attributes
- Click and fill forms (framework-aware, with before/after verification)
- Scroll and capture screenshots, served back to your chat
Every action reports what actually happened — including whether a click really changed anything — so the agent verifies instead of guessing.
Security model#
- Loopback only — the extension connects exclusively to local addresses you configure.
- One-time pairing codes — codes expire after 5 minutes and are single-use; the resulting credential never leaves your Mac.
- Command expiry — commands the extension did not pick up within 20 seconds are discarded, so nothing executes late.
- You hold the keys — payments and destructive actions always require your explicit confirmation, at every permission level that allows clicking.
- Auditable — the extension’s JavaScript ships readable inside the app bundle.
Download#
The extension is bundled with the Agent Server (assets/safari/PocketHook-Safari.zip), or grab it directly: PocketHook-Safari.zip — signed and notarized for macOS.