safari-browser
/safari-browser
Automatyzuje Safari na macOS przez AppleScript dla stron wymagających logowania, zachowując lokalny stan sesji i ciasteczka.
- Autor
- PsychQuant ↗
- Repozytorium
- psychquant-claude-plugins ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 4
- Skrypty
- 1
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 6
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/recall.py
Co robi i kiedy
Automatyzuje Safari na macOS przez AppleScript dla stron wymagających logowania, zachowując lokalny stan sesji i ciasteczka.
Wyzwalacze z opisu
Oryginalny opis (EN)
macOS native browser automation via Safari + AppleScript. Use when the user needs to automate websites that require login (Plaud, Elementor, banking, social media) — Safari preserves localStorage and cookies permanently. Also use when agent-browser fails due to session/auth issues, or when the user explicitly asks to use Safari. Triggers on: "login to site", "automate with Safari", "use Safari", "session expired with agent-browser", "Plaud upload", or any website automation where persistent auth is needed. ALSO use for reading Safari's local on-disk data — browsing history, bookmarks / Reading
Jak działa
- When to Use safari-browser vs agent-browser
- Inspect Command Results Before Continuing
- Core Workflow
- Observe After Acting
- Command Reference
- Common Patterns
- Troubleshooting
- Limitations
- Playbooks
Podgląd SKILL.md
---
name: safari-browser
description: >-
macOS native browser automation via Safari + AppleScript. Use when the user needs to automate
websites that require login (Plaud, Elementor, banking, social media) — Safari preserves
localStorage and cookies permanently. Also use when agent-browser fails due to session/auth
issues, or when the user explicitly asks to use Safari. Triggers on: "login to site",
"automate with Safari", "use Safari", "session expired with agent-browser", "Plaud upload",
or any website automation where persistent auth is needed. ALSO use for reading Safari's
local on-disk data — browsing history, bookmarks / Reading List, iCloud tabs from other
devices, and downloads. Triggers on: "what did I look at", "find that page I saw",
"I forgot the URL", "search my history", "my bookmarks", "tabs on my other Mac/iPhone",
"what did I download".
allowed-tools:
- Bash(safari-browser:*)
- Bash(safari-browser *)
---
# Safari Browser Automation
macOS native browser automation CLI using Safari + AppleScript. **Core advantage: permanent login** — uses the user's existing Safari session directly.
## When to Use safari-browser vs agent-browser
| Condition | Use |
|-----------|-----|
| Website requires login (Plaud, Elementor, banking, etc.) | **safari-browser** |
| Need localStorage/cookies from existing session | **safari-browser** |
| agent-browser `state save/load` fails | **safari-browser** |
| Vue/React sites where `fill` doesn't trigger reactivity | **safari-browser** (JS events dispatched) |
| Headless / CI / public sites | agent-browser |
| Cross-platform needed | agent-browser |
| Sites that block headless browsers (banks, social media) | **safari-browser** (real browser, no bot detection) |
| AI + human collaboration (user watches and takes over) | **safari-browser** (shared Safari window) |
| Need CDP accessibility tree | agent-browser (safari-browser has JS-based snapshot) |
## Inspect Command Results Before Continuing
For every command, read stderr's **first line and full diagnostics**, and check its exit code. Nonzero means stop the sequence. A `⚠ BLOCKING DIALOG` warning also stops the next action even if a read-only command succeeded. Inspect `dialog list` and choose a named button only within the user's existing authorization; never automatically replay an action that might already have run.
Keep stdout and stderr separate. Do not discard stderr or use `2>&1 | tail -1` / a live `head -1` pipe. Enable `set -o pipefail` for shell pipelines and check each step. For executable capture and loop guidance, read [command-results.md](references/command-results.md). Successful execution still requires the page-state checks below.
Treat the command-reference and pattern blocks below as individual steps, not unchecked batches; apply this gate to every invocation.
## Core Workflow
```bash
# Navigate
safari-browser open "https://example.com"
# Discover elements (like agent-browser snapshot)
safari-browser snapshot # @e1 input[type="email"], @e2 button "Submit"
safari-browser snapshot -c # compact (hide invisible elements)
safari-browser snapshot --json # structured JSON output
# Interact using @refs or CSS selectors
safari-browser fill @e1 "user@example.com"
safari-browser click @e2
# Observe before the next action — exit 0 means the command ran,
# not that the page did what you meant (see "Observe After Acting")
safari-browser js "return location.pathname"
# Get information
safari-browser get url
safari-browser get text "h1"
# Wait for page changes (--for-url, NOT --url: --url targets a document)
safari-browser wait --for-url "dashboard"
safari-browser wait --js "document.querySelector('.loaded')"
```
## Observe After Acting
**Gate the next step on the page's state, not on the previous command's return value.**
A command that exits 0 tells you the command ran. It does not tell you the page changed,
or changed the way you meant.
After every state-changing action — `click`, `fill`, `select`, `press`, `open`, `upload` —
read back a cheap signal before continuing:
```bash
safari-browser click "@e3"
safari-browser js "return location.pathname + ' | ' + (document.querySelector('#status')||{}).textContent"
# decide what to do next from THIS, not from click's exit code
```
The default read is `location.pathname` plus whatever the action was supposed to affect —
the field you filled, the row that should have appeared, the button that should now be
gone. One extra call per action; recovery from an undetected divergence costs far more,
and costs more the longer it goes unnoticed.
### Why: four ways the signal comes loose from the state
All four are from one session against a government portal (frameset + iframe,
server-rendered forms). Each would have been caught immediately by a post-action read.
| What happened | What the tool reported |
|---|---|
| A text-matched `確認` hit a *different* button and navigated to a PDF preview | success — four more commands ran against the wrong page |
| `set URL` did nothing on a blank POST-result page | success; `location.pathname` never changed |
| A widget-backed date field rendered one value while `.value` returned another | the string previously assigned — wrong in both directions |
| A click navigated before its return value could be collected | `undefined` — a script gating on `=== "opened"` aborted a step that had worked |
### Rules that follow
- **Text is not identity.** `find text "確認"` matches the first thing that reads that way,
which on a page with a modal is often not the modal's button. Scope to a container, or
check the element's `id` / `onclick` before clicking it.
- **Widget-backed fields need the widget's API.** Date pickers, comboboxes and rich editors
keep their own state; the underlying `input.value` is authoritative for neither reading
nor writing.
- **`undefined` is not failure.** A navigation can begin before a return value is collected.
Confirm from the page, not from what came back.
- **An empty result is not an empty page.** `get text` returning nothing may mean a blocked
tab — a JavaScript dialog freezes the tab and safari-browser will say so if it can see
one, but only when Accessibility is granted.
## Command Reference
### Navigation
```bash
safari-browser open <url> [--new-tab] [--new-window]
safari-browser back
safari-browser forward
safari-browser reload
safari-browser close
```
### Element Interaction
```bash
safari-browser click <selector>
safari-browser dblclick <selector>
safari-browser fill <selector> <text> # clear + fill + input/change events
safari-browser type <selector> <text> # append text + input event
safari-browser select <selector> <value> # dropdown
safari-browser hover <selector>
safari-browser focus <selector>
safari-browser check <selector> # checkbox
safari-browser uncheck <selector>
safari-browser scroll <dir> [pixels] # up/down/left/right, default 500px
safari-browser scrollintoview <selector>
safari-browser highlight <selector> # red outline for debug
safari-browser drag <src> <dst> # drag and drop (JS events)
```
### Keyboard
```bash
safari-browser press Enter
safari-browser press Tab
safari-browser press Escape
safari-browser press Control+a # modifier combos
safari-browser press Shift+Tab
```
### Find Elements (by text/role/label/placeholder)
```bash
safari-browser find text "Submit" click
safari-browser find role "button" click
safari-browser find label "Email" fill "user@example.com"
safari-browser find placeholder "Search" fill "query"
```
### JavaScript
```bash
safari-browser js "document.title"
safari-browser js --file script.js
safari-browser js "JSON.stringify(localStorage)"
safari-browser js --large "document.body.innerText" # chunked read for large output
safari-browser js --output /tmp/page.txt "document.body.innerText" # write to file
```
**Large output handling**: Safari's `do JavaScript` silently drops results >~1MB. Use `--large` to force chunked read, or `--output` to write to file. The CLI auto-retries with chunked read when it detects empty output.
### Page & Element Info
```bash
safari-browser get url
safari-browser get title
safari-browser get text [selector] # full page or element
safari-browser get source
safari-browser get html <selector>
safari-browser get value <selector> # input value
safari-browser get attr <selector> <name>
safari-browser get count <selector>
safari-browser get box <selector> # bounding box JSON
```
### State Checks
```bash
safari-browser is visible <selector> # true/false
safari-browser is exists <selector>
safari-browser is enabled <selector>
safari-browser is checked <selector>
```
### Snapshot (Element Discovery + Page State)
```bash
safari-browser snapshot # scan interactive elements → @e1, @e2...
safari-browser snapshot -c # compact (exclude hidden elements)
safari-browser snapshot -d 3 # limit DOM depth
safari-browser snapshot --page # full page state: accessibility tree + metadata + alerts + dialogs
safari-browser snapshot --page --json # full page state as JSON
safari-browser snapshot --page -s "main" # scoped to <main> element
safari-browser snapshot -s "form.login" # scope to CSS selector
safari-browser snapshot --json # JSON array output
```
All selector-accepting commands support `@eN` refs from the last snapshot.
### Screenshot, PDF & Upload
```bash
safari-browser screenshot [path] # default: screenshot.png [non-interfering]
safari-browser screenshot --full path # full page [non-interfering]
safari-browser pdf --allow-hid [path] # export as PDF [actively interfering — requires --allow-hid]
safari-browser upload <selector> <file> # smart default: native dialog if Accessibility permitted, else JS fallback
safari-browser upload --js <sel> <file> # force JS DataTransfer injection [non-interfering]
safari-browser upload --native <sel> <file> # force native file dialog [requires Accessibility permission]
```
**Upload behavior**: With Accessibility permission granted, `upload` uses the native file dialog by default (clipboard paste for path input — fast, supports all characters including CJK and spaces). Without permission, it automatically falls back to JS DataTransfer injection and prints a hint to stderr. Use `--js` to force JS mode, or `--native`/`--allow-hid` to force native mode (backward compatible).
**PDF export**: Uses clipboard paste for path input (instead of keystroke), precise waits (`repeat until exists`) instead of blind delays, and AXDefault button click (locale-independent) for the Save button. Still requires `--allow-hid`.
### Tab Management
```bash
safari-browser tabs # list all tabs
safari-browser tabs --json # JSON array output
safari-browser tab <n> # switch to tab n
safari-browser tab new # new tab
```
### Wait
```bash
safari-browser wait <ms> # wait milliseconds
safari-browser wait --for-url <pattern> # wait for URL to contain pattern
safari-browser wait --js <expr> # wait for JS truthy
safari-browser wait --timeout <ms> # custom timeout (default 30s)
```
### Storage
```bash
safari-browser cookies get [name] # get all or by name
safari-browser cookies get --json # JSON object output
safari-browser cookies set <name> <value>
safari-browser cookies clear
safari-browser storage local get <key>
safari-browser storage local set <key> <value>
safari-browser storage local remove <key>
safari-browser storage local clear
safari-browser storage session get/set/remove/clear
# Multi-window: per-origin storage requires --url targeting (#23)
safari-browser storage local get token --url plaud # Plaud's token
safari-browser storage local get token --url oauth # different OAuth provider's token
```
### Multi-Window Targeting (#17 #18 #21 #23)
When Safari has more than one window open, every command that reads from
or drives a document accepts global targeting flags:
```bash
safari-browser documents # discover available windows
safari-browser get url --url plaud # target by URL substring
safari-browser get title --window 2 # target by window index (1-based)
safari-browser snapshot --url plaud # snapshot specific document
safari-browser wait --for-url "/dashboard" --url plaud # wait on specific document
# Window-scoped commands (close/screenshot/pdf/upload --native) only accept --window
safari-browser screenshot --window 2 out.png
safari-browser pdf --window 2 --allow-hid out.pdf
safari-browser upload --native "input[type=file]" file.mp3 --window 2
```
**Reusing a lock flag across commands — use a bash array, not a string.**
To lock several commands to the same document, store the flag in an **array** so
it word-splits in both shells. A plain string + unquoted `$LOCK` breaks under zsh
(Claude Code's Bash runs zsh), which does NOT word-split unquoted variables —
`--url plaud` is then passed as one token and the CLI errors `Unknown option
'--url plaud'`:
```bash
LOCK=(--url plaud) # ✅ array — splits in bash AND zsh
safari-browser snapshot "${LOCK[@]}"
safari-browser get url "${LOCK[@]}"
# ❌ LOCK="--url plaud"; safari-browser snapshot $LOCK # breaks under zsh
```
**Default `screenshot` behavior** (#23 R7): when AX permission is granted, default `screenshot` (no flag) uses AX SPI for reliable identity (no title/bounds heuristic). Without AX permission, falls back to legacy CG name match.
**`screenshot --window N`** (#23 R6 C1): requires Accessibility permission. Uses `_AXUIElementGetWindow` private SPI for reliable AS↔CG mapping. Eliminates the wrong-window failure modes that bedevil bounds-/title-based matching. Strict fail-closed: throws `windowIdentityAmbiguous` when multiple visible windows can't be uniquely identified, instead of silently picking one.
**Wait command rename** (#23 BREAKING): `wait --url <pattern>` → `wait --for-url <pattern>`. The old `--url` flag is now a global targeting flag.
### Settings
```bash
safari-browser set media dark # force dark mode
safari-browser set media light # force light mode
```
### Debug
```bash
safari-browser console --start # capture all levels (log/warn/error/info/debug)
safari-browser console # read captured messages ([warn], [error] prefixed)
safari-browser console --clear
safari-browser errors --start # capture JS errors
safari-browser errors
safari-browser mouse move <x> <y>
safari-browser mouse down / up / wheel <dy>
```
### Local Safari Data (on-disk — the only way to answer "what did I look at before")
Every other command drives the **running** browser. These four read Safari's own files under
`~/Library/Safari/`, so they work with Safari closed and answer questions about the past.
The direct `bookmarks --search` example requires a CLI build containing [the bookmark-search feature](https://github.com/PsychQuant/safari-browser/issues/120). Check `safari-browser bookmarks --help` first. If it is missing, update the CLI checkout to a revision containing that feature before installing; re-signing an old binary does not add it. The recall helper below uses existing `bookmarks --json` and performs its own title/URL matching, so it does not require that newer flag.
```bash
safari-browser history --search agent --limit 50 # browsing history (default limit applies)
safari-browser history --since 2026-08-01
safari-browser bookmarks --folder AI # bookmarks + Reading List (folder filter)
safari-browser bookmarks --search swift --json # title/URL search; can combine with --folder
safari-browser cloud-tabs # tabs open on your other devices
safari-browser downloads
```
All four take `--json`. Data is on stdout; keep stderr for permission, missing-source and parse diagnostics. Parse only stdout and check the exit code before using it. An empty JSON result is `[]`, but its accompanying diagnostics determine what that means.
**These require Full Disk Access, and the grant is bound to the binary's code signature —
not to its path.** An ad-hoc signed binary (what `make install` produces) cannot hold a
durable FDA grant, so the commands detect their own signing state and print guidance specific
to it. Follow what the error says rather than assuming "add it in System Settings" will stick.
A missing source file is **not** an error: `cloud-tabs` on a Mac that never enabled iCloud tab
syncing exits 0 with a note on stderr. That is a configuration state, not a failure.
**Finding a page you cannot name.** Read [the recall workflow](references/recall.md). Start with a broad clue in history, add bookmarks/Reading List, then other-device tabs or download clues as relevant. Collect a human-readable candidate batch rather than repeatedly guessing terms. Deduplicate by full URL, preserve identical titles on different URLs, and report all query/display limits.
The read-only helper `scripts/recall.py` next to this SKILL.md collects JSON in memory, retains source clues and diagnostics, and produces sorted candidate pages with coverage metadata. It never opens URLs or writes browser-data temp files. Resolve `${CLAUDE_SKILL_DIR}` to this skill's directory before invoking it; see the reference for examples and verification limits.
For Google Forms, use the sibling `safari-google-fill` playbook. It verifies section changes and hands inaccessible file picking to the user before checking the attachment and submission state.
## Common Patterns
### Login-Required Site (e.g., Plaud)
```bash
# Safari already has the session — just navigate
safari-browser open "https://web.plaud.ai"
safari-browser wait --js "!document.querySelector('.login-form')"
# Get JWT from localStorage
TOKEN=$(safari-browser js "localStorage.getItem('tokenstr')")
# Use token with curl for API calls
curl -H "Authorization: $TOKEN" https://api.example.com/data
```
### Form Submission
```bash
safari-browser open "https://example.com/form"
safari-browser fill "input#name" "John"
safari-browser fill "input#email" "john@example.com"
safari-browser select "select#country" "TW"
safari-browser check "input#agree"
safari-browser click "button[type='submit']"
safari-browser wait --for-url "success"
```
### File Upload
```bash
safari-browser open "https://example.com/upload"
safari-browser upload "input[type='file']" "/path/to/document.pdf" # smart default (native if permitted, else JS)
safari-browser upload --js "input[type='file']" "/path/to/document.pdf" # force JS injection (no permissions needed)
safari-browser upload --native "input[type='file']" "/path/to/document.pdf" # force native dialog
safari-browser wait 5000 # wait for upload to complete
```
### Human-like Delays (Anti-Bot)
When automating sites that detect bots (banks, hospital EMR, social media), use Cauchy-distributed random delays instead of fixed `sleep`:
```bash
# Cauchy delay: median ~3s, occasionally 5-10s (simulates human rhythm)
sleep $(python3 -c "import random, math; print(max(2, round(3 + math.tan(math.pi * (random.random() - 0.5)) * 0.8, 1)))")
```
Use between every `safari-browser` command when operating sensitive sites. Never use fixed intervals — that's how bots get detected.
## Troubleshooting
- **Binary killed (exit 137 / SIGKILL)** — two different causes, same symptom. (a) *Unsigned binary*: macOS kills unsigned binaries that call osascript. Fix: re-run the install target you used — `make install`, or `DEVELOPER_ID=<cert-sha1> make install-signed`. **Do not reach for a bare `codesign --force --sign - ~/bin/safari-browser`**: on a binary installed with `install-signed` that re-signs it ad-hoc, replacing an identity-bound designated requirement with the content hash and silently destroying the durable Full Disk Access grant — the exact state the FDA limitation below describes. (b) *Reused inode*: an older `make install` copied over a path still held open by a running process, and macOS caches signature validation per inode — so re-signing does NOT help, because it writes the same inode. Fix: `rm -f ~/bin/safari-browser` then reinstall. Current `make install` / `make install-signed` avoid it structurally — they sign a `mktemp` staging file and land it with `mv`, and a rename gives the destination a fresh inode (safari-browser#121). This bites only binaries installed by an older checkout.
- **Large JS output returns empty** — Safari `do JavaScript` silently drops results >~1MB. Use `safari-browser js --large "..."` or `--output /tmp/result.txt` for chunked read.
## Limitations
- **macOS only** — requires Safari + AppleScript
- **Not headless** — Safari always has a visible window
- **JS returns strings only** — use `JSON.stringify()` for objects
- **JS output ~1MB limit** — use `--large` flag for bigger results (auto-retries with chunked read)
- **No network interception** — Safari has no API for this
- **JS-based snapshot** — `snapshot` uses DOM scanning (not CDP accessibility tree), 90% as effective
- **Automation permission required** — first run prompts for Terminal → Safari access (System Settings → Privacy & Security → Automation)
- **upload smart default** — uses native file dialog when Accessibility permission is granted; auto-falls back to JS DataTransfer otherwise. Force with `--js` or `--native`
- **Local-data commands require Full Disk Access** — `history` / `bookmarks` / `cloud-tabs` / `downloads` read `~/Library/Safari/`. TCC binds the grant to the binary's *designated requirement*, and an ad-hoc signature's requirement **is** the content hash — so the grant stops applying after every rebuild, silently. Install with `DEVELOPER_ID=<cert-sha1> make install-signed` (not `make install`) for a grant that survives; `make verify-install-signature` reports which state the installed binary is in. The commands say which case you are in rather than failing opaquely (safari-browser#119)
- **pdf requires Accessibility permission** — System Settings → Privacy & Security → Accessibility (uses clipboard paste + AXDefault button click)
## Playbooks
Site-specific operation guides live as sibling skills named `safari-<site>-<action>/SKILL.md` — Claude Code auto-surfaces them by description when the user's intent matches. Available playbooks: `safari-plaud-upload`, `safari-github-star`, and `safari-google-fill` (Google Forms). To add a personal playbook (private site, custom flow), drop a `SKILL.md` at `~/.claude/skills/safari-<site>-<action>/SKILL.md` using the same convention; Claude loads user-local skills natively and no custom precedence is added by this plugin. Contribution guide: `plugins/safari-browser/skills/CONTRIBUTING-PLAYBOOKS.md`. Authoritative spec: `openspec/specs/playbook-skills/spec.md` in the safari-browser repo.
Pliki w paczce (4)
- SKILL.md 23 KB
- references/command-results.md 3 KB
- references/recall.md 7 KB
- scripts/recall.py 9 KB
Wersje
W bazie nie ma innych skilli o nazwie safari-browser.
Migawka bazy z 13.11.2026 · wersja paczki 53b17409627a (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100safari-plaud-upload
Wysyła pliki audio do Plaud przez Safari, dodaje ścieżki do folderu i uruchamia transkrypcję nagrania z dysku. - 95control-safari
Steruje otwartymi kartami Safari z zachowaniem zalogowania i sprawdza lub wypełnia strony przez skrypty JavaScript. - 100claude-for-safari
Steruje prawdziwą przeglądarką Safari na macOS przez AppleScript, JavaScript strony, zrzuty ekranu i sprawdzone zdarzenia System Events: czyta strony, nawiguje, klika i wypełnia formularze niewrażliwe. - 100safari-github-star
Dodaje gwiazdkę do repozytorium GitHub w zalogowanym Safari, gdy użytkownik chce działać we własnej sesji przeglądarki. - 90safari
Steruje Safari z Claude Code przez lokalny serwer MCP, testuje i sprawdza stronę w WebKit, także w zalogowanej przeglądarce. - 90safari-extension-control-workflow
Prowadzi decyzje o integracji aplikacji macOS z Safari: Web Extensions, Web Inspector Extensions, App Extensions, SafariServices, blokery treści i komunikacja rozszerzeń z aplikacją.