house / Browser Hand

---
name: browser-hand
description: >
  Use when work needs the user's already-open, signed-in Chrome: existing tabs,
  real cookies, forms, screenshots, OAuth-backed sites, or authenticated admin
  UIs. Includes an extension-first workflow plus a documented low-level
  headless/CDP fallback for disposable or dedicated-profile automation.
license: MIT
compatibility: Requires local Chrome with the Browser Hand extension and relay.
category: browser
tags: [browser, chrome, extension, automation, authenticated-sessions, agent]
agents: [claude-code, codex, grok]
metadata:
  author: verygoodplugins
  version: "0.6.2"
resources:
  - path: references/setup.md
    type: file
  - path: references/extension-cli.md
    type: file
  - path: references/remote-debug-fallback.md
    type: file
  - path: references/platform-gotchas.md
    type: file
  - path: references/troubleshooting.md
    type: file
  - path: scripts/anon-screenshot.sh
    type: file
---

Browser Hand

Control the user’s real Chrome profile through a local extension bridge. No --remote-debugging-port on the everyday profile.

This is a skill, not an MCP server: no always-on tool list and no extra MCP process. The agent loads it when the task matches (signed-in browser work).

When to load this skill

Load it when any of these are true:

• The task needs a site the user is already signed into.
• The user mentions existing tabs, cookies, “my Chrome,” “logged in,” or a real account.
• Remote debugging / a fresh Chromium would lose auth or get blocked (common with Google and other OAuth).

Skip it when:

• A public page can be fetched with HTTP / WebFetch.
• The user only wants a disposable headless browser (use the upstream dev-browser CLI).

Why this instead of remote debugging

1. Modern Chrome will not attach a remote-debug port to the default profile without a separate user-data dir.
2. Sites often block debugger/automation-shaped sessions (including Google OAuth).
3. This stack defaults to background tabs — no stealing OS focus while the user works.
4. Recovery paths for password-manager wedges and multi-step agent flows; local challenge gym for agent-shaped failures.

Pieces (repo root)

Setup (once)

npm run setup
# Chrome → Load unpacked → extension/dist/chrome-mv3
# NOT extension/.output/ — that is a stale WXT build whose manifest still
# says "dev-browser"; loading it is why Chrome shows the old name.
npm run relay    # leave running
npm run doctor   # want status: tab_bootstrap_works

Switching from old dev-browser skill/extension? npm run setup -- --cleanup-legacy

Details: references/setup.md.

Daily commands

browser-hand doctor
browser-hand open --url https://example.com --page-name work
browser-hand snapshot --page-name work
browser-hand fill --page-name work --fields '{"Email":"[email protected]"}'
browser-hand click --page-name work --text "Submit"
browser-hand type --page-name work --label "Bio" --text "Hello"
browser-hand evaluate --page-name work --code 'document.title'
browser-hand screenshot --page-name work

Full reference: references/extension-cli.md.

Agent rules

• Prefer named pages (--page-name) for multi-step work.
• open/goto/snapshot/screenshot/evaluate create a named tab if missing; click/type/fill/autofill-profile attach to an existing one and error instead. Pass the same --page-name you opened with — omitting it acts on whichever tab is active.
• Do not request window focus for ordinary fill/click/snapshot. Only use focus --focus window --reason "…" when a human must act (2FA, captcha, confirm).
• Snapshot or screenshot before and after writes; verify with evaluate when critical.
• On username/password manager weirdness, soft recovery is built in — retry evaluate/fill; re-open the named page if screenshot still fails.
• Append new platform quirks to references/platform-gotchas.md on the same run.

Optional headless

For CI / empty profile only: upstream dev-browser --headless or --connect to a non-default debug profile. See references/remote-debug-fallback.md. Never treat that as “drive my daily Chrome.”

Read-only / audit

Observation-only tasks: no Save/Publish/Delete; evidence from the authenticated profile; filenames with provenance. See references/troubleshooting.md.

Why it exists

Remote debugging and WebDriver-style attach are a bad fit for everyday Chrome:

modern Chrome blocks debug ports on the default profile, many sites (including

Google OAuth) treat debugger sessions as hostile, and automation steals OS focus.

Sandbox Chromium has none of your cookies.

Browser Hand uses a small Chrome extension and a local relay so agents drive the

same profile you already use. It is a loadable skill, not an MCP server —

no always-on tool tax; agents pull it in when the task needs a real browser.

History

0.6.x

Public skill package for verygoodplugins/browser-hand.

AutoVault-first install, background focus, soft recovery for password-manager

wedges, agent obstacle course.

Earlier (as house `dev-browser`)

Extension-relay vs debug-port paths lived under AutoHub-coupled runbooks.

Productized as Browser Hand under Very Good Plugins.

How Jack actually uses it

Default to the extension CLI for signed-in work. Install the skill with AutoVault;

keep the relay and extension running locally. Reach for headless/remote-debug only

for CI or throwaway profiles.

What it is not

Not Playwright-in-a-box for empty Chromium. Not an MCP browser server. For durable

agent memory across sessions, see AutoMem; for skill packaging, see AutoVault.