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
README.md+10−2@@ -9,8 +9,8 @@ task needs to BE the user. pup is the opposite trade: no borrowed identity, but real, disposable browser the AI owns end to end (open/close windows + tabs, navigate, screenshot, eval JS, record). Logged out by design, it's the safe, fully-drivable default for automation, testing, scraping public pages, and showing wiki pages; reach for nb/nbe only when you genuinely need the user's-real logins. pup drives the browser **already on the machine** (installed Chrome, else Microsoft Edge;-every Windows PC ships Edge), so the common case needs no download.+real logins. pup drives **Chrome for Testing**, the automation build (why: [docs/WHY-CFT.md](/blob/app/pup-bridge/docs/WHY-CFT.md));+pup installs and maintains it by itself, with the machine's installed Chrome/Edge as fallbacks. **The core goal: an AI-driven browser that can do everything it needs to for you - the best assistant in the world.** By default every pup window surfs on the shared durable **adom-you** profile, and every@@ -19,6 +19,14 @@ usernames and passwords on every site it has ever seen, which is what makes a tr AI browser possible. Isolated throwaway profiles exist for the cases that need them (logged-out testing, acting as another user), but they build nothing: adom-you is the default on purpose. +**pup drives Chrome for Testing (CfT), the build Google ships for automation.** Branded Chrome+fights automation in ways that matter here: the "controlled by automated test software" banner+blips over the window during real driving and cannot be suppressed, and Chrome 137 removed every+silent way to load pup's toolbar extension. CfT has none of those fights, pins a deterministic+version, and lets the Adom Pup toolbar ride every launch as a flag. The full technical record,+including what we tried and verified on branded Chrome, is in+[docs/WHY-CFT.md](/blob/app/pup-bridge/docs/WHY-CFT.md).+ > 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.
SKILL.md+1−1@@ -1,7 +1,7 @@ --- name: pup user-invocable: true-description: "Drive a browser on the user's desktop from the cloud — the Puppeteer 'pup' bridge (pup_* verbs via the adom-bridge-cli CLI). pup drives the browser ALREADY on the machine in a pup-managed DURABLE profile (logins/localStorage persist and are shared across pup windows; {isolated:true} for a throwaway) (installed Chrome, else Microsoft Edge — on Windows every PC has Edge, on macOS neither is guaranteed so a download may be needed), driven over CDP, in the BACKGROUND so it never disturbs the user; NOT the user's real signed-in profile (that's the Adom extension's nbrowser_* verbs), NOT headless (a real rendered window, so screenshots/recording are true-to-life). Chrome for Testing only as a last resort. Open/close windows + tabs, navigate, screenshot, eval JS, record. This is the START-HERE skill: the mental model + when-to-use + the skill map; deeper topics route to the sub-skills. For 'is it ready' use pup_readiness (not pup_status). Trigger words: pup, puppeteer, browser window, open in pup, open my app in pup, browser screenshot, browser eval, browser reload, visual debug, headful chrome, pup_open_window, pup_screenshot, pup_readiness, pup_prewarm, chrome for testing, open in browser, open my web app, show my app in the browser, preview my app, open the app I just built, view my app, open localhost, show my dev server, pup_login, log into a site in pup, autofill password, saved login, durable profile, isolated window."+description: "Drive a browser on the user's desktop from the cloud — the Puppeteer 'pup' bridge (pup_* verbs via the adom-bridge-cli CLI). pup drives Chrome for Testing (the automation build: no automation banner, deterministic version, toolbar extension rides the launch — see docs/WHY-CFT.md; installed Chrome/Edge are fallbacks) in a pup-managed DURABLE profile (logins/localStorage persist and are shared across pup windows; {isolated:true} for a throwaway), driven over CDP, in the BACKGROUND so it never disturbs the user; NOT the user's real signed-in profile (that's the Adom extension's nbrowser_* verbs), NOT headless (a real rendered window, so screenshots/recording are true-to-life). Chrome for Testing only as a last resort. Open/close windows + tabs, navigate, screenshot, eval JS, record. This is the START-HERE skill: the mental model + when-to-use + the skill map; deeper topics route to the sub-skills. For 'is it ready' use pup_readiness (not pup_status). Trigger words: pup, puppeteer, browser window, open in pup, open my app in pup, browser screenshot, browser eval, browser reload, visual debug, headful chrome, pup_open_window, pup_screenshot, pup_readiness, pup_prewarm, chrome for testing, open in browser, open my web app, show my app in the browser, preview my app, open the app I just built, view my app, open localhost, show my dev server, pup_login, log into a site in pup, autofill password, saved login, durable profile, isolated window." --- # Pup — browser control on the user's desktop (start here)
docs/WHY-CFT.mdadded+80@@ -0,0 +1,80 @@+# Why pup drives Chrome for Testing++Policy as of 2026-08-10 (pup 2.0.53+): **pup's driving browser is Chrome for Testing (CfT), not+branded Chrome or Edge.** This page is the technical record of why, because the policy has flipped+twice and the reasons deserve to outlive the people who remember them.++A short history: early pup was CfT-based. In mid-2026 the default flipped to "drive the browser+already on the machine" to make first runs instant (no ~160 MB download when a perfectly good+Chrome or Edge is already installed). Running that way in production surfaced the problems below,+and on 2026-08-10 the policy flipped back to CfT for good.++## 1. The automation banner you cannot turn off++The moment pup does real automation in branded Chrome, moving a synthetic cursor, filling a login+form, assisting with a captcha, Chrome asserts the infobar: **"Chrome is being controlled by+automated test software."** It blips in and out as automation starts and stops, reflowing the+viewport each time, and it is deliberately hard to suppress in the branded build: the classic+trick (stripping `--enable-automation` from the launch args) changes input and focus semantics,+and newer branded builds re-assert automation indicators when DevTools attaches regardless. Users+watched the banner flicker over their windows all day. CfT is the build Google ships FOR+automation: the banner is not fighting you there, and suppressing chrome-level test UI is+supported behavior rather than an arms race.++## 2. Extensions: branded Chrome closed every silent path (the forcing reason)++Branded Chrome 137 (mid-2025) **removed the `--load-extension` flag** specifically to stop+software from silently side-loading extensions. We verified the fallout live on branded 148+(2026-08-10), trying every route to auto-install the Adom Pup toolbar:++- The CDP replacement (`Extensions.loadUnpacked`) requires a `--remote-debugging-pipe` launch,+ which is incompatible with pup's detached-launch architecture (pup windows deliberately outlive+ the bridge process and are re-adopted over the port), **and** the install turned out to be+ session-scoped anyway: it does not persist into the profile.+- Driving `chrome://extensions` plus the native folder dialog works but puts a file dialog on the+ user's screen. Horrific, vetoed.+- The remaining branded paths are all user-visible or worse: a Web Store click per profile, or an+ enterprise force-install policy that brands the browser "managed by your organization".++CfT still honors `--load-extension`. So on CfT the toolbar is simply a **launch argument**: every+profile launch carries it, every window is born with the toolbar pinned, and there is no install+step in existence. This capability gap alone justifies the policy.++## 3. Version determinism++CfT is pinned to the exact build puppeteer expects (matched buildId) and **has no auto-updater**.+Branded Chrome updates itself underneath running profiles on Google's schedule, which means CDP+behavior can drift mid-session, and two pup windows opened an hour apart can be driving different+browser versions. Deterministic versions are what make pup's ralph tests reproducible and make a+CDP bug a fixable fact instead of a moving target. pup owns CfT's update cadence via its own+self-heal (src/chrome.js), which is exactly where that control belongs.++## 4. None of the consumer chrome++No first-run bubbles, no default-browser nagging, no profile-import prompts, no sign-in and sync+pressure, and no Finch field-trial experiments silently flipping browser behavior per machine.+Branded Chrome runs server-assigned experiments; CfT gives every machine the same browser.++## 5. Isolation from the user's own browser++A different binary means a different process tree: the user's real Chrome can update, crash, or be+closed without touching a single pup window, and pup's taskbar identity never tangles with their+browsing. Profiles were always pup-owned; CfT extends the separation to the binary itself.++## Known trade-offs, stated honestly++- **First-run download** (~160 MB) on machines without CfT cached. pup has detected, installed,+ and repaired CfT by itself since long before this policy (readiness self-heal).+- The window title and Task Manager say **"Google Chrome for Testing"**. The rendered window is+ otherwise identical.+- **No Widevine DRM**: protected video (streaming services) will not play in pup. Driving those is+ an nb/nbe job anyway, with the user's real browser and identity.+- Users who explicitly pin branded Chrome (`pup_use {browser:"chrome"}`) keep everything working+ except the toolbar extension and infobar suppression; pup tells them why when it matters.++## What did NOT change with the switch++Profiles, cookies, and logins live in pup's own userDataDirs, independent of the driving binary.+Repinning from branded Chrome to CfT changed nothing about the shared adom-you credential store,+window ownership, taskbar identity, or recovery; the same profile simply renders under the+automation build.