The pup for macOS SKILL PACK: the AI skills that teach a cloud/container AI how to drive the macOS Puppeteer (pup) bridge (pup_* verbs): the everyday `pup` skill plus focused sub-skills for windows/sessions/tabs, screenshots+recording, credentials, lanes, settings, browsers+Chrome install, vendor logins and the Adom wiki. Installs into ~/.claude/skills + ~/.codex/skills. DOCS ONLY: this is NOT the bridge runtime. The bridge itself is one signed macOS binary that Adom Bridge for macOS installs an

skills pup puppeteer browser adom-bridge bridge macos pup-bridge-macos

Overview Files Skills Discover Packages Releases Dependencies Issues1 Breadcrumbs Pull Requests1 Activity

Install?

adom-wiki pkg install adom/pup-bridge-macos

Latest: v3.0.1, published 2026-11-03

Download for your machine · v3.0.1?

Release 3.0.1

Download for macOSv3.0.1 · 7.3 MB · 14 downloads

All downloads (1 file)

File	Platform	Arch	Kind	Size	sha256
adom-bridge-puppeteer-macos-v3.0.1.zip	macOS	universal	zip	7.3 MB	`cb2dc4be0ffd18ddfc662586c561a807ecd06664f1e47281a8ac2d0697ac21e0`

Dependencies 1 app

app adom/adom-bridge ^2.0.0

Contents

Install
Quick start
What it does
How it differs from the Windows line
Keeping up with the Windows line
Dependencies
Skills
Open source

README

markdown

Pup for macOS: the AI's own browser

Pup gives your AI a real browser on your Mac that it drives completely, in the background, signed in as you. Its windows live in a hidden browser app, so they never cover your work or take focus, and the AI can still open pages, click, type, read, screenshot and record them. Every window shares one profile where your logins accumulate, and pup fills saved passwords for the AI. Ask your AI to "open it in pup" and it does.

Pup for macOS is one small signed program, a universal binary for Apple Silicon and Intel Macs, that Adom Bridge installs and keeps up to date. This page holds its source, its AI skills and its releases. It is open source under the MIT license.

Install

On your Mac there is nothing to install by hand. Adom Bridge for macOS (bundled with Hydrogen) downloads pup the first time an AI asks for a browser, and updates it on its own from this page. In an AI container, install the skills so the AI knows how to use it:

adom-wiki pkg install adom/pup-bridge-macos

Quick start

Your AI addresses its windows by its own thread name, so there are no ids to track:

adom-bridge-cli --ai-thread "my-thread" pup_open_window '{"url":"https://example.com"}'   # a real window, hidden behind your work
adom-bridge-cli --ai-thread "my-thread" pup_screenshot  '{}'                              # the image lands in the container
adom-bridge-cli --ai-thread "my-thread" pup_navigate    '{"url":"https://wiki.adom.inc"}' # same window, next page
adom-bridge-cli --ai-thread "my-thread" pup_my_windows  '{}'                              # everything this thread has open

Or just say it: "open my app in pup", "screenshot this site in pup", "record a clip of this page in pup".

What it does

area	verbs
Windows and tabs	`pup_open_window`, `pup_open_tab`, `pup_switch_tab`, `pup_close_tab`, `pup_my_windows`, `pup_list_windows`, `pup_close_window`
Driving a page	`pup_navigate`, `pup_reload`, `pup_back`, `pup_forward`, `pup_click`, `pup_type`, `pup_fill`, `pup_select`, `pup_press_key`, `pup_scroll`, `pup_input_dispatch`, `pup_eval`, `pup_devtools`, `pup_dialog`
Capture	`pup_screenshot`, `pup_screenshot_element`, `pup_screenshot_full_res`, `pup_record_start` / `pup_record_stop`, `pup_annotate`
Logins and cards	`pup_login`, `pup_google_signin`, `pup_credentials`, `credential_set`, `pup_vault_sync`, `pup_card_set`, `pup_fill_card`
Showing the user	`pup_raise_os_window` (needs a `foregroundReason`), `pup_lower_os_window`, `pup_alert_window` (a notification)
Health	`pup_readiness`, `pup_prewarm`, `pup_status`, `pup_describe`

pup_describe returns the full machine-readable catalog.

How it differs from the Windows line

This is a standalone macOS app, forked from the Windows pup line (adom/pup-bridge) with every Windows code path removed.

Background means pup's browser app is hidden (the Cmd+H state), not pushed to the bottom of a window stack.
macOS has no per-window taskbar button, so there are no thread tiles, favicon badges, jump lists, taskbar progress bars or flashes. Those verbs answer honestly instead.
A nudge to the user (pup_alert_window) is a macOS notification that never takes focus.
Importing the browser's own saved passwords is not available. Logins grow when the user signs in once in a pup window, or through pup_vault_sync from another of their desktops.
Passwords live in the macOS Keychain. Pup's browser runs with an in-memory cookie key, so it never asks for Keychain access.
Installing Google Chrome on request copies it from Google's .dmg into /Applications. Recording a window needs ffmpeg (brew install ffmpeg).

Keeping up with the Windows line

Most of pup is platform-neutral, and the Windows line moves fast. tools/check-drift.sh compares this fork with the Windows page and reports what changed since the last reviewed baseline. Platform-neutral changes are ported forward; Windows-only changes are reviewed and skipped on purpose.

Dependencies

dependency	required?	why
macOS on Apple Silicon or Intel	yes	Pup for macOS is a native Mac program.
Adom Bridge for macOS	yes	It installs, updates and starts pup, and carries every command from your AI to it. Hydrogen includes it.
A browser build	automatic	Pup downloads its own Chrome build into `~/.cache/puppeteer` once, and uses an installed Google Chrome until that finishes.

Skills

The skills teach any AI how to use pup well. The main pup skill is the start; the others load when a task needs them.

skill	purpose
`pup`	Start here: the model, addressing by thread name, the everyday verbs, and the rules.
`pup-windows-sessions-tabs`	Windows, tabs, ownership and the zero-id forms.
`pup-screenshots-recording`	Every screenshot and recording option, and tricky pages.
`pup-credentials`	The vault, sign-in, Google accounts and vault sync.
`pup-lanes`	How pup drives a window and the rules that keep your closes final.
`pup-settings`	Every setting, behavior by behavior.
`pup-adom-wiki`	Viewing wiki pages signed in or as the public.
`pup-vendor-login`	Signing into vendor portals.
`pup-browsers-and-chrome`	Readiness, the browser build and cold starts (maintainer detail).
`pup-why-cft`	Why pup drives its own Chrome build (maintainer detail).

Open source

The complete source is in this page's Files tab: one Rust workspace, with every macOS API kept in a single crate (rust/host-mac). Build it with tools/build.sh <version>. Issues and ideas are welcome in the Issues tab.

Agent permissions

May run pup-bridge

3 allowed6 need approval3 environment

Show the rules

Allowed

pup-bridge read verbs (pup_screenshot, pup_status, pup_readiness, pup_describe, pup_my_windows) read the state of pup's own sandbox browser. They never touch the user's real browser.
pup-bridge drives a browser it launched and owns, in a profile it manages, in the background. Opening, navigating, clicking and evaluating there cannot affect the user's own browser.
pup-bridge pup_credentials lists saved logins as host and username only. It never returns a password.

Needs approval

pup-bridge pup_login with submit:true sends a stored password to a live site. It is reason-gated so the live domain is named and a lookalike is caught first.
pup-bridge credential_set and credential_delete write to and remove from the user's macOS Keychain.
pup-bridge pup_raise_os_window takes over the user's screen and keyboard focus.
pup-bridge pup_close_window and pup_quit_idle_browsers destroy windows the user may be looking at, which commonly hold state a person is part-way through.
pup-bridge pup_credential_reveal returns one saved password in plaintext to a local caller. The user must click Reveal on a desktop toast first, so it should never be called silently or in a loop.
pup-bridge pup_fill_card types a stored payment card into a checkout page. The user must approve EACH fill on a desktop toast naming merchant, amount and last4; the digits never reach the caller.

Environment

pup-bridge drives Chrome for Testing, installed and owned by pup, in a pup-managed profile, on the user's Mac, in a hidden browser app.
pup-bridge is NOT the user's signed-in browser. That is nb, a different package.
pup-bridge verbs are invoked through the adom-bridge CLI, not through a binary this package installs, so prefix rules cannot reach them.