Adom Desktop — Puppeteer (pup) Bridge

Drive a browser on the user's desktop from the cloud: open/close windows + tabs, navigate, screenshot, eval JS, record windows. pup is a generic, non-profile browser — every session is a fresh, isolated Chrome/Edge process, never the user's real signed-in browser. It drives the browser already on the machine (installed Chrome, else Microsoft Edge — every Windows PC ships Edge), so the common case needs no download; Chrome for Testing is auto-fetched only as a last resort when the box has no Chromium browser at all. Windows open in the background by default so pup never disrupts the user.

To drive the user's real, signed-in Chrome/Edge (their cookies, SSO, saved logins), that's the Adom browser extension's nbrowser_* verbs — a separate bridge, not pup.

Canonical page: https://wiki.adom.inc/adom/adom-desktop-puppeteer-bridge

Install vs Download — which is which (and why the version numbers differ)

The page header shows two things, for two different places. Most people need only the first.

Why two different version numbers? They're independent artifacts. The Install (pkg) version bumps whenever the skills/docs change (often). The Download (runtime) version bumps only when the bridge code changes (rarely). So it's normal to see e.g. Install v1.8.27 and Download v1.8.20 — nothing is out of sync; they just version on their own clocks.

(There's also a third copy — the runtime is bundled inside the Adom Desktop installer as a first-run seed, superseded by a newer cache copy via updateManifestUrl. You never touch it directly.)

Use it

# everyday: open + screenshot. Opens in the BACKGROUND automatically — no need to lower it,
# and it's fully drivable/screenshottable while hidden, so the user is never interrupted.
adom-desktop browser_open_window '{"sessionId":"myapp-web","owner":"myapp","url":"http://localhost:3000"}'
adom-desktop browser_screenshot  '{"sessionId":"myapp-web"}'

# readiness (use browser_readiness, NOT browser_status). On a box with Chrome or Edge this is
# instantly {ready:true} with no download. Only a box with no Chromium at all fetches Chrome for
# Testing in the background — poll until ready, then open.
adom-desktop browser_readiness '{}'      # → {ready:true, browserKind:"chrome"|"edge"|...}

• Task-prefix your sessionId + pass owner — sessions are shared across every AI thread on the desktop; that lets pup protect your window from another thread navigating it away.
• foreground:true is the only way to show a window — sizing/positioning does not foreground it.

Full everyday usage (tabs, recording, window ownership, cold-start playbook) is in the pup skill (SKILL.md).

Window-type taskbar icons: read a pup window at a glance

Every pup window's taskbar icon states what kind of thing it is showing. All five share the same drawing (the teal Adom tile carrying a solid browser window) and differ only in the window's content: a monochrome glyph on the 24x24 Adom house grid, per the brand icon law (single color, no gradients, no emoji):

Icon	Window content	Means
	open book	Adom wiki, public view: logged out, what the world sees
	book + person	Adom wiki, signed in: the user's logged-in view (private source, drafts, owner cards)
	the Adom mark	An Adom app: localhost or a cloud-slug proxy URL
	globe	The web: any other site (ti.com, digikey, ...)
	two panes	Mixed: the window's tabs span more than one category

• The category is derived from all tabs in the window; it updates live (add a digikey tab to a wiki window and the icon flips to mixed within about a second).
• The overlay badge riding the icon's corner is separate and sacred: it is the active tab's own favicon, so you always see which site you are looking at. In grouped-taskbar mode it shows window/tab counters instead.
• The tab title carries the same login signal in text: a solid dot (● Logged in) or hollow dot (○ Public) leads the title of every Adom wiki tab.
• Under the hood, each window's identity (icon, name, Alt-Tab entry) rides a per-session Windows AppUserModelID that carries the category: the only way Win11 allows a taskbar tile to change live. Grouped mode instead keeps one stable, pinnable Adom.Pup identity.

Real windows, one per type

Full windows as pup opens them (title bar, tabs, page). Note the tab title glyphs on the wiki pair and the signed-in header on the second:

Adom wiki, PUBLIC (tab: ○ Public, page header shows Login):

Adom wiki, SIGNED IN (tab: ● Logged in, page header shows the user's name):

An Adom app (here: the shotlog viewer on a cloud slug URL):

The web (ti.com):

Mixed (a digikey tab and a wiki tab in one window):

Overlay badges: the corner of the taskbar icon

The base icon states the window TYPE; the small overlay riding its lower-right corner carries LIVE detail, composited exactly like this:

The overlay never carries branding or state that belongs to the base icon: it is live per-window detail only, and the favicon always wins the slot when one exists.

The Adom wiki: logged-in vs public view, and the taskbar toggle

pup can show any Adom wiki page from two viewpoints, and both the AI and the user can switch:

• Public (default): a fresh logged-out profile: exactly what the world sees. Use it to verify what a publish actually exposed.
• Signed in: browser_open_window {..., wikiView:"authed"} routes to a reserved persistent profile whose cookie jar holds the user's ~30-day SSO session. One login serves every AI thread on the machine. First use returns wikiLoginNeeded:true; the user signs in once, in that window.

The user can flip a wiki window themselves: right-click its taskbar button: the jump list carries "Adom wiki: switch to logged-in view" (or "...switch to public view"). Clicking it relaunches that same window under the other cookie jar, brings it to the front, and shows an on-screen caption while it works ("Switching to the logged-in view of the Adom wiki", then "Adom wiki: now the LOGGED-IN view (Their Name)"). The AI-side equivalent is the browser_wiki_set_view verb, which exists for that jump-list click: AI threads should pass wikiView on open instead.

One session, one OS window

Every pup session gets its own OS window, even when sessions share a browser profile (as all signed-in wiki windows share the authed cookie jar). This is what makes per-window identity possible: a window's title belongs to its active tab, so windows that share sessions as tabs cannot be found, branded, flashed, or given jump lists individually. Sharing a profile shares the cookies; it never merges windows.

Recording

pup can record what it drives — a single tab/window or the whole desktop — straight from the cloud, with no HUD and no need to bring the window forward.

Above: a GIF preview of a real browser_record capture (≈8.6 s, the tab navigating the Adom wiki, recorded in the background on a VM). The native capture is the WebM linked below — this GIF is just an inline preview.

Two recorders — pick by what you're capturing

adom-desktop browser_record_start '{"sessionId":"demo-web"}'          # → { recordingId }
# ...drive the scene: navigate, click, type, scroll...
adom-desktop browser_record_stop  '{"sessionId":"demo-web","recordingId":"<id>"}'   # → { path: "...webm" }

ffmpeg is required for recording. The bridge auto-detects it (a WinGet Gyan.FFmpeg install, PATH, or common dirs) and re-checks lazily on record_start — so if it's missing you can winget install Gyan.FFmpeg and just retry, no bridge restart. browser_record_status / browser_record_list (and the desktop_record_* equivalents) report in-flight and finished captures.

Formats — one native format, easy conversion

pup records to one format natively: WebM (VP9) — for both recorders. It doesn't offer a format switch; instead, convert with the bundled ffmpeg when you need MP4 or GIF. Real numbers from the ≈8.6 s demo above (1264×705):

# → MP4 (H.264 — universal). The scale filter forces EVEN dimensions (H.264 rejects odd w/h → frame 0).
ffmpeg -i rec.webm -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" -c:v libx264 -crf 23 -pix_fmt yuv420p -movflags +faststart rec.mp4

# → GIF (silent, looping inline preview). Palette pass keeps colors clean; drop fps/scale to shrink.
ffmpeg -i rec.webm -vf "fps=12,scale=640:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" rec.gif

Rule of thumb: keep WebM for archiving + web embeds; make an MP4 the moment a human on Safari/ PowerPoint/phone needs it; make a short GIF only for an inline auto-play preview.

Source & development

This bridge is cloud-owned here (extracted from adom-desktop/plugins/puppeteer, mirroring the kicad/fusion bridges). Adom Desktop ships a bundled seed and auto-pulls newer versions from this page.

• Clone the source: adom-wiki repo clone adom/adom-desktop-puppeteer-bridge
• Runtime lives in src/ (server.js, chrome.js, bridge.json, …); the release zip is src/ at zip-root.
• Maintainer skills (pup-bridge-dev, pup-bridge-publish) are source-only — in dev-skills/ + publish-skills/, not shipped in the pkg (per the Bridge SDK a pkg ships only user skills). Skill map:

• Ownership boundary: CLAUDE.md. Publish recipe: PUBLISHING.md. History: CHANGELOG.md.

Extend pup — add your own pup skill (third parties)

Built a skill that drives pup for a specific job (a site-specific scraper, a visual test flow, a domain widget)? You don't need write access here — surface it from this page with a breadcrumb:

1. Publish your skill to your own wiki page (see the adom-wiki / wiki-skillpack skills). Make it a normal user skill so pkg install drops it into a container's ~/.claude/skills.
2. Drop a breadcrumb on this page pointing at it:

   adom-wiki breadcrumb post adom/adom-desktop-puppeteer-bridge \
     --label "Your skill name — one-line what it does" \
     --target-url "https://wiki.adom.inc/<owner>/<your-slug>" \
     --category "skill"
   

   It's pending until the page owner approves it, then it shows in this page's Breadcrumbs tab.
3. Discovery is automatic: an agent working with pup can list related third-party skills with adom-wiki breadcrumb list adom/adom-desktop-puppeteer-bridge — approved breadcrumbs are how pup finds community skills that build on it.

Keep breadcrumbs on-topic (they genuinely extend pup / browser-driving); off-topic ones get rejected.

Related

• Bridge SDK guide — bridge.json schema, packaging, lifecycle
• KiCad bridge · Fusion 360 bridge
• Adom Desktop (parent app)

MIT licensed.