Safari Control

Use this skill when the task must happen in Safari itself:

• - The user is already logged in there
• Safari extensions, cookies, or profiles matter
• You need the current tab, tab list, page URL, or page text
• A headless browser would not reflect the real session

Do not force Safari to behave like Playwright. Prefer Safari's session access and DOM helpers first, Safari native UI automation second, and desktop-control only for pointer-heavy UI.

Core Tool

Run commands from the safari-control skill directory so the relative scripts/ path resolves correctly.

CODEBLOCK0

Recommended Flow

Use this exact flow unless the task clearly starts in one specific layer:

1. 1. Check environment and active page:

CODEBLOCK1

INLINECODE3 is the branch point:

• - safari_js=false: do not use DOM commands until the user enables JavaScript from Apple Events.
• INLINECODE5: do not use native Safari chrome commands.
• INLINECODE6: use screenshot --mode foreground when you need an image.
• If Safari is missing required permissions or features, tell the user before proceeding. In particular, check whether Safari allows Automation, JavaScript in the Smart Search field, and JavaScript from Apple Events. Enabling these unlocks more functionality, but also increases risk because automation and scripted interactions gain more power over the user's Safari session. If the user refuses, do not keep pushing the recommendation and continue with the reduced feature set.

1. 2. If Safari session state matters, inspect it before mutating anything:

CODEBLOCK2

1. 3. If you need page content or web-page actions, verify DOM access:

CODEBLOCK3

1. 4. Choose the lowest layer that fits:

• - Prefer DOM commands for page content, forms, links, and standard web controls.
• Use native Safari controls or menus for the smart search field, toolbar buttons, tab groups, and menu bar commands.
• Use desktop-control only for extension popups, native pickers, pointer-heavy drag/drop, or UI Accessibility cannot expose.
• When you want to draw the user's attention to important content on the page, you may use JavaScript to visually highlight it, such as adding a red outline, background tint, or temporary annotation.

Command Layers

1. Environment and Session

Use for machine-readable state and tab/window management.

CODEBLOCK4

Rules:

• - Prefer --json for agent-readable output.
• Most read-only page commands support --window N --tab M, so you can inspect background tabs without switching focus.
• INLINECODE10 before invasive work when preserving the user's layout matters.
• INLINECODE11 is additive: it recreates windows and tabs, it does not merge with or close current ones.

2. Page Read and Inspect

Use when JavaScript from Apple Events is enabled and the target is inside the web page.

CODEBLOCK5

Rules:

• - Prefer snapshot before manual probing on unfamiliar pages.
• Prefer snapshot --interactive-only when you only need actionable controls and want smaller output.
• Prefer get-text --mode article before body; it is usually less noisy.
• Prefer element-info when a selector exists but behaves unexpectedly.

3. Page Actions and Waits

Use for standard DOM interactions after confirming the target is inside the page.

CODEBLOCK6

Rules:

• - Prefer exists, count, wait-*, and snapshot to branch explicitly before acting.
• After an action, wait on a concrete condition instead of sleeping.
• Use press-key and press-shortcut only for page-level DOM handlers, not Safari chrome.
• INLINECODE23, forward, and reload return structured before/after state for change detection.

4. Native Safari UI

Use when the target is Safari chrome, not the page.

CODEBLOCK7

Rules:

• - The menu examples in this section assume Safari is running with an English UI.
• Start with list-native-controls --json before guessing identifiers.
• The native control JSON now includes pressable, focusable, settable, and menuable fields. Use those before choosing press-native-control, focus-native-control, set-native-value, or menu actions.
• INLINECODE34 and native-search default to --confirm-mode ax. Use enter or both only if Safari's native confirm path is insufficient on that machine.
• Use list-menu-items or list-native-menu-items before clicking when Safari is localized.

Common Task Templates

Read the current page

CODEBLOCK8

Fill a form in the real Safari session

CODEBLOCK9

Operate Safari's own address bar or toolbar

CODEBLOCK10

Export and Evidence

Use when you need durable files instead of transient terminal output.

CODEBLOCK11

Rules:

• - auto screenshot mode tries background capture first and falls back to foreground.
• INLINECODE42 and save-page-bundle can read a background tab via --window / --tab, but the screenshot still comes from the visible Safari window.

JavaScript Access Requirement

If check-js reports disabled, tell the user to enable:

1. 1. Safari Settings
2. Advanced
3. Developer features if needed
4. Developer
5. INLINECODE47

Then retry check-js.

If native Safari automation or script-driven workflows are blocked, also tell the user to verify Safari settings such as:

1. 1. Allow Automation
2. Allow JavaScript in the Smart Search field
3. Allow JavaScript from Apple Events

Explain that these settings enable more Safari-control features, but they also grant more power to automation and scripted interactions. If the user declines, continue with only the features that remain available.

Release and Distribution

These are maintenance commands, not the normal interaction path:

CODEBLOCK12

Use these when you want a compiled binary, a release directory, zip artifacts, or build metadata with git and environment information.

Limits

• - Safari scripting is strong for session state, structured page inspection, waits, and standard DOM interactions.
• Safari scripting is not a robust replacement for full browser automation.
• Complex form workflows, native pickers, extension UIs, canvas apps, and pointer-heavy interactions should move to desktop-control.
• INLINECODE50 is for small files injected into input[type=file], not large native picker workflows.
• INLINECODE52 is filesystem polling, not a Safari download API.
• INLINECODE53 exposes document.cookie, not HttpOnly cookies or the full Safari cookie jar.
• INLINECODE55 only sees the current origin.