Guide · Agent skill

How to use the Safari Browser Automation CLI agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

This guide explains the cli-anything-safari agent skill, which lets an AI agent drive the Safari browser on a Mac through a command-line tool. It is written for readers who have not used agent skills before. By the end you will know what the skill does, how to install it, how to ask an agent to use it, and what safety points to check first.

Safari Browser Automation CLIHKUDS/CLI-Anything · Apache-2.0 Download the skill

Quick start

1Confirm your Mac is ready. Check that you are on macOS with Safari, Node.js 18 or newer, and Python 3.10 or newer installed.
2Enable Apple Events for Safari. In Safari, open the Develop menu and turn on Allow JavaScript from Apple Events.
3Download and unzip the skill. Download the skill ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
4Install the CLI package. From the safari/agent-harness folder, run pip install -e . to install cli-anything-safari.
5Test with a count. Run cli-anything-safari tools count. The expected result in the source is 84.
6Take a snapshot. Open a page with the navigate tool, then run cli-anything-safari --json tool snapshot to get structured text.
7Ask the agent. Describe the browser task in plain language and review the actions before any login or form step.

What this skill lets the agent do

The skill teaches an agent to control the Safari browser on macOS through a Python Click CLI. It wraps the safari-mcp Node.js MCP server and exposes its 84 tools as shell commands. The agent can open pages, read page content as structured text, click, fill forms, scroll, take screenshots, save pages as PDF, read cookies and storage, and capture network activity.

Because it runs in your real Safari, existing logins are kept. This is useful for work that depends on being signed in, and it is also why you should review what the agent is allowed to touch.

Check the requirements before you install

The skill only works on a Mac. You need Safari, Node.js 18 or newer, and Python 3.10 or newer. You also need to turn on Apple Events for Safari so the tool can run JavaScript.

macOS (safari-mcp is macOS-only)
Safari, already installed
Node.js 18+ (the source suggests brew install node or the nodejs.org installer)
Python 3.10+
Safari menu: Develop > Allow JavaScript from Apple Events

Install the skill from the ZIP download

Download the skill ZIP from this page and unzip it. To make it available to Claude Code for your user account, place the unzipped folder in ~/.claude/skills/. To make it available only inside one project, place it in that project's .claude/skills/ folder.

In the Claude apps you can instead upload the skill under Settings > Capabilities > Skills.

Personal use: ~/.claude/skills/
Single project: .claude/skills/ inside the project folder
Claude apps: Settings > Capabilities > Skills

Install the CLI package

The source describes installing the CLI from its agent-harness folder with pip in editable mode. The first tool call downloads the safari-mcp npm package, a one-time download of a few MB.

The first tool call downloads safari-mcp, so expect a short wait the first time.

cd safari/agent-harness
pip install -e .

Ask the agent for browser tasks

You do not need to type the commands yourself. Describe the browser task in plain language, and an agent that has loaded the skill can choose the right commands. The skill is aimed at agents that cannot speak MCP directly, such as those that run shell commands from bash or scripts.

For debugging, you can also run the commands yourself in Terminal. Start by listing the available tools, then take a snapshot of the page.

Open https://example.com and tell me the main heading.
Log in to the staging form with the test account and report any error text.
Save the current page as a PDF to /tmp/page.pdf.

cli-anything-safari tools count
cli-anything-safari --json tool snapshot

Core commands and tips for reliable use

The CLI has five top-level commands: tool (call any of the 84 tools), tools (inspect the registry with list, describe and count), raw (call a tool by full name with raw JSON arguments), session (in-memory state), and repl (interactive mode, the default with no subcommand).

Refs from a snapshot expire on the next snapshot, so take a fresh snapshot before clicking by ref. Scroll uses direction and amount, not x and y. Evaluate takes --script, not --code. Check the exact arguments with tools describe before using a tool.

Use --json for output an agent or script can parse.
Check return codes: 0 means success, non-zero means an error.
Read errors from stderr and data from stdout.
Run tools describe <name> first, because file path argument names vary between tools.
Each call starts a fresh subprocess, so there is no persistent session.

cli-anything-safari --json tool snapshot
cli-anything-safari tool click --ref 0_5
cli-anything-safari tool scroll --direction down --amount 500

Safety notes: scripts and network access

This skill runs scripts and uses the network. The CLI launches the safari-mcp server through npx, which is downloaded on first use. Because the tool can read cookies, storage and fill passwords, only point it at accounts and sites you own, and review what the agent is about to do with logins.

Keep sensitive values out of shared logs. Commands and JSON arguments may appear in your shell history, so avoid putting real passwords directly in commands where possible.

Read cookies and storage can expose sensitive data.
fill-form can enter passwords into forms.
The skill makes network requests, including the first npm download.

What people use it for

Scripting a repeatable browser task from bash, such as reading structured page text with a snapshot and piping it through jq.
Running browser checks in a macOS CI job using cron-friendly, subprocess-friendly output.
Debugging a page interactively from Terminal by navigating, snapshotting and clicking by ref.
Capturing network activity and performance metrics for a page load.
Saving a page as PDF or capturing a screenshot for a record of what was shown.

Frequently asked questions

Is the Safari browser automation CLI skill free?

The source does not state pricing or licence terms for this skill. The repository is listed under the Apache-2.0 licence, so check that licence text for the terms that apply to you.

Does this skill work on Windows or Linux?

No. The safari-mcp server is macOS-only because Safari and Apple Events are required, so the skill only works on a Mac.

How do I install an agent skill like this one?

Download the ZIP from the page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder. In the Claude apps you can upload it under Settings > Capabilities > Skills.

Why does clicking by ref fail?

Refs come from a snapshot and expire on the next snapshot. Take a fresh snapshot, then click using the new ref. You can also click by --selector or --text.

Should I use this CLI or safari-mcp directly?

If your agent already speaks MCP natively, such as Claude Code, Cursor or Cline, the source says calling safari-mcp directly over MCP stdio is faster. Use this CLI when your agent cannot speak MCP or when you need to script from bash.

Is it safe to let an agent use my logged-in Safari?

Use care. Because the skill runs in your real Safari with existing logins and can read cookies, storage and fill passwords, limit it to accounts and sites you own and review its actions.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers and engineers on a Mac whose agent cannot use MCP and who need Safari control from bash, scripts or CI. It is not a fit for Windows or Linux users, for agents that already speak MCP, or for anyone who is not comfortable with an agent reading cookies and filling logins in their own browser.

Download the skill