Osascript Chrome

osascript-chrome

Full Chrome automation via AppleScript/JXA + Chrome profile data files. All scripts are Python.

Critical Gotchas (read before writing any Chrome script)

• Minimized windows invisible: Chrome returns 0 windows when minimized. Always verify via System Events first.
• Tab variable reference loss: NEVER store a tab in a variable then execute JS on it. Execute JS inline at the point of match — see scripts/execute-js-in-tab.py for the outer: labeled-break pattern.
• without activating is invalid on Chrome's tell block — use System Events focus snap instead.
• CDP for headless / Electron: osascript only works with real GUI Chrome. Use CDP (see reference/08-cdp.md) for headless or Slack/VSCode/Notion.
• activeTabIndex is 1-based: Chrome AS dictionary uses 1-based tab indices for the active tab property. Array access (tabs[ti]) is still 0-based.
• SQLite scripts copy-first: chrome-history, chrome-downloads all copy the DB to a tempfile before querying — Chrome locks the file while running.

Tab Control

List all open tabs across all windows (handles minimized via System Events):

uv run scripts/list-tabs.py

Bring a tab matching a URL pattern to front and activate Chrome:

uv run scripts/focus-tab.py github.com
uv run scripts/focus-tab.py --window 0 --tab 2

Close tab(s) by URL pattern — --all to close every match:

uv run scripts/close-tab.py github.com
uv run scripts/close-tab.py github.com --all

Navigate an existing tab to a new URL (no new tab opened):

uv run scripts/navigate-tab.py github.com "https://github.com/new"

Reload a tab — --hard bypasses cache:

uv run scripts/reload-tab.py localhost
uv run scripts/reload-tab.py localhost --hard --all

Mute/unmute tabs — --on, --off, --all, --status:

uv run scripts/mute-tab.py youtube.com --on
uv run scripts/mute-tab.py --all --off
uv run scripts/mute-tab.py --status

List tabs currently playing audio (audible property) — --all for full state:

uv run scripts/tab-audio.py
uv run scripts/tab-audio.py --all

Window Management

List all Chrome windows with mode, tab count, active tab — --tabs for full detail:

uv run scripts/list-windows.py
uv run scripts/list-windows.py --tabs

Open a URL in Chrome — --background keeps current focus:

uv run scripts/open-tab.py "https://example.com"
uv run scripts/open-tab.py "https://example.com" --background

Open a new Chrome window — --incognito for private mode:

uv run scripts/new-window.py
uv run scripts/new-window.py --incognito "https://example.com"

Close a Chrome window — --list to preview, --empty to purge newtab-only windows:

uv run scripts/close-window.py 0
uv run scripts/close-window.py --empty
uv run scripts/close-window.py --list

JavaScript Execution & Content Extraction

Read DOM content from a tab (defaults to document.body.innerText):

uv run scripts/read-tab.py github.com
uv run scripts/read-tab.py gmail.com "document.title"

Execute arbitrary JS expression in a tab and return the result:

uv run scripts/execute-js-in-tab.py "localhost:3000" "JSON.stringify(window.__STATE__)"

Full structured extraction — title, OG meta, headings, links, images, body text:

uv run scripts/scrape-page.py github.com
uv run scripts/scrape-page.py docs.google.com --text-only
uv run scripts/scrape-page.py example.com --links-only

All <a> links with href + anchor text — --filter to match specific hrefs:

uv run scripts/scrape-links.py github.com
uv run scripts/scrape-links.py github.com --filter "/pull/"

Read localStorage and sessionStorage — --key for a single value:

uv run scripts/tab-storage.py localhost:3000
uv run scripts/tab-storage.py app.example.com --key "auth_token"

Read document.cookie as a parsed list (HttpOnly cookies are not accessible by design):

uv run scripts/tab-cookies.py github.com
uv run scripts/tab-cookies.py app.example.com --name "session"

Fill an input by CSS selector — fires React/Vue events — --submit to submit the form:

uv run scripts/form-fill.py "google.com" "input[name='q']" "search term"
uv run scripts/form-fill.py "example.com/login" "#password" "secret" --submit

Chrome Profile Data (file-based, no GUI needed)

Read Chrome browsing history — supports --profile, search term:

uv run scripts/chrome-history.py
uv run scripts/chrome-history.py 50 github

Read Chrome download history — state, size, mime type, timestamps:

uv run scripts/chrome-downloads.py
uv run scripts/chrome-downloads.py 50 pdf --complete

Read all bookmarks with folder paths — --search, --folder, --list-profiles:

uv run scripts/chrome-bookmarks.py
uv run scripts/chrome-bookmarks.py --search "github" --profile "Default"

List installed Chrome extensions with enabled state — --permissions for full detail:

uv run scripts/chrome-extensions.py
uv run scripts/chrome-extensions.py --search "blocker" --permissions

List all Chrome profiles with name, email, history size:

uv run scripts/chrome-profile.py
uv run scripts/chrome-profile.py --detail

Tab Properties Available via JXA

Reference

• reference/02-chrome.md — Tab enumeration, JS execution, focus management, JXA syntax
• reference/08-cdp.md — CDP over WebSocket for Electron apps and headless Chrome
• reference/15-limitations-and-gotchas.md — Tab reference loss, minimized windows, Electron blind spots

When to use osascript vs CDP

Use osascript when Chrome is already open with real GUI windows, you need the existing session/cookies, or simple tab control/JS execution.

Use CDP (reference/08-cdp.md) when you need Electron apps (Slack, VSCode, Notion), headless operation, or network interception.