/tandem

name: tandem
description: How to operate the Chrome browser shared with the human (the tandem MCP's browser_* tools). Use it whenever you need to navigate, read/analyze pages, get past blocks that require human interaction (captchas, anti-bot checkpoints, logins), or inspect the network/DOM in real time alongside the human.

tandem — shared browser, human + Claude

The human and you share ONE SAME Chrome in real time. The human sees it and drives it with the mouse; you operate it with the `browser_*` tools of the `tandem` MCP (Playwright over CDP). What one does, the other sees: state, cookies, and session are the same.

Startup

• The browser does NOT start on its own. If the `browser_*` tools give `ECONNREFUSED 127.0.0.1:9222`,

Chrome isn't running: ask the human to run `/tandem:browser-start` (or run it yourself if you have the command available). Check state with `/tandem:browser-status`.

Division of labor

• **The human does** what requires being human: solving captchas, getting past anti-bot checkpoints

(e.g. Vercel Security Checkpoint), 2FA logins, visual decisions.

• **You do** the analysis: `browser_snapshot` (accessibility tree, better than a screenshot

for reasoning and acting), `browser_evaluate` (JS), `browser_network_requests`, data extraction, filling forms, clicking by snapshot ref.

• Typical unblocking pattern: the human clears the wall → you read the already-rendered DOM and analyze.

Two modes: live vs delegated (don't pollute the context)

There are two ways to navigate; choose by the task, not one by default:

• **Live (in this context):** when there's handoff with the human (walls they clear: captcha,

checkpoint, login), interactive navigation, or on-the-fly decisions. The human is in the loop.

• **Delegated to the `web-navigator` subagent:** when it's HEAVY read/extraction without walls

(large snapshots, scraping, walking many pages). The subagent swallows the DOM/snapshots in ITS context and returns to you only the distilled data → this context isn't polluted. You share the SAME Chrome (global state), so the human keeps seeing the window.

• Rule: if the task will generate a lot of noise (snapshots of hundreds of KB, multi-page) and does NOT

need the human live → delegate. If it needs human handoff or iterating with you → live.

• Limit of delegation: the subagent doesn't talk to the human. If it hits a wall, it returns which and where;

you tell the human, they clear it, and you relaunch the subagent to continue.

Tab choreography (don't steal focus)

• By default the MCP **reuses the active tab**. If the human is reading something, do NOT navigate over

their tab without warning: open yours with `browser_tabs` (new) and work there.

• Before a navigation that changes what the human sees, say so ("I'm going to open X in a new tab").
• For actions: by ref from the most recent `browser_snapshot`, or by a **unique** durable

**selector** (`target` accepts both — [verified]). Never coordinates. If there's a profile with `sel:`, acting by selector avoids the snapshot (see "Act without a snapshot" and the `tandem:map` skill).

Security (non-negotiable)

• It's a **dedicated profile**, not the human's personal Chrome. Even so, any login the human

does there leaves cookies/tokens accessible via CDP. Do NOT navigate to sensitive sites (banking, personal email) in the shared tab unless the human explicitly asks.

• `browser_evaluate` runs arbitrary JS on the page: use it for analysis, not for destructive

actions or exfiltration. No sending session data to third parties.

• Pentest work: only within authorized scope; the shared browser is no excuse to go

out of scope.

After a Chrome (re)start — the first tool may reconnect

• The MCP server is PERSISTENT (one per session); Chrome is EPHEMERAL (`browser-start`/`-stop`).

When Chrome is killed and a new one starts on the same port — a **voluntary `stop`→`start`** OR Chrome dying mid-session — the MCP still holds a `connectOverCDP` handle to the OLD process and doesn't notice until a tool fails.

• Symptom: the FIRST `browser_*` after a new Chrome fails with "Target page/context/browser has been

closed" (dead handle); that very failure triggers the reconnect, so the SECOND tool works `[verified 2026-06-29]`. (`ECONNREFUSED 127.0.0.1:9222` is different: no Chrome at all → `/tandem:browser-start`.)

• Rule: do NOT restart the MCP or the session. Retry once — or fire a cheap `browser_tabs` as a

WARMUP right after `browser-start` — so the human never sees the error. Root cause is in @playwright/mcp's CDP reconnect (a changed-process endpoint), not in tandem's scripts.

Site memory (`tandem:map` skill)

The section below is CROSS-site technique (applies to any website). The knowledge OF-a-specific-site (its routes, its search, its locators) lives in a **per-host profile** managed by the `tandem:map` skill (`~/.claude/tandem/sites/<host>.md`).

• When you start operating a site: check whether there's a profile (`scripts/map.sh show <host>`). If it exists,

read it BEFORE firing snapshots — you navigate knowingly, not re-deriving. If it doesn't exist and the work isn't trivial, offer the human to do a recon and save it (assisted recon).

• Snapshot `eNN` refs are ephemeral: in profiles, locators are anchored by role+name,

never by ref or position. Detail: the `tandem:map` skill and `tandem/docs/01-navigation-memory.md`.

Real navigation — patterns (LIVING LIST, distilled from real use)

These rules are born from concrete navigations, not theory. They grow each time a new website breaks something. Mark each rule as [verified] (lived) or [hypothesis] (to validate).

Efficient reading (don't burn context)

• [verified] A `browser_snapshot` of large pages can exceed the token limit (seen:

135 K on a catalog page). Do NOT dump it into the context. Extract only what's needed with `browser_evaluate` (JS that returns clean data) or with grep over the file the snapsho