---
name: hd-open-url-mac
description: >
  macOS platform companion to hd-open-url — the Apple-specific half of "open a URL
  in a native browser". The six ways to open a URL (Hydrogen webview tab, HD window,
  Pup, native browser, the Browser Picker, headless curl), the decide-for-the-user
  rule, the /open-url + /open-in-profile + prefs API all live in hd-open-url
  (adom/hd-bootstrap); THIS skill carries only the macOS native-browser mechanics:
  launching via LaunchServices (`open` / `open -a "<App Name>"` / `--new-window`
  fresh windows), macOS browser-profile dirs, and the control-URL discovery file
  (~/.adom/hd-control-url). Mirror of hd-open-url-windows (chrome.exe/msedge.exe by
  path). Trigger words — open url macos, open -a, native browser mac, Safari Chrome
  Arc Edge, fresh window mac, browser profiles mac, hd-control-url.
---

# hd-open-url (macOS) — opening URLs in native macOS browsers

This is the **macOS half** of `hd-open-url`. The decision framework — the six ways to
open a URL, "decide for the user — DON'T hand them the picker", the
`/open-url` · `/open-in-profile` · `/browser-picker/prefs` API, the fresh-window
rationale for auth flows — is host-agnostic and lives in the generic **hd-open-url**
skill. Read that first; this skill only covers how the **native-browser path (#4)**
launches on a Mac.

## Control-URL discovery — `~/.adom/hd-control-url`

Same as the generic skill: read the live base URL from `~/.adom/hd-control-url`
(`BASE="$(cat ~/.adom/hd-control-url)"`) — never hard-code the port. On macOS that file
resolves to the **`adom-host` gateway** from inside the workspace machine, because the
Apple `vz` VM does NOT mirror host loopback (`127.0.0.1` inside the machine is NOT the
Mac, and HD's host services bind `0.0.0.0`). See `hd-api-mac` for the gateway detail.

## Native browsers launch via LaunchServices (`open` / `open -a`)

The `/open-in-profile` and direct native-browser paths drive macOS browsers through
LaunchServices, not by resolving an `.exe`:

- **Default / shell-open:** `open <url>` (LaunchServices picks the user's default
  browser) — `open_in_browser_profile` / `screenshot.rs`.
- **Named browser:** `open -a "<App Name>" <url>`. `screenshot.rs` maps
  `chrome→"Google Chrome"`, `edge→"Microsoft Edge"`, `firefox→"Firefox"`,
  `brave→"Brave Browser"`; **Safari** and **Arc** are likewise app-name targets. Using
  the app *name* (not a path) handles user-relocated installs uniformly.
- **Fresh window (`fresh:true`):** to force a brand-new window/process HD resolves a
  concrete browser binary and passes `--new-window` (Chromium) / `-new-window` (Firefox)
  before the URL — `open -a … <url>` alone opens a tab, not a window (`lib.rs`
  fresh-window branch). A freshly-launched window auto-foregrounds, so this is the path
  for **Claude/Adom auth pages the user must complete** (the generic skill defaults the
  fresh toggle ON for those).

## macOS browser-profile dirs

`GET /browser-profiles` enumerates the user's installed browsers + profiles so
`/open-in-profile {browser, profileDir}` can target the **work** profile (where saved
logins live). On macOS those profiles live under the app's Application Support dir
(e.g. `~/Library/Application Support/Google/Chrome/<Profile>`,
`…/Microsoft Edge/<Profile>`), as opposed to the Windows `%LOCALAPPDATA%\…\User Data`
layout. Discover them via the endpoint rather than assuming a path or browser — don't
hard-code `chrome`/`edge`.

## NOT here (lives in the Windows companion)

Launching `chrome.exe` / `msedge.exe` by resolved path (`find_browser_exe`), the
`%LOCALAPPDATA%\…\User Data\<Profile>` profile-dir layout, and the Windows
`--new-window` / `--profile-directory` exe invocation are the Windows native-browser
path — see `hd-open-url-windows`. On macOS it's LaunchServices (`open` / `open -a`) with
app-name targets.