Hermes Agent Safari support arrived on 18 November 2026, when a safari plugin was added to the official Hermes plugin catalog, and this guide walks through the install, every macOS permission gate and the safety settings to change first.
The plugin lets Hermes drive your real Safari on a Mac: open tabs, read pages, fill forms and click, using the logins you already have.
Safari has no Chrome DevTools Protocol, so the plugin talks to Safari through AppleScript (JXA) instead, per its catalog entry.
Before you start, read the safety section below, because this plugin acts on signed-in sites without asking each time.
What shipped and when
- The catalog entry landed in the 18 November canary build (commit 1addeb7b), with a follow-up review commit.
- Tier: community; maintainer: Thorballer; version 0.1.0.
- Requires Hermes 0.21.0 or newer and runs on macOS only.
- It registers a
safaritoolset with eight tools and ahermes safaricommand.
Step 1: install from the catalog
hermes plugins install safari
hermes plugins list | grep safari # -> safari enabled
The catalog install pins the plugin to the reviewed commit and enables it, per the plugin README.
Hermes plugin commands are documented on the plugins page.
Step 2: check what is missing
hermes safari status # JSON: safari_installed, automation, cliclick, allow_js_from_apple_events
hermes safari doctor # every permission gate, with the fix for each
Anything that reads false is a gate you still need to open.
Step 3: Automation consent
The first time Hermes sends an AppleEvent, macOS asks whether Python may control Safari; click Allow.
If you dismissed it, go to System Settings, Privacy and Security, Automation, find your Python or Terminal entry and switch Safari on.
Errors -1712 or -1743 mean this gate is still closed.
This unlocks safari_open, safari_state and safari_tabs.
Step 4: Allow JavaScript from Apple Events
In Safari open Settings, Advanced, and tick "Show features for web developers".
Then choose Develop, Allow JavaScript from Apple Events from the menu bar.
This is the gate that turns the plugin from a tab opener into a real browser driver: it unlocks safari_js, safari_act, safari_type and selector clicks.
A Safari update can reset it, so rerun hermes safari doctor if JavaScript calls start failing.
🔥 Want Hermes running browser jobs for your business? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS, four coaching calls a week and 3,400+ members wiring up the same agents. → Join the AI Profit Boardroom
Rank in AI Search or It's FREE →
Step 5: optional cliclick and Accessibility
brew install cliclick
cliclick sends real OS mouse events, which some sites need, and enables coordinate clicks.
The binary that runs it needs Accessibility permission under System Settings, Privacy and Security, Accessibility.
Step 6: Screen Recording for screenshots
Enable your Python or Terminal under Privacy and Security, Screen Recording, then restart that process.
That unlocks safari_screenshot, the fallback read path when JavaScript is off.
The eight tools and their gates
| Tool | What it does | Needs |
|---|---|---|
| safari_open | Open a URL in a new tab or window | Automation |
| safari_state | List windows and tabs | Automation |
| safari_tabs | List, select, close or navigate tabs | Automation |
| safari_js | Run JavaScript in a tab and return the value | JS from Apple Events |
| safari_act | Read page text, find elements, go back | JS from Apple Events |
| safari_type | Type into a field, optionally submit | JS from Apple Events |
| safari_click | Click by selector or by screen coordinates | JS, or cliclick for coordinates |
| safari_screenshot | Capture the front window as a PNG | Screen Recording |
Use it from Telegram or Discord
Add the toolset to the platform list in config.yaml:
platform_toolsets:
telegram:
- safari
Safety: read the catalog safety note
The reviewed catalog entry says the agent can open any URL, including local file pages, read page text, run any JavaScript in any open tab, type, submit forms and click on your logged-in sites without a per-action Hermes approval.
It also says Hermes's browser website blocklist does not apply to this plugin.
Run it in a separate macOS user or Safari profile with only the logins the job needs, and keep banking and email signed out.
Tabs the plugin opens are closed after an hour idle, or at session end, unless you pass keep: true.
📈 Using Hermes for SEO research in Safari? Get your Backlink Gameplan and my team will reverse engineer why your competitors rank: their links, how many you need and which sites to target, within 48 hours, with a call with an SEO expert. → Get my Backlink Gameplan
Safari plugin vs the built-in browser
Hermes's own browser tools run a separate automation browser with an empty profile, so logged-in sites hit sign-in walls; the Safari plugin uses your real session instead.
Join the AI Profit Boardroom →
For other browser options, see our Hermes Agent browser guide and our Camofox plugin walkthrough.
No dependencies, and other install routes
The plugin README says it is pure Python standard library and drives the osascript and defaults binaries that ship with macOS, so there is nothing to pip install.
The catalog install pins the plugin to the catalogued commit and installs it enabled.
Two other routes exist: install straight from the repo URL with hermes plugins install https://github.com/Thorballer/hermes-safari-plugin, which bypasses the catalog pin, or clone it into ~/.hermes/plugins/safari and run hermes plugins enable safari.
Stick with the catalog route unless you need an unreleased fix, because the pin is what the catalog reviewers looked at.
What hermes safari status returns
The status command prints JSON with five fields: safari_installed, safari_running, automation (state plus detail), cliclick and allow_js_from_apple_events.
Any field that reads false is a gate you still need to open.
hermes safari doctor goes a step further and prints the fix for each red gate on the line below it.
Run doctor after every Safari update, because the README notes an update or a prefs reset can clear the Apple Events JavaScript setting.
A full round trip, tool by tool
The README walks through one complete loop once the first two gates are green.
safari_openwith a URL returns the window, tab index and URL.safari_actwithaction: "text"returns rendered body text, trimmed to 20k characters.safari_jsevaluates a snippet and returns only the value, so you avoid pulling a whole DOM into context.safari_actwithaction: "find"and a CSS selector lists matches with their text before you click.safari_clickin selector mode scrolls the element into view and clicks its centre.safari_typefills a field through the native value setter, so React and Vue inputs register the change, with optional submit.safari_stateconfirms where you ended up.
That loop covers most read, search and form tasks without screenshots.
Single-page apps: poll, do not sleep
Client-rendered pages often return an empty shell on the first read.
The README's advice is to poll safari_js with a check such as "return the body text if it is longer than 500 characters, else null" until it returns a value.
A single read after a fixed delay gives wrong answers on slow pages.
Build this into any skill or prompt that reads dashboards or web apps.
The error envelope
Every tool returns the same shape: {"success": true, ...} on success, or success: false with error, gate and fix fields.
Read gate and fix first; they name the exact checkbox that blocked the call.
This makes the plugin easy to wrap in a skill that tells the user which setting to flip.
Tab lifecycle
Tabs opened by safari_open close after an hour idle, at session end, or opportunistically before the next open, so a closed chat leaves nothing behind.
Pass keep: true for a tab you want to survive.
Close one immediately with safari_tabs and action: "close" plus the tab index.
Hardening the setup
Because the plugin acts in your signed-in browser without per-action approval, decide which logins it should be able to reach.
A practical approach is a separate macOS user account signed in only to the sites you want the agent to use.
Turn the Automation toggle off in System Settings when you are not running Safari tasks, and keep sensitive sites out of the session entirely.
Start with read-only tasks and only move to form filling once you trust the prompts.
Permission error codes
Two AppleEvent errors point straight at the Automation gate.
-1712 is a timeout, usually because the consent dialog was never answered.
-1743 is a denial, usually because the dialog was dismissed once and macOS will not ask again.
Fix both under System Settings, Privacy & Security, Automation, by switching Safari on for the Python or Terminal process that runs Hermes.
Screen Recording needs a restart
After you grant Screen Recording, macOS requires the process that runs Hermes to restart before screenshots work.
If safari_screenshot still fails after granting, quit and relaunch that terminal or app, then rerun hermes safari doctor.
Screenshots are the fallback read path when the JavaScript gate is off, so this step matters on locked-down machines.
Rank in AI Search or It's FREE →
Local files are in scope too
The catalog note says the agent can open any URL, including file:// paths.
That means a prompt could open and read local files through Safari, not just websites.
Keep sensitive documents out of the macOS user that runs Safari tasks, and write prompts that name the exact URLs you expect the agent to visit.
Wrapping it in a skill
Once a Safari task works by hand, turn it into a Hermes skill so the steps stay the same every run.
Spell out the URL, the safari_js snippet that returns the value, the poll condition for slow pages and the output format.
Add an explicit "do not click or submit" line for read-only skills, because the plugin will not ask before it acts.
See the Hermes docs for how skills are stored and loaded.
Version and platform checks
The catalog entry requires Hermes 0.21.0 or newer and macOS.
Confirm your Hermes version before installing, and upgrade first if you are behind.
On Linux or Windows the plugin has nothing to drive, since it relies on Safari and the macOS scripting tools.
Troubleshooting
-1743: Automation denied; re-enable Safari under Automation.- JavaScript calls return errors: re-tick Allow JavaScript from Apple Events.
- Clicks ignored by a site: install cliclick and use coordinates.
- Empty page text on a slow app: poll with
safari_jsuntil the text appears.
Want help with the rest of your agent stack? The AI Profit Boardroom covers it step by step.
Join the AI Profit Boardroom →
FAQ: Hermes Agent Safari
Does Hermes Agent support Safari?
Yes. Since 18 November 2026 a safari plugin in the Hermes plugin catalog drives your real Safari on macOS.
Is the Safari plugin official?
It is listed in the official Hermes plugin catalog at the community tier, maintained by Thorballer.
Which permission matters most?
Allow JavaScript from Apple Events in Safari's Develop menu. Without it the plugin can only open and list tabs.
Is it safe to use on my main Mac account?
Be careful. The catalog safety note says it acts on signed-in sites without per-action approval, so use a separate profile with limited logins.
Does it work on Windows or Linux?
No. The catalog lists macOS as the only platform.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote "Link Building Mastery".
- My Udemy courses have taught over 29,000 students.
→ Get my best AI training inside the AI Profit Boardroom
Install the plugin, run hermes safari doctor until all gates are green, and lock down the logins before the first real task.
For a done-with-you path, join the AI Profit Boardroom, and keep this page as your Hermes Agent Safari setup checklist.











