app
Pup - the AI's own browser
Public Made by Adomby adom
pup gives your AI a real browser on your desktop that it drives completely, in the background, signed in as you: windows that never jump in front of your work, one shared profile that learns your logins, and every window labeled on the taskbar with its AI thread's name.
← Commit history
Docs for launch: new README and nine feature guides with real screenshots
14 files changed
+468−50
docs/dashboard.md+45docs/how-pup-works.md+61docs/img/dashboard.pngdocs/img/jumplist.pngdocs/img/settings.pngdocs/img/taskbar-tiles.pngdocs/install-and-footprint.md+43docs/logins-and-cards.md+39docs/open-source-and-contributing.md+73docs/pup-vs-native-browser.md+28docs/screenshots-and-recording.md+32docs/settings.md+87docs/taskbar-and-jump-lists.md+49page.json+11−50docs/dashboard.mdadded+45@@ -0,0 +1,45 @@+# The dashboard++The pup dashboard is a live page, served by pup itself, that shows every pup window on your desktop, which AI thread owns it, and why its taskbar button looks the way it does. It opens in a pup window of its own.++++## Opening it++- Click the **pup** card in Hydrogen's dock bar.+- Right-click any pup taskbar tile and choose **Open pup dashboard**.+- Ask your AI: "open your dashboard in pup".++## The header++The top line is a one-glance summary: how many windows and tabs are open, how many taskbar buttons they make, how many windows surf on the shared adom-you profile, and **MATCH** when every taskbar button wears exactly the icon pup intended (it turns red with a reason when one does not). The buttons on the right open help, Settings, refresh every badge, flash every pup button so you can find them, clear those flashes, and close the dashboard.++## Say it++You never need the dashboard's buttons, because everything pup does is something you can ask an AI for. The Say it panel lists ready phrases, "open my wiki page in pup", "record a clip of this page in pup", "show me the logged-out view in pup", with a copy button and a send button that starts a new AI thread with that phrase. **Play the demo** runs a five-step, two-minute guided tour.++## Status chips++Three chips show that the pieces are healthy: the browser build is installed, Adom Bridge is answering, and the profile is adom-you. A grey or red chip names what is wrong.++## The taskbar mirror++The TASKBAR row draws pup's buttons the way Windows shows them right now: each thread's tile with its favicon badge and a status dot. It is the quickest way to see the taskbar of a machine you are not sitting at.++## The window map++Below the mirror, every window is grouped under its AI thread. Each window row shows:++- whether it is in the background or foreground, and buttons to bring it forward or send it back;+- **surfing as adom-you**, or the profile it uses instead and why;+- the thread that owns it;+- for Adom wiki windows, whether this is the signed-in or the public view;+- its age, and every tab with the active one marked.++Each window carries a **how this icon was chosen** note: which tab supplied the favicon, where pup got it (the page's own icon link, the site's favicon file, or the generic glyph), and what painted it. A wrong icon is never a mystery.++The filter boxes narrow the map to one AI thread or to windows whose address, name or thread matches. The footer shows pup's health loops ticking, for anyone diagnosing a problem.++## Settings++The gear opens the [Settings](settings.md) window.
docs/how-pup-works.mdadded+61@@ -0,0 +1,61 @@+# How pup works++This guide explains what pup is on your machine, how your AI's commands reach a browser window, and the rules pup follows so it never fights you for your screen or your windows.++## One signed program, managed for you++pup is a single Windows program, `adom-pup-bridge.exe`, about 8 MB, signed by Adom Industries, Inc. Everything it needs is built into that one file: the browser extensions it loads, its dashboard, its icons and fonts, and its catalog of 97 commands. There is no Node, no npm, and nothing to install by hand.++[Adom Bridge](https://wiki.adom.inc/adom/adom-bridge) (ab) owns pup's lifecycle. It downloads pup the first time an AI asks for a browser, checks the download against its published sha256, starts it, restarts it if it stops, and moves it to each new version. pup listens only on your own machine (127.0.0.1), so Windows never asks you to let it through the firewall.++```+your AI (container or desktop)+ │ adom-bridge --ai-thread "my-thread" pup_open_window {...}+ ▼+Adom Bridge on your desktop ── starts, updates and talks to ──▶ adom-pup-bridge.exe+ │+ ▼+ a real browser window, driven+ through pup's own extension+```++## The browser: real, visible, and driven from the inside++pup opens real browser windows, not a hidden headless engine, so screenshots and recordings show exactly what a person would see. It uses its own Chrome build so it can load its extension and stay on a known version; until that build has downloaded on a new machine, pup uses your installed Chrome or Edge. The [why pup uses its own browser build](WHY-CFT.md) record has the full reasoning.++pup drives each window through its own extension running inside the browser, which polls pup for commands and runs them. This is the **extension lane**, and it is the only way pup opens windows by default. There is no remote debugging port, which matters: vendor sites such as st.com, Mouser and Arrow detect a debug port and block the page, and through the extension lane they load normally. The extension lane handles trusted mouse and keyboard input (including inside cross-site frames), element and full-page screenshots, downloads, fetching files with the page's cookies, and HTTP Basic-Auth from the vault. An older debugging lane still exists for the rare feature that needs it, and it is off unless a person turns it on for a machine.++## Windows are born behind your work++pup's first rule is that it never takes your screen. A new window is caught while it is still invisible, given its identity, and placed at the bottom of the window stack in the same instant it first appears. It never activates, never steals your keyboard, and never covers what you are doing. A release cannot ship unless a measured test passes: it samples the top of the screen twice a second while pup does a cold start, navigations and new windows, and fails if a pup window is on top in even one sample.++A pup window comes to the front only when an AI asks for that with a stated reason. pup shows that reason as a caption, so you always know why a window appeared. Your own clicks (a jump list task, a toolbar button) raise windows immediately, without a warning about your own click.++## One shared profile that learns your logins++Every pup window surfs on one durable profile called **adom-you**. Cookies, logins and site data carry across all pup windows and all AI threads, so once you sign into a site in any pup window, every pup window is signed in. Each open and navigate tells the AI where it **landed**: the final address, whether it is a sign-in page, and whether the profile is already signed in there. So an AI never asks you to sign in where you already are.++A window can use a different profile when a task needs one. `isolated:true` creates a throwaway profile that is deleted with its window, for logged-out tests or acting as another user, and it requires the AI to state why. Each profile gets its own browser, so windows never mix cookie jars.++## Addressing: the thread name is the handle++An AI never tracks window ids. Its thread name (`--ai-thread`) is the key: its first open creates its window, later opens add tabs, and every other command with no id goes to that window. `pup_my_windows` lists everything the thread owns. A thread that needs several windows labels them with `window`. Windows belong to their thread: another thread cannot navigate or close them without taking over with a reason, and pup logs every takeover.++## Restarts, upgrades and crashes: what comes back++pup restarts when Adom Bridge updates it, and its browser can crash or your machine can sleep. pup keeps a small file per window (its tabs and addresses) so it can put things back, under three rules:++- **A window is restored only when its browser is gone.** If pup ended the browser itself (an upgrade or a restart), if the browser crashed, or if it was already gone when pup started, pup reopens its windows in the background with all their tabs.+- **Your close is final.** If the browser is running and your window is not in it, you closed it, and pup forgets it. That holds even when you close a window during the seconds pup itself is restarting, and closing a thread's taskbar icon while windows are being restored cancels that thread's remaining restores.+- **A window that is still on screen is never thrown away.** If pup restarts while the extension is briefly unreachable, it waits and re-adopts the same window instead of forgetting it or opening a duplicate.++Before pup starts a browser on a profile, it waits until no earlier process is still using that profile's files, so a restart never leaves Chrome complaining that something went wrong opening your profile.++## What pup cleans up by itself++- **Taskbar identities.** When a window closes, its taskbar registration goes with it, and a sweep a minute after each start removes any left over by older versions.+- **Browser downloads.** Superseded browser builds and leftover partial downloads are deleted a minute after each start, never while a download is in progress and never the build in use.+- **Throwaway profiles.** Isolated profiles are deleted with their window and swept at start.+- **Screenshots and recordings** are kept for a limited time and size.++See [Install size and footprint](install-and-footprint.md) for the measured numbers.
docs/img/dashboard.pngadded⋯ 1 unchanged line ⋯
docs/img/jumplist.pngadded⋯ 1 unchanged line ⋯
docs/img/settings.pngadded⋯ 1 unchanged line ⋯
docs/img/taskbar-tiles.pngadded⋯ 1 unchanged line ⋯
docs/install-and-footprint.mdadded+43@@ -0,0 +1,43 @@+# Install size and footprint++What pup puts on your machine, measured, what cleans itself up, and how to remove it.++## What you download++| piece | size | when |+|---|---|---|+| pup itself (`adom-pup-bridge.exe`, signed) | 4 MB download, 8.4 MB on disk | The first time an AI asks for a browser. Adom Bridge fetches it and checks its sha256. |+| pup's browser build | 200 MB download, 428 MB unpacked | Once, in the background, right after install. Until it lands, pup uses your installed Chrome or Edge, so the first window does not wait. |+| AI skills (in a container) | under 1 MB | `adom-wiki pkg install adom/pup-bridge` |++On a brand-new Windows machine (measured 2026-09-23): pup installed in 1 second, was usable at once on the system Edge, finished the browser download in 6 seconds and unpacking in 3, and opened its first window 24 seconds after a bare install.++## What grows with use++Measured on a desktop used heavily for a month (2026-10-03):++| location | size | what it is |+|---|---|---|+| `%LOCALAPPDATA%\Adom Bridge\bridges-cache\puppeteer` | 15 MB | the program, recent screenshots |+| `~/.cache/puppeteer` | 428 MB | the browser build, exactly one copy |+| `~/.adom/pup-profiles/adom-you` | 1.1 GB | the shared profile: cookies, logins, site data and cache for every site you use in pup |+| `~/.adom/pup-profiles` (all) | 4.0 GB | adom-you plus 20 older named profiles |+| `~/.adom/pup-logs` | 3 MB | the log, capped at 2 MB with one rotation |+| `~/.adom/pup-vault.bin` | under 1 MB | the encrypted vault |++The adom-you profile grows like any browser profile: mostly the cache of the sites you visit.++## What cleans itself up++- **Browser builds.** A minute after each start pup deletes superseded browser builds and leftover partial downloads. It keeps only the build in use, never touches one a running browser uses, and waits for any download in progress. Before this (2.0.677), every update kept the old 410 MB build forever.+- **Throwaway profiles.** Profiles made for `isolated:true` windows are deleted with their window and swept at each start.+- **Taskbar registrations.** Each window's taskbar identity is removed when it closes, and leftovers are swept at start.+- **Screenshots and recordings** are kept for a limited time and size.++**What does not clean itself up yet: named profiles.** A profile created for one task (a `profile:"name"` open) stays until it is removed, which is how the measured desktop collected 20 of them and 2.9 GB. To reclaim that space, ask your AI to "reap pup's idle profiles". It runs `pup_reap_profiles {"dryRun":true}` to list profiles idle for 14 days, then the same without `dryRun` to delete them. It never deletes adom-you, a profile that is open, or one needed to restore a saved window.++## Removing pup++- `pup_uninstall {"confirm":true}` removes pup's profiles and saved windows, its staged extensions, its taskbar icons and every taskbar identity it registered. It keeps your saved logins; remove those with `credential_delete`.+- Adom Bridge's `bridge_uninstall {"name":"puppeteer"}` removes the program.+- The browser build in `~/.cache/puppeteer` can be deleted by hand afterwards.
docs/logins-and-cards.mdadded+39@@ -0,0 +1,39 @@+# Logins, passwords and cards++pup keeps its own password manager so your AI can sign into sites as you, in the background, without the browser's save-password bubbles and autofill dropdowns that are built for a person at the keyboard. This guide covers how logins are captured, filled and protected, and how pup handles payment cards.++## Where secrets live++Passwords are stored in one file per Windows user, `~/.adom/pup-vault.bin`, encrypted with Windows' own data protection (DPAPI), so only your Windows account on this machine can read it. Card numbers live in the same kind of store. No pup command ever returns a password or card number to a cloud AI, and pup never writes one to a log.++## Captured as you sign in++When you sign into a site in a pup window, pup saves the username and password as the form is sent. The next command the AI runs tells it that a login was captured. Because every pup window shares the adom-you profile, each login you make anywhere makes pup better at signing in everywhere. Turn capturing off in [Settings](settings.md) if you prefer.++## Filled on return, sent only with a reason++When a pup window reaches a sign-in page for a site the vault knows, pup fills the saved username and password in the background. It never sends the form by itself. An AI must call `pup_login` with `submit:true` and a `submitReason` explaining why this site is the right one; pup echoes the real address back, so a look-alike or redirected domain is caught before a password goes anywhere. A login that matches several accounts asks which one.++Every open and navigate also reports where the window **landed**: whether it is a sign-in page, whether a login is offered, and whether the profile is already signed in. So an AI never asks you to sign in where you already are.++## Bringing in the logins you already have++- **From Chrome or Edge.** `pup_import_browser_logins` copies your saved passwords from your own Chrome, Edge or Brave on this machine into pup's vault, after one consent dialog and one Windows administrator prompt. It runs only on your desktop, never from a cloud AI.+- **From your other desktop.** `pup_vault_sync` merges the logins of two of your desktops in both directions, newest wins. Passwords travel pup to pup and never pass through an AI.+- **By hand.** `credential_set` stores one login; `pup_credentials` lists what is stored as host and username only; `credential_delete` removes one.++## Google accounts++`pup_google_accounts` lists the Google accounts found in your browsers and in pup's vault, marked work or personal, and whether pup is already signed in to each. `pup_google_signin` signs in as a named account hands-free. When Google asks for a second step, it hands back the options and the exact call to finish with the code, and it never restarts a sign-in that is waiting for a code.++## HTTP Basic-Auth++Some vendor and intranet pages ask for a username and password in a browser dialog instead of a web form. pup answers those from the vault through its extension, with no dialog. When the vault has no login for that site, the AI gets a clear `no_credential` error naming the host, instead of a page that seems to hang.++## Seeing a password++`pup_credential_reveal` shows one saved login to a program running on your own desktop, and only after you click a consent notice on your screen. One site per call, never in bulk, and refused outright for cloud AIs.++## Payment cards++`pup_card_set` stores a card under a nickname. pup checks the number, expiry and security code, and no command ever returns them afterward. An AI should ask you for card details and never copy them from a page. `pup_fill_card` types a saved card into a checkout page, including the payment fields that live in Stripe-style frames, without the digits ever reaching the AI. It answers only with which fields it filled. Every fill waits for your approval on a desktop notice that names the merchant.
docs/open-source-and-contributing.mdadded+73@@ -0,0 +1,73 @@+# Open source: code and contributing++pup is open source under the MIT license. Its complete source is in this page's **Files** tab, and changes come back as pull requests on this page. This guide shows how the code is organized, how to build and test it, how to add a feature, and how to send it back.++## How the code is organized++pup is one Rust workspace in `rust/`, built into a single Windows program. Twelve crates, each with one job:++| crate | lines | job |+|---|---|---|+| `bridge` | 210 | The program's entry point: start the HTTP server on 127.0.0.1, route commands, run the start-up tasks. |+| `verbs` | 8,100 | Every command (`pup_*`). Each is a function of (context, caller, arguments) that returns a reply. |+| `browser` | 970 | Which browser to drive, fetching pup's browser build, launch arguments, and staging the extensions. |+| `session` | 160 | The window and tab model and the small file kept per window for recovery. |+| `identity` | 660 | Taskbar identity: names, the thread tile drawing, favicon badges, jump list contents. No OS calls. |+| `vault` | 370 | Logins and payment cards: matching, validation, the encrypted store's format. |+| `dashboard` | 450 | Every page pup serves that is not a command: `/status`, `/health`, the dashboard and its assets. |+| `cdp` | 360 | The client for the older debugging lane. |+| `core` | 390 | Shared types: settings, the reply envelope, caller identity, logging. |+| `host` | 150 | The operating-system interface, as traits and nothing else. |+| `host-win` | 570 | The Windows implementation of `host`, and the only crate allowed to call Windows directly. |+| `host-mac` | 50 | The macOS implementation, in progress. |++The rule that keeps the port possible: every Windows call lives in `host-win` behind a trait in `host`. `tools/check-borders.sh` fails the build if a Windows or macOS API name appears anywhere else. The Mac port is one crate: implement `host-mac`.++The browser extensions that pup loads into its windows live in `src/extension*/` as plain JavaScript and are built into the program, along with the dashboard (`rust/dashboard/assets/`) and the command catalog.++## Build and test++You need Rust with the Windows target. From Linux or WSL, install mingw-w64 for the linker; on Windows, use the stable toolchain.++```bash+rustup target add x86_64-pc-windows-gnu+python3 tools/gen-assets.py # embed extensions, dashboard and the command catalog+tools/check-borders.sh # Windows calls only in host-win+cd rust && cargo test --workspace # unit tests, on any OS+cargo build --release --target x86_64-pc-windows-gnu+# -> rust/target/x86_64-pc-windows-gnu/release/adom-pup-bridge.exe+```++## Add a feature++Most features are a new command or a change to one. To add `pup_something`:++1. Write the handler in the fitting file under `rust/verbs/src/` (`tabs.rs`, `input.rs`, `extras.rs`, ...): a function of `(ctx, caller, args)` that returns `ok(json!({...}))` or `err(code, message, hint)`.+2. Route it in `dispatch` in `rust/verbs/src/lib.rs` and add its name to `PHASE1_VERBS`.+3. Describe it for AIs: add an entry to `_STUBS` in `tools/gen-assets.py` with a summary, inputs, an example and a hint. The build stops if a routed command has no description, and the same list becomes both `pup_describe` and the manifest Adom Bridge reads, so they cannot drift apart.+4. If it needs the operating system, add a method to a trait in `host`, implement it in `host-win`, and give `host-mac` a stub.+5. Add a test, and run the build and tests above.++Good first changes: a clearer hint on a command that confused your AI, a new jump list task, a Settings row with a better explanation, a faster screenshot path. Open the folder in Claude Code and describe the change you want; the code's comments record why things are the way they are, often with the date and the problem that caused them.++## Send it back++Open a pull request on this page with the files you changed:++```bash+adom-wiki pr create adom/pup-bridge --title "Add pup_something" --body-file why.md \+ --files rust/verbs/src/extras.rs rust/verbs/src/lib.rs tools/gen-assets.py+```++Or start a thread in the **Issues** tab first if you want to talk the idea through.++## What happens to your change++Adom maintainers review it, then build, sign and test every release before anyone gets it:++- **Foreground proof.** A cold start, navigations and new windows while the screen is sampled twice a second; it fails if a pup window is ever on top.+- **Smoke test.** Every everyday command, end to end, through Adom Bridge on a real desktop.+- **Parity.** 56 recorded reply shapes replayed and compared.+- **Jump list test.** Every jump list task fired exactly as Windows fires it, with its effect checked in the window.++A release goes first to the insiders tier on Adom's own desktops, and only reaches everyone when a person approves it in their own words.
docs/pup-vs-native-browser.mdadded+28@@ -0,0 +1,28 @@+# pup or native browser?++Adom gives an AI two ways to use a browser on your desktop. They solve different problems, and a good AI picks the right one for each task.++| | pup | native browser (nb) |+|---|---|---|+| whose browser | pup's own browser, its own windows | your own Chrome or Edge, your own windows |+| identity | the shared adom-you profile, which learns your logins over time | your real profile: your cookies, your single sign-on, your saved passwords |+| where windows appear | behind your work, labeled with the AI thread's name | wherever your browser puts them |+| control | total: open, close, navigate, type, click inside any frame, screenshot, record, run scripts | drives the page you are on, through the Adom browser extension |+| best for | testing your app, screenshots, scraping, recording, sign-ins pup has learned, anything the AI does on its own | handing a page to you, sites only your own browser is signed into, anything you will keep using yourself |++## Why pup exists++A normal browser is built for a person. It asks you to save a password, pick a saved login, click a cookie banner, bring a window forward. An AI driving your own browser keeps tripping over that machinery, and it competes with you for the same windows and tabs.++pup is a browser built for the AI. It does all of that silently, in windows you can ignore, and it never touches the tabs you are using. Because every pup window shares the adom-you profile, logins you make in pup accumulate, so pup can sign into more of your sites over time. And because pup drives its browser through its own extension rather than a debugging port, vendor sites that block automation (st.com, Mouser, Arrow) load normally.++## Why native browser exists++Some things only your own browser has: the single sign-on session at your company, a site you signed into years ago and never in pup, a page you want to keep reading yourself. For those, an AI drives your real browser through the Adom browser extension's `nbrowser_*` commands, which is a separate bridge.++## How to ask++- "open my app in pup", "screenshot this in pup", "log me into mouser in pup": pup.+- "open this in my browser", "show it to me in Chrome": native browser.++When in doubt, an AI uses pup: it is safe to run while you work and leaves your own browser alone.
docs/screenshots-and-recording.mdadded+32@@ -0,0 +1,32 @@+# Screenshots and recording++pup windows are real rendered browser windows, so what an AI captures is exactly what you would see, even while the window sits behind your work.++## Screenshots++| command | captures |+|---|---|+| `pup_screenshot {}` | The visible part of the thread's active tab, sized for an AI to read. Add `fullPage:true` for the whole page. |+| `pup_screenshot_element {"selector":"..."}` | One element, found by selector or by its visible text, scrolled into view and cropped to it. Add `closest` to grab the card around a piece of text. |+| `pup_screenshot_full_res {}` | The same at full resolution, not reduced, for saving to disk. It can be too large for an AI to read. |++A whole-page capture covers pages that scroll as a whole. Pages that scroll inside a panel (many web apps) come back as the visible area with a hint to capture the panel by element or to scroll it instead.++Every image reply carries the path on your desktop plus a copy sized for an AI to read (at most 1568 pixels on a side), and Adom Bridge copies that image into the AI's container by itself, so the AI can open it at once. Each reply also says which window, tab, address and title it captured, and refuses if the capture would show a different window than the one asked for.++A background window can look frozen in a screenshot, with a paused video or a still animation. That is the browser saving power on a window you cannot see, not a hang. For a window that must keep rendering while hidden (recording it, or a live display), an AI opens it with `highFps:true`. That boost is leased, 20 minutes by default and at most 120, and falls back automatically so it never drains a laptop battery.++## Recording++`pup_record_start {}` and `pup_record_stop {}` record the thread's window to an MP4 through Adom Bridge's native recorder, with hardware video encoding. `pup_record_status` reports takes in progress, and a stop that is still encoding says so and finishes in the background. For a whole-desktop recording with system sound, Adom Bridge's own `desktop_record_start` is the right tool.++Convert a recording for sharing with ffmpeg:++```bash+ffmpeg -i take.mp4 -vf "scale=1280:-2" -c:v libx264 -crf 26 -c:a aac share.mp4 # smaller MP4+ffmpeg -i take.mp4 -vf "fps=12,scale=800:-1" loop.gif # silent looping GIF+```++## Annotate++Annotate puts a drawing layer over a page: pen, arrows, boxes and text. Start it from a tile's jump list (Annotate this page), from the pen in pup's browser toolbar, with Alt+Shift+A, or by an AI calling `pup_annotate`. When you click Done, the marked-up region is captured, copied to your clipboard, and sent to the AI thread that owns the window, with a thin caption naming the thread, page and time. The drawing stays visible, so the AI's next screenshot shows it too.
docs/settings.mdadded+87@@ -0,0 +1,87 @@+# Settings++pup's Settings window opens from the gear on the [dashboard](dashboard.md). Every row explains itself, shows its default, and applies immediately: no restart. Settings are saved per machine in `~/.adom/pup-settings.json`. Anything here can also be changed by asking your AI, which calls `pup_configure` with the setting's name, for example `{"overlaySize":"66"}`.++++The defaults below are what every Adom user starts with.++## Taskbar identity++| setting | default | what it does |+|---|---|---|+| Identity mode (`taskbarMode`) | tiles | **tiles**: one taskbar button per AI thread showing the thread's name. **aumid**: one button per window with a pup icon for the kind of page. **plain**: no pup branding; windows stack under the stock browser button. The window shows all six combinations as a live matrix drawn by the same code that draws the real icons; click a row to switch. |+| Overlay badges (`overlayBadges`) | on | Paint the active tab's favicon in the button's corner. |+| Badge size (`overlaySize`) | 75 | 50, 66, 75 or 100 percent of full size. Smaller keeps the thread name's bottom line readable. |+| Grouping (`taskbarGrouping`) | split | aumid mode only: one button per window, or grouped by kind. |+| Icon style (`aumidIconStyle`) | category | aumid mode only: one pup icon for everything, or a different icon per kind of page. |++See [Taskbar identity and jump lists](taskbar-and-jump-lists.md) for what each mode looks like.++## Jump lists++| setting | default | what it does |+|---|---|---|+| Right-click menu (`jumpLists`) | on | Show pup's tasks when you right-click a pup button. |+| Wiki view tasks (`jlViewTasks`) | on | Add Switch to logged-in view and Switch to public view on Adom wiki windows. |+| Close all windows task (`jlCloseAll`) | on | Add Close ALL Adom Pup windows. |+| Open dashboard task (`jlDashboard`) | on | Add Open pup dashboard. |+| Annotate this page task (`jlAnnotate`) | on | Add Annotate this page. |+| Start Menu anchor (`aumidShortcut`) | off | Add a Start Menu shortcut per live window so the menu opens on the first right-click on every Windows build. Off keeps your Start Menu clean. |++## Annotate and capture++| setting | default | what it does |+|---|---|---|+| Caption bar on captures (`annCaptionBar`) | on | Add a thin strip under each annotation capture naming the thread, page and time, so any AI you paste it into knows where it came from. |+| Adom toolbar in Chrome (`toolbarExtension`) | on | pup's buttons in the browser toolbar: annotate, snip, switch view, dashboard, owner, close. |+| Snip hotkey (`tbSnipHotkey`) | on | Alt+Shift+A starts annotating the current pup window. |+| Corner pencil (`tbFloatyPencil`) | off | A small pencil in a page's top-right corner that starts annotating. Off because the corner can overlap buttons in some sites' headers. |+| Pencil hit area (`floatyHitPx`) | 24 | The size in pixels of the invisible corner target that reveals the pencil. |++## Activity and foreground++| setting | default | what it does |+|---|---|---|+| Activity signal (`taskbarActivity`) | progress | Show a progress strip on a button while an AI is driving that window, flash it instead, or show nothing. |+| Windows attention flash (`winAttentionFlash`) | off | Windows lights a button when a window asks for the foreground and is refused. Off: pup creates new windows without asking, so nothing lights up. On: each new pup window you were not looking at stays lit until you click it. |+| Caption on AI foreground (`fgCaption`) | on | When an AI brings a window to your screen, show its stated reason as a caption. |+| Minimum caption time (`fgCaptionMs`) | 3500 | How long that caption stays, in milliseconds. |+| Not-by-Adom caption (`notMineCaption`) | off | Caption it when a window comes forward by itself (a page script, the browser) and pup did not do it. |++## Logins++| setting | default | what it does |+|---|---|---|+| Auto-fill saved logins (`autoLogin`) | on | Fill a saved username and password when a matching sign-in page loads, in the background. Sending the form always needs the AI to state why that site is the right one. |+| Capture logins to the vault (`captureLogins`) | on | Save the username and password when you sign into a site in a pup window. |+| Import logins | button | Import your saved passwords from Chrome or Edge on this machine, after one consent and one Windows prompt. |++More in [Logins, passwords and cards](logins-and-cards.md).++## In-page identity++| setting | default | what it does |+|---|---|---|+| Floating owner chip (`ownerChip`) | on | A small chip in the bottom-left of each page naming the thread that owns the window and its profile. You can click through it. |+| ai-thread tag in the title (`titleTag`) | off | Append the thread name to the window title. Off because many pages manage their own titles. |+| Thread name prefixed to the title (`titlePrefix`) | off | Put the thread name first in the window title. |++## Recovery and safety++| setting | default | what it does |+|---|---|---|+| Sleep and crash recovery (`sleepRecovery`) | on | After the laptop wakes or the browser dies, bring every pup window back at its last page, signed in. It never brings back a window you closed. See [How pup works](how-pup-works.md#restarts-upgrades-and-crashes-what-comes-back). |+| Issue-report hints (`reportIssues`) | on | Invite AIs to file an issue on this page when a pup command misbehaves. |+| Minimal-touch mode (`minimalTouch`) | on | A safety switch from an old browser-freeze investigation: pup only opens windows and drives the pages in them. The per-feature settings above override it, so it rarely changes anything now. Leave it on. |++## Settings with no row in the window++A few settings are for maintainers and are changed only through `pup_configure`:++| setting | default | what it does |+|---|---|---|+| `cdpLane` | off | Allow the older debugging lane on this machine for the rare feature that needs it. |+| `idleBrowserQuitMin` | 10 | Minutes before an idle browser with no windows is closed. |+| `consumerBrands` | on | Present pup's browser as the installed Chrome version to sites, so they do not treat it as a test build. |+| `fgWatch` | on | For 20 seconds after a background open, put a window back if something pulls it forward. |
docs/taskbar-and-jump-lists.mdadded+49@@ -0,0 +1,49 @@+# Taskbar identity and jump lists++pup labels every window on the Windows taskbar so you can tell at a glance which AI thread owns it and what it is showing. This guide covers the default look, the alternatives, the right-click menu, and the one setting that changes how that menu opens.++++## Thread tiles (the default)++Each AI thread gets one taskbar button whose icon is the thread's name, drawn on the Adom teal tile, bottom-left, in a heavy grotesk face. All windows of that thread group under that one button, and the button's title is the thread name. The name wraps onto two lines on a hyphen or space, keeps a minimum size, and is shortened rather than shrunk to nothing, so even long names stay readable.++pup draws the tile itself, inside its own program, at every size Windows asks for (16 to 256 pixels). Each size is drawn at four times its resolution and averaged down, so the letters sit at their exact positions with smooth edges instead of being snapped to whole pixels. The tile is stamped onto the window before the window first appears, so a button never starts as a plain browser icon and changes a moment later.++## The favicon badge++The badge in the button's top-right corner is the active tab's own favicon, placed on a small card that turns light when the favicon is dark, so dark logos such as GitHub's stay visible. It follows the active tab, so switching tabs updates it. When a page has no favicon, pup draws a neutral globe (or a document mark for PDFs) and tries again once the page settles. The badge is drawn at 75 percent of full size by default so it does not cover the thread name's bottom line; Settings offers 50, 66, 75 and 100 percent.++## Six display modes++The look is one choice with three options, crossed with badges on or off:++| mode | buttons | icon |+|---|---|---|+| tiles + badge (default) | one per AI thread | the thread name tile, with the page's favicon |+| tiles | one per AI thread | the thread name tile, no badge |+| aumid + badge | one per window, or grouped by kind | a pup icon for the kind of page (wiki signed in, wiki public, an Adom app, the open web, mixed), with the favicon |+| aumid | same | the kind-of-page icon, no badge |+| plain + badge | all pup windows stack under the stock browser button | the browser's own icon, with the favicon |+| plain | same | nothing that marks it as pup |++Switch in [Settings](settings.md) by clicking a row of the matrix, or ask your AI to change `taskbarMode`. A switch re-labels every open window at once. The window you are actively using keeps its old button until you look away, because rebuilding a button means briefly hiding the window, and pup will not blink the window you are working in.++## Jump lists: the right-click menu++++Right-click a pup tile and its jump list offers:++- **Annotate this page**: draw on the page with a pen, arrows, boxes or text. When you finish, the marked-up capture is copied to your clipboard and sent to the AI thread that owns the window.+- **Open pup dashboard**: the live map of every window ([The dashboard](dashboard.md)).+- **Close ALL Adom Pup windows**: every pup window, from every thread, closed for good.+- On Adom wiki windows, **Switch to logged-in view** and **Switch to public view** flip the same window between what you see and what the public sees.++Each task calls pup's own signed program directly. Your click counts as you, so it can act on any thread's window without a takeover, and a raise for your click comes with no warning toast.++## The first right-click and the Start Menu anchor++On some Windows builds the jump list of a new pup button only opens on the second right-click: the first one flashes and closes. Windows loads a button's menu late when the button's identity has no Start Menu shortcut, and the only reliable fix is a visible shortcut. Measured on 2026-09-23: with no shortcut, a Windows 11 25H2 machine at build 26200.9457 needed two right-clicks every time, while a machine on build 26200.9550 opened the menu on the first click.++The **Start Menu anchor** setting (`aumidShortcut`, off by default) adds one shortcut per live window in an "Adom Pup" Start Menu folder and fixes the first click on every build. It is off by default because most people never open a jump list and a Start Menu entry per thread is clutter. The shortcuts are removed when their windows close.
page.json+11−50@@ -2,14 +2,15 @@ "schema_version": 1, "type": "app", "slug": "pup-bridge",- "title": "Pup - Puppeteer Bridge",- "brief": "pup is the AI's own browser: a real, full Chrome on the user's desktop that the AI fully controls (a sandbox, not the user's signed-in browser). Rides Bridge; pup_* verbs open windows and tabs, navigate, screenshot, and eval JS.",- "version": "2.0.692",+ "title": "Pup - the AI's own browser",+ "brief": "pup gives your AI a real browser on your desktop that it drives completely, in the background, signed in as you: windows that never jump in front of your work, one shared profile that learns your logins, and every window labeled on the taskbar with its AI thread's name.",+ "version": "2.0.686", "tags": [ "skills", "pup", "puppeteer", "browser",+ "ab", "adom-bridge", "bridge", "pup-bridge"@@ -87,7 +88,7 @@ "install_hint": "", "version_cmd": "" },- "readme": "# pup: the Puppeteer bridge\n\n**pup is the AI's own browser: a real, full Chrome/Edge window on the user's desktop that the AI drives\nwith complete programmatic control, but a _sandbox_.** It runs in a fresh, isolated profile that is\nnever the user's real signed-in browser, and opens in the **background by default** so it never disrupts\nthem. That trade is exactly why pup exists alongside **nb / nbe** (the native browser and its extension):\nnb/nbe drive the user's _real_ browser, their cookies, SSO, saved logins, their identity, for when a\ntask needs to BE the user. pup is the opposite trade: no borrowed identity, but **total control**, a\nreal, disposable browser the AI owns end to end (open/close windows + tabs, navigate, screenshot, eval\nJS, record). Logged out by design, it's the safe, fully-drivable default for automation, testing,\nscraping public pages, and showing wiki pages; reach for nb/nbe only when you genuinely need the user's\nreal logins. pup drives the browser **already on the machine** (installed Chrome, else Microsoft Edge;\nevery Windows PC ships Edge), so the common case needs no download.\n\n**The core goal: an AI-driven browser that can do everything it needs to for you - the best assistant\nin the world.** By default every pup window surfs on the shared durable **adom-you** profile, and every\nlogin made there enriches a shared credential store. Over time that store lets pup automatically enter\nusernames and passwords on every site it has ever seen, which is what makes a truly self-sufficient\nAI browser possible. Isolated throwaway profiles exist for the cases that need them (logged-out\ntesting, acting as another user), but they build nothing: adom-you is the default on purpose.\n\n> To drive the user's **real, signed-in** Chrome/Edge (their cookies, SSO, saved logins), that's the\n> **Adom browser extension's `nbrowser_*` verbs**, a separate bridge, not pup.\n\nCanonical page: **https://wiki.adom.inc/adom/pup-bridge**\n\n## Install vs Download, which is which (and why the version numbers differ)\n\nThe page header shows **two** things, for two different places. Most people need only the first.\n\n| On the page | What it is | Who runs it | You usually… |\n|---|---|---|---|\n| **Install**, `adom-wiki pkg install …` | The **AI skill pack**, the `pup` skills that teach a cloud/container AI how to drive the bridge. Docs only, no runtime; drops into `~/.claude/skills` + `~/.codex/skills`. | your **container / cloud AI** | **run this** (or it arrives via `sync_skills`) |\n| **Download for your machine**, `adom-bridge-puppeteer-v<ver>.zip` | The **bridge runtime**, the actual Node program (browser detection + driving) that runs on the desktop. | **Bridge**, on the user's PC | **do nothing**, Bridge **auto-installs & auto-updates** it; the manual download is only for offline/manual installs |\n\n**Why two different version numbers?** They're independent artifacts. The **Install (pkg)** version bumps\nwhenever the *skills/docs* change (often). The **Download (runtime)** version bumps only when the *bridge\ncode* changes (rarely). So it's normal to see e.g. Install `v1.8.27` and Download `v1.8.20`, nothing is\nout of sync; they just version on their own clocks.\n\n*(There's also a third copy, the runtime is **bundled inside the Bridge installer** as a first-run\nseed, superseded by a newer cache copy via `updateManifestUrl`. You never touch it directly.)*\n\n## Use it\n\n```bash\n# everyday: open + screenshot. Opens in the BACKGROUND automatically, no need to lower it,\n# and it's fully drivable/screenshottable while hidden, so the user is never interrupted.\nadom-bridge-cli pup_open_window '{\"sessionId\":\"myapp-web\",\"owner\":\"myapp\",\"url\":\"http://localhost:3000\"}'\nadom-bridge-cli pup_screenshot '{\"sessionId\":\"myapp-web\"}'\n\n# readiness (use pup_readiness, NOT pup_status). On a box with Chrome or Edge this is\n# instantly {ready:true} with no download. Only a box with no Chromium at all fetches Chrome for\n# Testing in the background, poll until ready, then open.\nadom-bridge-cli pup_readiness '{}' # → {ready:true, browserKind:\"chrome\"|\"edge\"|...}\n```\n\n- **Task-prefix your `sessionId` + pass `owner`**, sessions are shared across every AI thread on the\n desktop; that lets pup protect your window from another thread navigating it away.\n- **`foreground:true` is the only way to show a window**, sizing/positioning does not foreground it.\n\nFull everyday usage (tabs, recording, window ownership, cold-start playbook) is in the `pup` skill\n(`SKILL.md`).\n\n## Window-type taskbar icons: read a pup window at a glance\n\n\n\nEvery pup window's **taskbar icon states what kind of thing it is showing**. All five share the same\ndrawing (the teal Adom tile carrying a solid browser window) and differ only in the window's\n*content*: a monochrome glyph on the 24x24 Adom house grid, per the brand icon law (single color,\nno gradients, no emoji):\n\n| Icon | Window content | Means |\n|---|---|---|\n|  | open book | **Adom wiki, public view**: logged out, what the world sees |\n|  | book + person | **Adom wiki, signed in**: the user's logged-in view (private source, drafts, owner cards) |\n|  | the Adom mark | **An Adom app**: localhost or a cloud-slug proxy URL |\n|  | globe | **The web**: any other site (ti.com, digikey, ...) |\n|  | two panes | **Mixed**: the window's tabs span more than one category |\n\n- The category is derived from **all tabs** in the window; it updates **live** (add a digikey tab\n to a wiki window and the icon flips to *mixed* within about a second).\n- The **overlay badge** riding the icon's corner is separate and sacred: it is the **active tab's\n own favicon**, so you always see which site you are looking at. In grouped-taskbar mode it shows\n window/tab counters instead.\n- The **tab title** carries the same login signal in text: a solid dot (`● Logged in`) or hollow dot\n (`○ Public`) leads the title of every Adom wiki tab.\n- Under the hood, each window's identity (icon, name, Alt-Tab entry) rides a per-session Windows\n AppUserModelID that **carries the category**: the only way Win11 allows a taskbar tile to change\n live. Grouped mode instead keeps one stable, pinnable `Adom.Pup` identity.\n\n### Using pup's icons in your own tool (HD browser picker, launchers, menus)\n\nIf you are building a surface that offers \"open a pup window\" (a browser picker, a launcher tile, a\nmenu item), **use pup's real icon, not a stand-in.** The canonical, self-describing asset set lives\nin the wiki repo at [`assets/pup-icons/`](assets/pup-icons/), in three formats:\n\n- **SVG** (`pup-cat-*.svg`), scalable, the right choice for a web/Tauri picker.\n- **PNG** (`pup-cat-*-{32,48,128,256,512}.png`), raster fallback / retina.\n- **ICO** (`pup-cat-*.ico`), Windows multi-size, for taskbar/shortcut contexts (256px frame is\n PNG-compressed, per the Vista+ rule, so it never renders as a generic document).\n\n**For a launcher/picker item, use `pup-cat-default`**, the neutral teal browser-window tile. It is\nwhat a pup window's taskbar button looks like before its content is known, so the picker previews the\nreal result. The five category icons above (`wiki`, `wiki-in`, `app`, `web`, `mixed`) are for\n*showing an existing window's kind*, not for a generic \"open pup\" action.\n\nFetch any asset from the wiki without cloning:\n\n```\nhttps://wiki.adom.inc/api/v1/pages/pup-bridge/files/assets/pup-icons/pup-cat-default.svg\nhttps://wiki.adom.inc/api/v1/pages/pup-bridge/files/assets/pup-icons/manifest.json\n```\n\n[`assets/pup-icons/manifest.json`](assets/pup-icons/manifest.json) is machine-readable: it maps each\nicon id to its meaning, its glyph, and its file in every format, and names\n`recommended_for_launcher` so a tool can pick the right one programmatically. Brand rule if you ever\nredraw one: teal tile `#00b8b0` + dark-teal window body `#003d40` + a single-color teal glyph, no\ngradients, shadows, or emoji.\n\n## Real windows, one per type\n\nFull windows as pup opens them (title bar, tabs, page). Note the tab title glyphs on the wiki pair\nand the signed-in header on the second:\n\n**Adom wiki, PUBLIC** (tab: `○ Public`, page header shows Login):\n\n\n\n**Adom wiki, SIGNED IN** (tab: `● Logged in`, page header shows the user's name):\n\n\n\n**An Adom app** (here: the shotlog viewer on a cloud slug URL):\n\n\n\n**The web** (ti.com):\n\n\n\n**Mixed** (a digikey tab and a wiki tab in one window):\n\n\n\n## Overlay badges: the corner of the taskbar icon\n\n\n\nThe base icon states the window TYPE; the small overlay riding its lower-right corner carries\nLIVE detail, composited exactly like this:\n\n| Overlay | When | What it tells you |\n|---|---|---|\n| the active tab's **favicon** on a dark rounded plate | split mode, page serves a favicon | which site the active tab is on, at a glance |\n| a **count badge** (white digit, dark plate) | split mode, 2+ tabs and no favicon | how many tabs the window holds |\n| the **dual counter** (dark = windows, teal = total tabs) | grouped mode | how much is stacked under the single Adom Pup button |\n\nThe overlay never carries branding or state that belongs to the base icon: it is live per-window\ndetail only, and the favicon always wins the slot when one exists.\n\n## The Adom wiki: logged-in vs public view, and the taskbar toggle\n\npup can show any Adom wiki page from **two viewpoints**, and both the AI and the user can switch:\n\n- **Public (default)**: a fresh logged-out profile: exactly what the world sees. Use it to verify\n what a publish actually exposed.\n- **Signed in**: `pup_open_window {..., wikiView:\"authed\"}` routes to a reserved persistent\n profile whose cookie jar holds the user's ~30-day SSO session. One login serves **every** AI\n thread on the machine. First use returns `wikiLoginNeeded:true`; the user signs in once, in that\n window.\n\n**The user can flip a wiki window themselves**: right-click its taskbar button: the jump list\ncarries **\"Adom wiki: switch to logged-in view\"** (or \"...switch to public view\"). Clicking it\nrelaunches that same window under the other cookie jar, brings it to the front, and shows an\non-screen caption while it works (\"Switching to the logged-in view of the Adom wiki\", then\n\"Adom wiki: now the LOGGED-IN view (Their Name)\"). The AI-side equivalent is the\n`pup_wiki_set_view` verb, which exists for that jump-list click: AI threads should pass\n`wikiView` on open instead.\n\n## One session, one OS window\n\nEvery pup session gets its **own OS window**, even when sessions share a browser profile (as all\nsigned-in wiki windows share the authed cookie jar). This is what makes per-window identity\npossible: a window's title belongs to its active tab, so windows that share sessions as tabs\ncannot be found, branded, flashed, or given jump lists individually. Sharing a profile shares the\ncookies; it never merges windows.\n\n## Recording\n\npup can record what it drives, a **single tab/window** or the **whole desktop**, straight from the\ncloud, with no HUD and no need to bring the window forward.\n\n\n\n*Above: a GIF preview of a real `pup_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.*\n\n### High-FPS windows: recording something the user is not looking at\n\npup windows are backgrounded by design, and Chrome throttles a window that is occluded, so\nrecording one normally yields a **1-2 fps** video. pup can disable Chrome's power-saving to keep a\nwindow painting at full rate, but a window in that mode can never idle down (three of them once\ndrained a laptop overnight, wiki issue #14).\n\nSo it is **opt-in and leased**:\n\n- **Default** is Chrome's own power behaviour. Normal windows throttle when occluded and cost\n nothing in the background. Right for driving, scraping and screenshots.\n- **`pup_open_window {highFps:true}`** renders at full rate while occluded, for background\n recording. It holds a lease (default 20 min), and **an active recording holds that lease open\n indefinitely, so a take is never cut off**. On lapse the window is *downgraded* back to normal\n power by relaunching with its tabs intact, never closed.\n- **`pup_highfps_extend {sessionId, minutes}`** negotiates more time up front.\n\n**Full details, defaults, activity signals, and rules of thumb: [RECORDING.md](RECORDING.md).**\n\n### Two recorders, pick by what you're capturing\n\n| Verb pair | Captures | How it works under the hood |\n|---|---|---|\n| **`pup_record_start` / `pup_record_stop`** | ONE pup **tab/window**, the page content | **CDP `Page.startScreencast`** (JPEG frames, up to ~50 fps) piped to **ffmpeg**, encoded to **VP9** in real time → one `.webm`. Tab-scoped at the protocol level, so it captures the exact tab even in the **background**, no `getDisplayMedia`, no picker, no foreground. |\n| **`desktop_record_start` / `desktop_record_stop`** | the WHOLE **desktop** (multiple apps, dialogs) | Screen capture via **MediaRecorder** → one `.webm`; ffmpeg remuxes it to stamp a proper Duration. |\n\n```bash\nadom-bridge-cli pup_record_start '{\"sessionId\":\"demo-web\"}' # → { recordingId }\n# ...drive the scene: navigate, click, type, scroll...\nadom-bridge-cli pup_record_stop '{\"sessionId\":\"demo-web\",\"recordingId\":\"<id>\"}' # → { path: \"...webm\" }\n```\n\n**ffmpeg** is required for recording. The bridge auto-detects it (a WinGet `Gyan.FFmpeg` install, PATH,\nor common dirs) and re-checks **lazily on `record_start`**, so if it's missing you can\n`winget install Gyan.FFmpeg` and just retry, no bridge restart. `pup_record_status` /\n`pup_record_list` (and the `desktop_record_*` equivalents) report in-flight and finished captures.\n\n### Formats, one native format, easy conversion\n\npup records to **one** format natively: **WebM (VP9)**, for both recorders. It doesn't offer a format\nswitch; instead, convert with the bundled ffmpeg when you need MP4 or GIF. Real numbers from the ≈8.6 s\ndemo above (1264×705):\n\n| Format | Codec | Size | How you get it | Best for | Watch out for |\n|---|---|---|---|---|---|\n| **WebM** ([view](https://wiki.adom.inc/api/v1/pages/pup-bridge/files/pup-recording-demo.webm)) | VP9 | **143 KB** | pup's **native** output, no step | Chrome/Edge/Firefox, small + high quality, the source of truth | Older **Safari**, PowerPoint, and some chat apps don't accept VP9/WebM |\n| **MP4** ([view](https://wiki.adom.inc/api/v1/pages/pup-bridge/files/pup-recording-demo.mp4)) | H.264 | **135 KB** | transcode (below) | **Universal**, Safari, iOS, PowerPoint, Slack/Teams, \"send it to anyone\" | H.264 needs **even width & height**, odd dims (like 705) fail at frame 0; the `scale` filter forces even |\n| **GIF** ([view](https://wiki.adom.inc/api/v1/pages/pup-bridge/files/pup-recording-demo.gif)) |, | **192 KB** | transcode (below) | Auto-playing, looping **inline preview** in any README/chat/GitHub, no player, no click (like the one above) | No audio, capped colors, and it balloons fast at higher fps/resolution/length, keep it short + downscaled |\n\n```bash\n# → MP4 (H.264, universal). The scale filter forces EVEN dimensions (H.264 rejects odd w/h → frame 0).\nffmpeg -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\n\n# → GIF (silent, looping inline preview). Palette pass keeps colors clean; drop fps/scale to shrink.\nffmpeg -i rec.webm -vf \"fps=12,scale=640:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse\" rec.gif\n```\n\n**Rule of thumb:** keep **WebM** for archiving + web embeds; make an **MP4** the moment a human on Safari/\nPowerPoint/phone needs it; make a short **GIF** only for an inline auto-play preview.\n\n## Source & development\n\nThis bridge is cloud-owned here (extracted from `adom-bridge/plugins/puppeteer`, mirroring the\nkicad/fusion bridges). Bridge ships a bundled seed and auto-pulls newer versions from this page.\n\n- Clone the source: `adom-wiki repo clone adom/pup-bridge`\n- Runtime lives in `src/` (`server.js`, `chrome.js`, `bridge.json`, …); the release zip is `src/` at zip-root.\n- **Maintainer skills** (`pup-bridge-dev`, `pup-bridge-publish`) are **source-only**, in `dev-skills/` +\n `publish-skills/`, not shipped in the pkg (per the Bridge SDK a pkg ships only user skills). Skill map:\n\n| Skill | Ships in pkg? | What it's for |\n|---|---|---|\n| `pup` (root SKILL.md) | ✅ user | Start here, mental model (CDP-launched fresh process of the installed browser, rendered-but-backgrounded), when-vs-extension, quick start |\n| `pup-windows-sessions-tabs` | ✅ user | sessionIds, window ownership (don't steal another thread's window), background-vs-foreground, many tabs in one window |\n| `pup-screenshots-recording` | ✅ user | Screenshots (full-page/full-res) + recording; driving/verifying tricky pages (shadow DOM, nested scroll) |\n| `pup-browsers-and-chrome` | ✅ user | Browser detection/launch, `pup_use`, installing Chrome/CfT (incl. UAC-notify), readiness, cold-start errors |\n| `pup-adom-wiki` | ✅ user | Driving + verifying `wiki.adom.inc` pages in pup (view/screenshot/verify; the login situation) |\n| `pup-bridge-dev` / `pup-bridge-publish` | ❌ source-only | MAINTAINERS: bridge internals + the publish/release recipe (in `dev-skills/`/`publish-skills/`, not shipped) |\n- Ownership boundary: `CLAUDE.md`. Publish recipe: `PUBLISHING.md`. History: `CHANGELOG.md`.\n\n## Extend pup, add your own pup skill (third parties)\n\nBuilt a skill that drives pup for a specific job (a site-specific scraper, a visual test flow, a\ndomain widget)? You don't need write access here, surface it from this page with a **breadcrumb**:\n\n1. **Publish your skill** to your own wiki page (see the `adom-wiki` / `wiki-skillpack` skills). Make it a\n normal user skill so `pkg install` drops it into a container's `~/.claude/skills`.\n2. **Drop a breadcrumb on this page** pointing at it:\n ```bash\n adom-wiki breadcrumb post adom/pup-bridge \\\n --label \"Your skill name, one-line what it does\" \\\n --target-url \"https://wiki.adom.inc/<owner>/<your-slug>\" \\\n --category \"skill\"\n ```\n It's **pending until the page owner approves it**, then it shows in this page's **Breadcrumbs** tab.\n3. **Discovery is automatic:** an agent working with pup can list related third-party skills with\n `adom-wiki breadcrumb list adom/pup-bridge`, approved breadcrumbs are how pup finds\n community skills that build on it.\n\nKeep breadcrumbs on-topic (they genuinely extend pup / browser-driving); off-topic ones get rejected.\n\n## Related\n\n- [Bridge SDK guide](https://wiki.adom.inc/adom/adom-bridge-sdk), `bridge.json` schema, packaging, lifecycle\n- [KiCad bridge](https://wiki.adom.inc/adom/kicad-bridge) · [Fusion 360 bridge](https://wiki.adom.inc/adom/fusion-bridge)\n- [Bridge (parent app)](https://wiki.adom.inc/adom/adom-bridge)\n\nMIT licensed.\n",+ "readme": "# pup: the AI's own browser\n\n**pup gives your AI a real browser on your desktop that it drives completely, in the background, signed in as you.** It opens real Chrome windows that never jump in front of your work, keeps one shared profile where your logins accumulate, fills saved passwords for the AI, and labels every window on the taskbar with the name of the AI thread that owns it. Ask your AI to \"open it in pup\" and it does.\n\npup is one small signed Windows program (about 8 MB) that [Adom Bridge](https://wiki.adom.inc/adom/adom-bridge) installs and keeps up to date for you. This page holds its source, its AI skills, and the guides below. It is open source under the MIT license.\n\n## Install\n\nOn your desktop there is nothing to install by hand. Adom Bridge (bundled with Hydrogen) downloads pup the first time an AI asks for a browser, and updates it on its own. In an AI container, install the skills so the AI knows how to use it:\n\n```bash\nadom-wiki pkg install adom/pup-bridge\n```\n\n## Quick start\n\nYour AI addresses its windows by its own thread name, so there are no ids to track:\n\n```bash\nadom-bridge --ai-thread \"my-thread\" pup_open_window '{\"url\":\"https://example.com\"}' # a real window, behind your work\nadom-bridge --ai-thread \"my-thread\" pup_screenshot '{}' # the image lands in the container\nadom-bridge --ai-thread \"my-thread\" pup_navigate '{\"url\":\"https://wiki.adom.inc\"}' # same window, next page\nadom-bridge --ai-thread \"my-thread\" pup_my_windows '{}' # everything this thread has open\n```\n\nOr just say it: \"open my app in pup\", \"screenshot this site in pup\", \"record a clip of this page in pup\".\n\n## Every window wears its thread's name\n\n\n\nEach AI thread gets one taskbar button, and its icon is the thread's name drawn on the Adom teal tile. All of that thread's windows group under it, so the taskbar reads as a list of your threads, not a row of identical browser icons. The small badge in the corner is the active tab's own favicon: above, spice-compare is on a Texas Instruments page, nsf-proposal on the Adom wiki, parts-search on GitHub, and my-app on an ordinary site. pup stamps the name before the window first appears, so a button never starts out as a plain browser icon and changes later. Details, the five other display modes, and how to switch: [Taskbar identity and jump lists](docs/taskbar-and-jump-lists.md).\n\n## Right-click a tile for pup's tasks\n\n\n\nRight-clicking a pup tile opens its jump list. Every window offers Annotate this page (draw on the page and the marked-up capture goes to the owning AI thread), Open pup dashboard, and Close ALL Adom Pup windows. An Adom wiki window adds Switch to logged-in view and Switch to public view, which flips the same window between what you see and what the public sees, the fastest way to check what a publish exposes. Each task runs pup's own signed program directly, with no script in between.\n\n## The dashboard shows every window, live\n\n\n\nThe dashboard lists every pup window grouped by the AI thread that owns it, with each tab, whether it is signed in, which profile it surfs on, and a mirror of the taskbar buttons. Every icon carries a \"how this icon was chosen\" note, so a wrong icon is never a mystery. The Say it panel lists phrases you can paste into any AI thread, and the gear opens Settings. Open it from the dock bar card, the jump list, or by asking your AI for \"your dashboard in pup\". Full tour: [The dashboard](docs/dashboard.md).\n\n## Feature guides\n\n| guide | what it covers |\n|---|---|\n| [How pup works](docs/how-pup-works.md) | One signed exe, the extension lane, windows born behind your work, the shared adom-you profile, restarts and upgrades, and what is never brought back. |\n| [Taskbar identity and jump lists](docs/taskbar-and-jump-lists.md) | Thread tiles, favicon badges, the six display modes, jump list tasks, and the Start Menu anchor setting. |\n| [The dashboard](docs/dashboard.md) | The live window map, the taskbar mirror, icon explanations, Say it, and the toolbar buttons. |\n| [Settings](docs/settings.md) | Every setting in the Settings window, its default, and what it changes. |\n| [Logins, passwords and cards](docs/logins-and-cards.md) | pup's own vault, auto-capture and fill, reason-gated sign-in, importing from Chrome or Edge, Google accounts, Basic-Auth, cards. |\n| [Screenshots and recording](docs/screenshots-and-recording.md) | Window, element and full-page screenshots, recording with sound, and annotate. |\n| [Install size and footprint](docs/install-and-footprint.md) | What lands on disk, measured, what cleans itself up, and how to remove pup completely. |\n| [pup or native browser?](docs/pup-vs-native-browser.md) | When the AI should use pup, when it should drive your own browser, and why both exist. |\n| [Open source: code and contributing](docs/open-source-and-contributing.md) | How the code is organized, how to build and test it, how to add a feature, and how to send it back. |\n| [Why pup uses its own browser build](docs/WHY-CFT.md) | The dated record of that decision. |\n\n## Talk to the AI\n\n| you want | say |\n|---|---|\n| see your app | \"open my app in pup\" |\n| check a page | \"screenshot this site in pup\" |\n| a clip | \"record a clip of this page in pup\" |\n| the public view of a wiki page | \"show me the logged-out view in pup\" |\n| sign in | \"log me into mouser in pup\" |\n| everything open | \"what do you have open in pup?\" |\n| the dashboard | \"open your dashboard in pup\" |\n\n## Dependencies\n\n| dependency | required? | why |\n|---|---|---|\n| Windows 10 or 11 | yes | pup is a native Windows program. A Mac port is in progress; Macs run the older build for now. |\n| Adom Bridge 2.1 or later | yes | It installs, updates and starts pup, and carries every command from your AI to it. Hydrogen includes it. |\n| A browser build | automatic | pup downloads its own Chrome build once (about 200 MB, 428 MB unpacked) and uses your installed Chrome or Edge until that finishes. |\n\n## Skills\n\nThe skills teach any AI how to use pup well. The main `pup` skill is the start; the others load when a task needs them.\n\n| skill | purpose |\n|---|---|\n| `pup` | Start here: the model, addressing by thread name, the everyday verbs, and the rules. |\n| `pup-windows-sessions-tabs` | Windows, tabs, ownership and the zero-id forms. |\n| `pup-screenshots-recording` | Every screenshot and recording option, and tricky pages. |\n| `pup-credentials` | The vault, sign-in, imports and Google accounts. |\n| `pup-lanes` | How pup drives a window and the rules that keep your closes final. |\n| `pup-taskbar-states` | The six taskbar display modes, exactly. |\n| `pup-settings` | Every setting, behavior by behavior. |\n| `pup-adom-wiki` | Viewing wiki pages signed in or as the public. |\n| `pup-vendor-login` | Signing into vendor portals. |\n| `pup-browsers-and-chrome` | Readiness, the browser build and cold starts (maintainer detail). |\n\n## Open source\n\nThe complete source is in this page's **Files** tab: one Rust workspace of twelve crates, with every Windows call kept in a single crate so the Mac port only implements one interface. [Open source: code and contributing](docs/open-source-and-contributing.md) walks through the layout, the build, the tests and the release gates, and how to send a change back as a pull request on this page. Issues and ideas are welcome in the **Issues** tab.\n", "author": "John Lauer <[email protected]>", "visibility": { "public": true@@ -100,15 +101,15 @@ "created_at": "2026-05-28T05:28:43.991Z", "skills": [], "author_name": "John Lauer",- "description": "The pup SKILL PACK: the AI skills that teach a cloud/container AI how to drive the Bridge Puppeteer (pup) bridge (pup_* verbs): the everyday `pup` skill plus focused sub-skills for windows/sessions/tabs, screenshots+recording, browsers+Chrome install, and driving the Adom wiki. Installs into ~/.claude/skills + ~/.codex/skills. DOCS ONLY — this is NOT the bridge runtime. The bridge itself (the Node program that drives the browser) runs on the DESKTOP: Adom Bridge bundles it and auto-installs/updates it, and it's published separately on the Releases tab as adom-bridge-puppeteer-v<ver>.zip. The pkg version is kept in lockstep with the Release version so the page's max version row always carries BOTH a pkg tarball (skills) and a runtime zip (bridge) — a skills-only or runtime-only bump on the top row breaks constraint installs. TL;DR: pkg install = the skills for your AI; the bridge = the Release zip, which Adom Bridge manages for you.",+ "description": "The pup SKILL PACK, the AI skills that teach a cloud/container AI how to drive the Bridge Puppeteer (pup) bridge (pup_* verbs): the everyday `pup` skill plus focused sub-skills for windows/sessions/tabs, screenshots+recording, browsers+Chrome install, and driving the Adom wiki. Installs into ~/.claude/skills + ~/.codex/skills. DOCS ONLY, this is NOT the bridge runtime. The bridge itself (the Node program that drives the browser) runs on the DESKTOP: Bridge bundles it and auto-installs/updates it, and it's published separately on the Releases tab as adom-bridge-puppeteer-v<ver>.zip. So the pkg version (skills, bumps often) and the Release version (runtime, bumps rarely) differ on purpose. TL;DR: pkg install = the skills for your AI; the bridge = the Release zip, which Bridge manages for you.", "keywords": [+ "ab", "pup", "puppeteer", "browser", "adom-bridge", "bridge",- "skills",- "pup-bridge"+ "skills" ], "files": [ "SKILL.md",@@ -116,22 +117,10 @@ "skills/pup-screenshots-recording/SKILL.md", "skills/pup-browsers-and-chrome/SKILL.md", "skills/pup-adom-wiki/SKILL.md",- "skills/pup-vendor-login/SKILL.md",- "skills/pup-lanes/SKILL.md",- "skills/pup-settings/SKILL.md",- "skills/pup-credentials/SKILL.md",- "skills/pup-progress/SKILL.md",- "skills/pup-taskbar-states/SKILL.md", "install.sh", "uninstall.sh", "README.md",- "package.json",- "tools/pup-dashboard",- "dockbar.json",- "docs/img/dock-pup.svg",- "hero-v9.png",- "skills/pup-why-cft/SKILL.md",- "skills/pup-taskbar-progress/SKILL.md"+ "package.json" ], "scripts": { "install": "./install.sh",@@ -140,33 +129,5 @@ "dependencies": { "adom/adom-bridge": "^2.0.0" },- "org": "adom",- "contributors": [- "Kyle Bergstedt <[email protected]>",- "Colby Knox"- ],- "agent_permissions": {- "allow_bash": [- "pup-bridge"- ],- "allow": [- "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."- ],- "soft_deny": [- "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 OS keychain.",- "pup-bridge pup_raise_os_window and pup_assisted_click take over the user's screen and keyboard focus. Native input lands wherever focus is at that instant.",- "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 desktop but in the background.",- "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."- ]- },- "changelog": "An idle-browser cycle now counts saved windows still waiting to be re-adopted, so it can no longer end a browser right after a restart while its windows are on screen (one of John's windows did not come back, 2026-10-03). Plus everything in 2.0.691."-}+ "org": "adom"+}