---
name: pup
user-invocable: true
description: "Control Puppeteer browser windows on the user's desktop via the adom-desktop CLI. Use for: opening/closing browser windows, reloading pages, taking screenshots, evaluating JS, flashing taskbar alerts, navigating URLs, checking errors, managing multi-session Chrome. Trigger words: pup, puppeteer, browser window, browser reload, browser screenshot, pup reload, pup screenshot, pup alert, browser debug, visual debug, open in browser, reload browser, flash taskbar, browser_reload, browser_alert_window, browser_open_window, browser_screenshot, browser_eval."
---

# Pup — Puppeteer Browser Control

Control Chrome browser windows on the user's desktop via the `adom-desktop` CLI.

## How to Run Commands

All `browser_*` commands are run via the `adom-desktop` CLI using Bash:

```bash
adom-desktop <command> '<json_args>'
```

**Examples:**
```bash
adom-desktop browser_reload '{"sessionId":"dart2"}'
adom-desktop browser_alert_window '{"sessionId":"dart2"}'
adom-desktop browser_screenshot '{"sessionId":"dart2"}'
adom-desktop browser_open_window '{"sessionId":"myapp","profile":"myapp","url":"http://localhost:3000"}'
adom-desktop browser_eval '{"sessionId":"dart2","expr":"document.title"}'
```

**IMPORTANT:** These are NOT MCP tools. They are Bash commands. Use the Bash tool to run them.

## Available Commands

### Session Management
| Command | Description | Required Args |
|---|---|---|
| `browser_open_window` | **Spawns a new pup window**. Only use when there isn't an existing session of that name. | `sessionId`, `profile`, `url` |
| `browser_close_window` | Close a specific session | `sessionId` |
| `browser_focus_window` | Bring window to foreground | `sessionId` (optional) |
| `browser_alert_window` | Flash taskbar icon (non-intrusive) | `sessionId` (optional) |
| `browser_switch_window` | Switch global active session | `sessionId` |
| `browser_list_windows` | List all open sessions | none |

### ⚠ Don't double-open windows — `browser_navigate` reuses, `browser_open_window` spawns

If a session already exists (verify with `browser_list_windows` or `browser_list_tabs`), point an existing tab at a new URL with **`browser_navigate`** — passing `tabId` if you want to be explicit:

```bash
adom-desktop browser_navigate '{"sessionId":"chip-fetcher","tabId":"tab-1","url":"<new-url>"}'
```

Using `browser_open_window` against a session that's already alive **spawns a second physical pup window** with the same title. The new tab is tracked but the old window is orphaned — the user sees two windows showing the same content. Verified painful 2026-05-04: opened a chip-fetcher dashboard verification tab while the original UL Pro detail tab was still active; user noticed the duplicate before I did. Cleanup required `desktop_close_window` and a tracked-tab marker dance.

**Decision tree:**
- Need a new session entirely (different `sessionId`) → `browser_open_window`.
- Need to reuse an existing session's tab → `browser_navigate` (with `tabId` if multiple tabs).
- Need a second tab in the same session → `browser_open_tab` (not `browser_open_window`).

### ⚠ Cross-sessionId duplicates — same app, two windows

The double-open trap above catches *same-sessionId* re-opens. There's a second flavor that catches you across conversation boundaries: **a previous session left a pup window open under one `sessionId`, and the new conversation opens the same app under a different `sessionId`** — adom-desktop happily creates a second window because the keys differ. The user sees two pup windows showing the same content.

**Always run `browser_status '{}'` before `browser_open_window`** at the start of a new conversation, especially after a context compaction. Look for any session whose URL maps to the app you're about to open. Reuse it (`browser_navigate`) instead of creating a peer.

Verified 2026-05-07 with chipsmith: an earlier session had `sessionId: cs-v2` open at `…/proxy/8872/`. New conversation opened `sessionId: chipsmith` at the same port — two windows for the same chip. User noticed the duplicate first.

When closing a duplicate, prefer the OLDER one (lower `cb=` timestamp in URL); the newer one usually has the working state you just built up.

### Page Commands (all accept optional `sessionId`)
| Command | Description | Key Args |
|---|---|---|
| `browser_reload` | Reload page + clear error log | `sessionId` |
| `browser_navigate` | Navigate to new URL | `url`, `sessionId` |
| `browser_screenshot` | Capture page screenshot (lossless PNG) | `sessionId`, `maxWidth`, `fullPage` |
| `browser_eval` | Evaluate JS expression in page | `expr`, `sessionId` |
| `browser_errors` | Get console/page errors | `sessionId` |
| `browser_wait` | Wait for content to settle | `ms` (default 3000) |
| `browser_status` | Check all sessions | none |
| `browser_close` | Close ALL sessions | none |

## Common Patterns

### Reload + Alert (after code changes)
```bash
adom-desktop browser_reload '{"sessionId":"dart2"}' && \
adom-desktop browser_alert_window '{"sessionId":"dart2"}'
```

### Debug Loop
1. Edit code
2. `browser_reload`
3. `browser_wait` (3-5s for 3D tiles)
4. `browser_screenshot`
5. `browser_errors`
6. Analyze, repeat if needed

### Check Connectivity
```bash
adom-desktop ping
```

## Pick ONE surface — respect the user's window-mode preference

Hydrogen stores a per-session **window mode** preference: `webview` (default) or `pup`. Check it before opening a window:

```bash
adom-cli hydrogen probe  # → { ..., "window_mode": "webview" | "pup" }
```

- **`webview`** → open as a Hydrogen webview tab (`webview open-or-refresh`)
- **`pup`** → open via Adom Desktop (`pup browser_open_window`). If Adom Desktop isn't reachable, fall back to webview and warn.

**Never open the same content in both at once.** User
feedback 2026-04-26: *"why the fuck did you open something in pup
and some stuff in webview. pick one or the other."*

Two costs of dual-opening:
1. Two copies of the page → user sees changes in one but not the
   other → "why doesn't my upload show up?" or "which one is
   real?".
2. Background WS / polling traffic doubles, which makes the
   Cloudflare-blipping problem worse.

When window-mode is `webview`, the decision rule:

| Use case | Surface | Why |
|---|---|---|
| Automated test, screenshot, eval, ralph loop, scripted multi-step demo | **pup** (even in webview mode — this is automation, not user-facing) | scriptable; doesn't compete with the user's tabs; pup's `browser_eval` works on every tab |
| Showing the user a finished result they should look at | **Hydrogen webview tab** (`adom-cli hydrogen webview open-or-refresh`) | the tab persists in their workspace; they can interact normally |
| Both at once for the SAME content | **don't** | pick whichever role the situation calls for and stick with it |

When window-mode is `pup`, everything goes through Adom Desktop — including user-facing results.

If you've opened the user's Hydrogen tab for a dashboard / viewer,
use **that** tab for screenshots too via `adom-cli hydrogen
screenshot panel --name "<tab-name>"`. Don't ALSO open a pup
window of the same URL. If you started in pup for testing and the
user wants to see the final state, route them to a Hydrogen tab
once and close the pup window.

Memory rule still applies for testing: pup is the testing surface,
NOT Hydrogen. The point of THIS rule is: don't open both for the
SAME content at the SAME time.

## Multi-URL workflows — ONE window, MANY tabs

When you'd open more than one URL for the same user task (vendor
fetch, multi-doc review, compare-pages workflows), put them in
**tabs of one window**, not separate windows. User feedback
2026-04-26: *"when you make all those pup windows, they clutter
up the user's desktop, so you should open all of those as tabs
in one pup window."*

```bash
# 1) Create the window with the first URL.
adom-desktop browser_open_window '{
  "sessionId":"my-task","profile":"my-task",
  "url":"https://first.example.com"
}'

# 2) Add the rest as tabs in the SAME session.
adom-desktop browser_open_tab '{"sessionId":"my-task","url":"https://second.example.com"}'
adom-desktop browser_open_tab '{"sessionId":"my-task","url":"https://third.example.com"}'

# 3) Activate a specific tab when you want to screenshot or eval it.
adom-desktop browser_switch_tab '{"sessionId":"my-task","tabId":"tab-2"}'
adom-desktop browser_screenshot   '{"sessionId":"my-task","maxWidth":1500}'
adom-desktop browser_eval         '{"sessionId":"my-task","expr":"document.title"}'
```

`browser_open_tab` lives alongside the documented `browser_*`
verbs. Same JSON-args convention; same `sessionId` semantics.

Pick a stable `profile` name across runs of the same task so the
cookie jar persists — the user logs in once and reuses for 12+
months. Cross-vendor cookie blending is fine because cookies are
per-domain.

## Verify what you opened — `"ok": true` is not enough

`browser_open_window` / `browser_open_tab` returns `"ok": true` as
soon as the navigation starts, NOT when the page actually
rendered useful content. Always sanity-check the result:

```bash
# Title check — fastest. 404s, anti-bot blocks, and login walls
# all change the title.
adom-desktop browser_eval '{"sessionId":"my-task","expr":"document.title"}'

# Screenshot — slowest, most thorough. Use when title isn't
# discriminating (e.g. SPA that updates title async).
adom-desktop browser_screenshot '{"sessionId":"my-task"}'
```

**Never blindly template a part number into a vendor URL pattern
without verifying the page exists.** The cost of a 404 you didn't
catch is the user spotting it instead. (Real example: shipped a
manufacturer-search-URL pattern that 404'd on `ti.com/product/`
and `nxp.com/` for parts those vendors don't make. Using a
`google.com/search?q=…` link routes through Google's resolver
and gets a real product hit on the first result.)

## Key Rules

- **Always pass `sessionId`** — never use `'{}'` as args. The default targets the *active* session which may not be what you want.
- **`adom-desktop browser_<cmd> <json>` — never `adom-desktop pup <cmd> --flags`.** There is no `pup` subcommand at the top level; that pattern fails with "Invalid JSON args".
- **No semicolons in `browser_eval`** — use comma operator or IIFE instead.
- **Sessions persist** — IndexedDB, cookies, localStorage survive restarts. Profile name is the persistence key.
- **Each session = independent Chrome window** — crash-isolated. Multiple tabs share one session and one cookie jar.
- **Never kill Chrome broadly** — use `browser_close_window` for specific sessions.
- **Always reload + alert after browser-facing code changes** — the user expects to see updates immediately.

## Full Reference

For detailed docs (profiles, sleep/wake recovery, troubleshooting, first-time setup), see `~/.claude/skills/adom/guides/pup.md`.