claude-for-safari

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

claude-for-safari

★ 64 Open GitHub ↗

Give your AI Agent the power to control Safari on macOS. No extensions, no separate browser.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Claude for Safari</h1>

Give your AI Agent the power to control Safari

<a href="https://safari.skilljam.dev">Website</a> · <a href="#quick-start">Quick Start</a> · <a href="#features">Features</a> · <a href="#faq">FAQ</a>

<a href="README.md">English</a> | <a href="README_CN.md">中文</a>

---

## Why This?

You want your AI Agent to help with browser tasks — then you discover:

- 🔒 **Playwright** → Separate browser instance, hijacks your session
- 🧩 **Claude for Chrome** → Requires Chrome extension, doesn't work with Safari
- 📝 **Copy & paste** → Manually feeding page content to AI every time

**You just want AI to use your Safari, as if you were doing it yourself.**

**Claude for Safari makes it one command:**

```
npx skills add SDLLL/claude-for-safari
```

After installing, tell Claude "check what's open in my Safari" — it reads and controls your real browser directly.

> **If this saves you time, [give it a ⭐](https://github.com/SDLLL/claude-for-safari/stargazers)** — it helps other developers discover the project!

---

## Quick Start

Run this in your terminal:

```bash
npx skills add SDLLL/claude-for-safari
```

Then launch [Claude Code](https://claude.ai/download):

```bash
claude
```

Say "show me what tabs are open in Safari". The agent will guide you through permission setup automatically.

> Compatible with any AI Agent that supports Skills: Claude Code, Cursor, Windsurf, etc.

### First-Time Setup

The agent auto-detects and guides you, but you can configure ahead of time:

1. **System Settings > Privacy & Security > Automation** → Allow terminal to control Safari
2. **Safari > Settings > Advanced** → Enable "Show features for web developers"
3. **Safari > Develop menu** → Check "Allow JavaScript from Apple Events"
4. **(Optional) System Settings > Privacy & Security > Screen Recording** → Allow the terminal or agent host (enables reliable background screenshots)
5. **(Optional) System Settings > Privacy & Security > Accessibility** → Required only for System Events clicks and keystrokes

---

## Features

No browser extension, proxy, or persistent daemon. The core uses macOS-native capabilities; optional window helpers require an available Swift toolchain.

| Capability | What the Agent Does | How |
|---|---|---|
| **List tabs** | List all windows and tabs with title & URL | AppleScript |
| **Read pages** | Extract text, structured data, simplified DOM | AppleScript + JavaScript |
| **Execute JS** | Run arbitrary JavaScript in page context | AppleScript `do JavaScript` |
| **Screenshot** | Capture Safari window — AI can "see" the page | `screencapture` |
| **Navigate** | Open URLs, new tabs, new windows | AppleScript |
| **Click** | Click elements (React/Vue/Angular compatible) | JavaScript `dispatchEvent` |
| **Type** | Fill forms, simulate keyboard input | JavaScript + System Events |
| **Safe form filling** | Discover fields and fill supported non-sensitive controls with per-field verification | Bundled JavaScript + JXA |
| **Network observation** | Observe redacted page-level fetch/XHR metadata; bodies are explicit opt-in | Bundled JavaScript |
| **Control indicator** | Show when an agent is changing a page and clean up afterward | Bundled JavaScript |
| **Scroll** | Scroll up/down, scroll to element | JavaScript `scrollBy/scrollTo` |
| **Switch tabs** | Switch by index or URL keyword | AppleScript |
| **Wait for load** | Wait until page is fully loaded | JavaScript `readyState` |

### Screenshot Modes

| Mode | Permission Required | Window Switch | Best For |
|---|---|---|---|
| **Background** | Screen Recording | No switch | Recommended, seamless |
| **User-visible** | Varies by macOS policy | Yes | Fallback when background capture is unavailable |

---

## How It Works

```
Claude Code ──osascript──► Safari (reads/controls your real browser)
     │
     └──screencapture──► screenshot ──► Claude sees the page
```

No extensions, proxy servers, or persistent background services.

The skill uses AppleScript, page JavaScript, `screencapture`, and optional bundled helpers. Page-injected helpers can be detected by websites and are removed after use.

---

## FAQ

<details>
<summary>Do I need to install anything?</summary>

The core requires no browser extension or separate automation browser. It uses macOS AppleScript and `screencapture`; compiling the optional multi-window helper requires `swiftc`/Apple Command Line Tools.
</details>

<details>
<summary>Does it support Chrome / Firefox / Arc?</summary>

Safari only. For other browsers, use <a href="https://github.com/nicepkg/playwright-mcp">Playwright MCP</a> or <a href="https://github.com/Areo-Joe/chrome-acp">Chrome ACP</a>. Safari is the only macOS browser with full AppleScript automation support.
</details>

<details>
<summary>Is it safe? Will AI do random things?</summary>

The skill requires target verification, preserves site confirmation dialogs, excludes sensitive form fields, and asks for authorization before consequential actions. Your agent host's own permission policy still applies.
</details>

<details>
<summary>The window flickers when taking screenshots?</summary>

Grant Screen Recording permission to the terminal or agent host for reliable background window capture. Without it, use a user-visible Screenshot workflow and verify the resulting image rather than assuming capture succeeded.
</details>

<details>
<summary>Which AI Agents are compatible?</summary>

Any agent supporting Claude Code Skills: Claude Code, Cursor, Windsurf, etc.
</details>

---

## Acknowledgements

- [@rrecio](https://github.com/rrecio) contributed the form, control-indicator, window-helper, network-observer, and real-Safari testing ideas in [PR #2](https://github.com/SDLLL/claude-for-safari/pull/2).
- [@jordan-brough](https://github.com/jordan-brough) contributed permission, dialog, locale, timestamp, and Safari UI measurement findings in [PR #3](https://github.com/SDLLL/claude-for-safari/pull/3).

Their work informed the maintainer-integrated, safety-hardened implementation.

---

## License

[MIT](LICENSE)

claude-for-safari

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README