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 snapshot saves to disk. The full snapshot is the last resort, not the first.
• [verified] For repeated data (lists, cards, tables) use browser_evaluate with a targeted querySelectorAll and return a compact array, not the whole tree.

Act without a snapshot (frugal navigation)

• [verified] The target of browser_click/type/evaluate accepts a unique selector in addition to the snapshot ref: CSS (h1) and Playwright engines (role=button[name="X"], regex in name=). Tested resolving without a prior snapshot.
• With a tandem:map profile that has sel:, act by selector and SKIP the snapshot (it costs ~18× the profile), validating the route first with fingerprint.mjs check (a gate, not faith). Full flow: tandem:map skill, §"Frugal flow".
• [verified] On deferred-render SPAs, browser_wait_for on the sel BEFORE acting: the first attempt may not find the element yet.
• Executable recipes: a repeated, named task (e.g. "open ticket by id") can live as a parameterized recipe in the profile. scripts/recipe.mjs compile <host> <recipe> <args> compiles it to steps (--step, observable) or a Playwright function (--fast, 1 call via browser_run_code_unsafe — mandatory dry-run, RCE-equivalent). Detail: tandem:map skill.

Signal vs noise

• [verified] A broad extraction (e.g. a[href*="/x/"]) captures junk: auxiliary files, duplicates, internal links. Filter and dedupe BEFORE reporting.
• [verified] Don't confuse the extracted with the curated: "96 links ≠ 96 items". State the real number after filtering and flag whatever you can't confirm as the official list.

Dynamic loading (infinite scroll / lazy-load)

• [verified] The first snapshot/evaluate of an infinite-scroll page is INCOMPLETE (seen: 10 of 100 items on quotes.toscrape.com/scroll). To gather it all: an ASYNC browser_evaluate that scrolls to the bottom in a loop until the count STABILIZES (N iterations with no change) with a safety cap, and collects the data in the same pass: while (stable<3 && iters<60){ scrollTo(0,scrollHeight); await sleep(350); n=count; if(n==prev)stable++ else{stable=0;prev=n} } Result: 10→100 in 6 iterations, stopped on its own. A single tool call does all the loading.

Pagination

• [verified] First detect how many pages there are (text like "Page 1 of 50") so you don't walk blindly. Walk with an async browser_evaluate using SAME-ORIGIN fetch + DOMParser (it doesn't reload the human's window on each jump) and accumulate, with an EXPLICIT page CAP. Seen: books.toscrape.com, 3 of 50 pages → 60 books. If you need more than the cap, raise it consciously and say so; never walk all N without a limit or silence it.

Obstacles (cookie banners / consent modals)

• [verified] They usually live in a third-party IFRAME (Sourcepoint, OneTrust…), cross-origin. Consequence: browser_evaluate of the TOP document doesn't reach them (can't read or click inside the iframe). Seen on theguardian.com (iframe "SP Consent Message").
• [verified] BUT browser_snapshot DOES flatten iframes: the buttons appear with frame refs (like f2e58) and browser_click by that ref acts on them. Pattern: snapshot → locate the button ("Accept all"/"Reject all") → browser_click by ref. If it fails, the human closes it with the mouse. Accepting/rejecting cookies is the human's decision: don't click "Accept all" on your own unless the human asks.

Saving snapshots to a file

• [verified] browser_snapshot(filename: "x.md") saves relative to the MCP's cwd (ended up in ~), IGNORING --output-dir → it clutters the home. Use an ABSOLUTE path in filename, or don't pass filename (the automatic reference already goes to the output-dir).

SPA / JS-rendered content

• [verified] browser_navigate waits for the initial render (Playwright waits for 'load'): on quotes.toscrape.com/js the 10 JS-painted quotes were ready with no extra wait. You only need browser_wait_for for DEFERRED content (later XHR, lazy after interaction).

Forms / login

• [verified] Small form → browser_snapshot returns inline refs. Pattern: browser_type by ref in each field → browser_click on submit (or browser_type submit:true) → verify the post-action state (e.g. a /logout link appears). Validated on quotes.toscrape.com/login. Login with 2FA/captcha: the human does it (human-AI handoff).

How this list grows

Every new website that breaks a pattern → add the rule here with its [verified] mark. Don't add theoretical rules you haven't lived: this profile is valuable because it's born of evidence, not a catalog.