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

# 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 keeps a request open to pup and runs each command the moment pup hands it over (about a tenth of a second, since 2.0.693). 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 detect a debug port and block the page, and through the extension lane they load normally. (A few sites, such as Mouser and Arrow, also run separate bot walls that can refuse any automated browser on some days; measured 2026-10-03, TI, DigiKey and LCSC loaded while Mouser and Arrow were walled.) 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.