mac-browser

Control your running browser on macOS via AppleScript — no restarts, no special flags, full access to your existing sessions and cookies.

Supports Microsoft Edge, Google Chrome, and Safari.

Why

Other browser automation tools (Playwright, CDP) require launching a dedicated browser instance. mac-browser talks directly to your already-running browser via AppleScript, meaning:

• Private GitHub repos, Google Docs, internal dashboards — all accessible without re-login
• No browser restarts or extra configuration
• Works with any site you're already authenticated with

Install as an AI Agent Skill

Drop this folder into your AI agent's skills directory and it will automatically be available when the agent needs to read web content from your browser.

# Claude Code
git clone https://github.com/mchades/mac-browser ~/.claude/skills/mac-browser

# GitHub Copilot CLI
git clone https://github.com/mchades/mac-browser ~/.copilot/skills/mac-browser

Prerequisites

• macOS only
• A supported browser must be running (Edge, Chrome, or Safari)
• Enable Allow JavaScript from Apple Events in your browser:
  • Edge / Chrome: View → Developer → Allow JavaScript from Apple Events
  • Safari: Develop → Allow JavaScript from Apple Events
    (If Develop menu is hidden: Safari Settings → Advanced → Show Develop menu in menu bar)

How it works

AppleScript provides a scripting interface to macOS applications. Both Chromium-based browsers (Edge, Chrome) and Safari expose their tabs and JavaScript execution through this interface.

• Edge / Chrome: requires setting the target tab as the "active tab" in its window before calling execute javascript. The original active tab is restored after execution. The browser window itself never comes to the front.
• Safari: supports do JavaScript ... in tab N of window M directly — no active-tab switch needed.

Scripts Reference

These scripts are invoked automatically by the AI agent. You don't need to call them manually.

Script	Description
list-tabs.sh	List all open tabs across all running browsers
find-tab.sh <pattern>	Find a tab by URL pattern
get-text.sh <pattern> [max-chars]	Get page text from a matching tab
eval-js.sh <pattern> <js>	Execute JavaScript in a matching tab
navigate.sh <url>	Open a URL in a new tab
screenshot.sh [path]	Take a screenshot of the browser window

Override the browser with MAC_BROWSER=chrome|safari|edge before any script.

License

Apache 2.0