---
name: pup-settings
description: "The complete reference to pup's behavior on macOS: every Settings toggle and the feature behind it, the toolbar extension family, annotate/capture, foreground etiquette, the credential vault (auto-capture + autofill), in-page identity, and recovery/safety. Read to know exactly what pup does on the user's machine and how to change any of it. Change settings live with pup_configure {key:value} or the dashboard gear (Settings dialog)."
---

# pup Settings & features: the complete behavior reference

Every knob pup exposes, what it does, its default, and how to flip it. **Change any of these live**
with `pup_configure {<key>:"on"|"off"|<value>}` (no restart), or the gear icon on the pup dashboard
(`http://127.0.0.1:<port>/dashboard`). Settings persist in `~/.adom/pup-settings.json`. Defaults
below are what a fresh Adom user gets.

## Windows-only keys (stored, but nothing changes on a Mac)

macOS has no per-window taskbar button, so the Windows line's taskbar keys do nothing here:
`taskbarMode`, `taskbarGrouping`, `aumidIconStyle`, `overlayBadges`, `overlaySize`, `aumidIcons`,
`threadTiles`, `aumidShortcut`, `jumpLists` and the `jl*` jump-list tasks, `taskbarActivity` (reads
`off`) and `winAttentionFlash`. `pup_configure` stores them and reports `taskbarSupported:false`,
`platform:"darwin"`. Do not offer them to a Mac user.

## Toolbar extension family: buttons in the browser toolbar

pup ships a small family of MV3 toolbar tiles (pup dots, the identity avatar, the annotate pen).
They ride the Chrome-for-Testing launch (`--load-extension`); pup auto-enables Developer mode and
pins them at each launch (v2.0.114), so they appear with zero setup.

| Key | Default | What it does |
|---|---|---|
| `toolbarExtension` | **on** | The Adom Pup toolbar buttons (annotate, snip, view toggle, dashboard, owner, close). |
| `tbSnipHotkey` | **on** | `Alt+Shift+A` starts annotate in Auto; `Alt+Shift+M` starts it in Multi (compose shapes, capture on Done). Either hotkey on an open toolbar switches its mode. |
| `tbFloatyPencil` | **off** | A tiny pencil in the upper-right CORNER of each page; one click starts annotate. Off by default, the corner hover zone can fight buttons in app headers, and the toolbar pen already covers discovery. |
| `floatyHitPx` | **24** | Size (px) of the invisible corner target that reveals the floaty pencil. Applies live. |

## Annotate & capture

Works on both lanes since 2.0.569: on the default extension lane the overlay is file-injected, so
strict-CSP and Trusted-Types pages (Google Docs) take it too.

Draw on any pup page (pen / snip). Two capture modes, switchable in the overlay toolbar (v2.0.370):
**Multi** (the default since 2.0.701) accumulates shapes and captures ONCE on Enter or Done; **Single**
(called Auto before 2.0.701, still `mode:"auto"`) captures the instant the mouse lifts, the
draw-one-circle case. Keys: Enter finishes, Space toggles Multi/Single, M or S picks one, Esc cancels;
a hint line under the toolbar says so. Multi auto-advances the color after each shape
(red → blue → green → purple; never yellow or white, since 2.0.705) so every shape is distinct with zero clicks.
Colors are a one-click trio (red, blue, green: colors anyone can name when telling the AI which mark is which) with purple/yellow/white in a flyout, each swatch named in its tooltip; a manual
pick overrides the cycle, and the pen cursor carries the current color.

| Key | Default | What it does |
|---|---|---|
| `annCaptionBar` | **on** | Bake a thin context strip under each capture (thread, page, time) so any AI you paste it into sees where it came from. |

Drive it: `pup_annotate {sessionId, tool:"pen"|"snip", mode:"auto"|"multi"}`, the toolbar pen, the
`Alt+Shift+A` hotkey (`Alt+Shift+M` for Multi), or the (off-by-default) corner pencil.

## Foreground etiquette: pup never steals your screen

pup's browser app stays HIDDEN (the Cmd+H state), so its windows never cover your work or take focus,
and they stay fully drivable. When an AI *does* raise a window, it must give a reason, shown on-screen
first, THEN it unhides and activates the window. A background nudge (`pup_alert_window`) is a macOS
notification you can click; it never takes focus.

| Key | Default | What it does |
|---|---|---|
| `fgCaption` | **on** | When an AI brings a window to your screen, show its stated reason as an on-screen caption. |
| `fgCaptionMs` | **2000** | How long (ms) that foreground-reason caption shows. |
| `notMineCaption` | **off** | The single self-foreground caption control (v2.0.292: folded in the old `fgWatch`). Off by default. When on, pup watches for ~20s after a background open/navigate and, if a window pulls ITSELF to the front (JS/focus/Chrome, not pup), briefly captions that Adom did NOT do it. The window is no longer re-parked, off-screen birth means pup no longer needs a foreground-steal watchdog; this is now purely the "not me" caption. |

## Credential vault: pup manages your logins (no Chrome dialog)

pup runs its own Keychain-backed password manager so the AI signs you in without Chrome's foreground
picker. Chrome's native "Save password?" bubble is disabled; pup captures and fills silently.

| Key | Default | What it does |
|---|---|---|
| `captureLogins` | **on** | As you sign into sites, store the username + password in the macOS Keychain (encrypted; never logged/echoed) so return visits auto-fill. Captures on password blur to beat cross-origin SSO redirects. |
| `autoLogin` | **on** | Fill a matching saved login when a login page loads (background, no dropdown). pup never auto-SUBMITS, submitting is reason-gated via `pup_login {submit:true, submitReason}` which confirms the live domain (anti-phishing). |

Verbs: `pup_login` (fill/submit; `realKeystrokes:true` for React-masked fields like Gusto),
`pup_credentials` (list host+username only), `credential_set` / `credential_delete`. Per-site login
flows live in `login-recipes/` on the wiki page.

## In-page identity: which thread owns this window

| Key | Default | What it does |
|---|---|---|
| `ownerChip` | **off** (since 2.0.713) | A tiny chip, bottom-left, naming the owning AI thread + profile. Off by default: it covers whatever the page puts in that corner (a video player's controls, a chat box), and the window title already leads with the thread name. |
| `titleTag` | **off** | Append "(ai-thread: <name>)" to the window title. Off, many pages manage their own title. |
| `titlePrefix` | **off** | Prepend the owning thread (+ wiki signed-in/out) to the title. Off, pup does not mangle page titles by default (see the page-integrity doctrine). |

## Recovery & safety

| Key | Default | What it does |
|---|---|---|
| `pup_restart_browser` (verb, not a setting) | | The fix when a browser wedges: its windows stop responding to the mouse wheel and their tab strips ignore clicks, while dragging a scrollbar still works. That is Chrome's browser process spinning, not a slow page, and only a restart clears it. pup detects it within about 45 s, toasts you, and this verb saves every tab, ends the browser, and brings the windows and tabs back. |
| `idleBrowserQuitMin` | **10** | Minutes a pup browser may sit with NO windows before pup closes it and gives the RAM back (0 = never close it). An empty Chrome still costs hundreds of MB on your machine, most of it a GPU process holding allocations from pages you already closed. The next open relaunches it, still signed in, so the only cost is one cold start. |
| `sleepRecovery` | **on** | Restore windows after a pup restart, or after the browser CRASHES (a nonzero exit code, the only proof pup accepts). A window you close yourself is forgotten the moment it goes, and closing the last pup window ends the browser cleanly: nothing comes back. pup windows are fleeting (2.0.595). Never restarts a live Chrome. |
| `reportIssues` | **on** | Let pup invite AIs to file a wiki issue when they hit something broken. |
| `minimalTouch` | **on** | Safety mode from the Chrome-crash hunt: pup keeps its hands off your windows, opens + drives pages only, skips extra window machinery. The per-feature toggles above win over this master switch. |

## The one profile that matters: adom-you

Every pup window rides the shared durable **adom-you** profile by default, so logins persist and the
credential store grows over time. Isolation (`isolated:true`) is REASON-GATED (`isolationReason`
required) and a non-adom-you window wears the anonymous identity tile so it's visibly not-you. Never
log in on an isolated throwaway, the session (and 2FA-remember) won't persist.