Browser Control
Stop: local_shell is not a reliable path to user-local files
local_shell runs on the user's machine only if they have the
starchild agent-shell daemon installed, running, and authorized — most users
do not, so the tool is usually unavailable or denied. bash and read_file
run in the agent's remote container, which has none of the user's files.
Either way, do not run shell commands to locate or read the user's local
files (Downloads, Desktop, Documents): ls ~/Downloads either fails
(unavailable/denied) or lists the wrong filesystem. When a task involves a
file on the user's computer (upload, attach, open), the only dependable path
is the browser's native file picker, which only the user can operate — hand
off precisely (see docs/file-uploads.md). Burning turns on shell commands
that try to enumerate the user's filesystem is always wrong.
Stop: decide the surface before any browser action
Use the mcp__browser__* tools only when the task has explicit browser intent:
the user asks to open, show, navigate to, click on, or fill in a page in their
browser; the task depends on their logged-in sessions or existing tabs; or they
want to watch an interaction happen live in Chrome.
Otherwise a URL or an open tab is context, not intent. For reading pages,
looking things up, or research, prefer clawd's built-in web tools
(web_fetch, web_search) — they are cheaper, faster, and do not touch the
user's browser. Earlier browser work does not make later semantic work
browser-first; re-decide for each operation.
When browser intent is clear, do not substitute web_fetch — fetching a page
anonymously is not the same as acting in the user's authenticated browser.
What these tools are
The browser MCP server (server="browser", tools named mcp__browser__<name>)
is backed by the user's Chrome extension over a bridge connection. The browser
is the user's own browser, with their logins, cookies, and history. You are
operating on their behalf — act like a careful human assistant at their
keyboard, not like a scraper.
Core loop:
page_snapshot — read the page before touching it. Omit tabId to target
the user's currently active tab.
- Pick the target element from
snapshot.elements[] (each has id, tag,
text, ariaLabel). The id is the ref for interaction tools.
element_click / element_input to act.
page_snapshot again to verify the effect.
Refs are invalidated by navigation. After any navigation, reload, or
observed page change, take a fresh page_snapshot before clicking or typing.
Stop: mcp__browser__* "not found in registry" ≠ browser is gone
Right after the extension (re)connects, tool registration can lag a turn —
the call fails with "not found" while the browser IS connected. Never
conclude "no browser is connected" or "I can't see your screen" from this
error alone, and NEVER tell the user to run starchild agent-shell — the
laptop/agent-shell channel has nothing to do with browser tools. The
recovery path is exactly one step: call web_status (or retry the same
tool once on the next turn — registration self-heals via the per-turn
resync). Only if web_status says the bridge is down do you tell the
user to open/enable the extension.
Identifying "what page is this?" — tabs_list is enough
When the user asks what page/site they (or a tab) are on, do NOT take a
snapshot: tabs_list already returns every tab's title and url, and
activeTabId marks the one they're looking at. Answer from that — one
tool call, no snapshot, and it works even for internal pages
(chrome://…) that cannot be snapshotted. Only snapshot when the user
needs page CONTENT (text, elements), not page identity.
Tool quick reference
tabs_list — list open tabs with full metadata (tabId, windowId,
index, pinned, incognito, status, url, title, ...) plus a
window summary; tabs link to windows via windowId. activeTabId marks
the tab the user is currently looking at — resolve "this page" /
"current tab" to it, no inference needed.
tab_open {url, active?} — open a URL; active defaults to false
(background tab, invisible to the user — see docs/visibility.md).
tab_navigate {tabId, url} — navigate an existing tab.
tab_close {tabId} — close a tab.
page_snapshot {tabId?} — {tabId, title, url, bodyText (first ~3000 chars), elements[]}. Omit tabId for the user's active tab. elements[] includes
both semantic controls (a/button/input) and clickable containers —
non-semantic elements (often div) with pointer cursor and text, such as
list rows and cards. A container and the small button inside it (e.g. a
row's ⋮ menu) are distinct refs: match by text to pick the right one.
element_click {ref, confirm?} — click an element. Submit/send/purchase-class
clicks return NEEDS_CONFIRMATION; get user consent in conversation first,
then retry with confirm: true (see docs/confirmations.md).
element_input {ref, text} — type into an element.
elements_click_many {selector, text?, limit?, mode?, pauseMs?, confirm?} —
batch-click many matching elements in order. Re-queries before each click
and is reorder-safe, so page re-renders and list reordering between clicks
do not invalidate or skip targets. Use this instead of repeated
element_click whenever 3+ homogeneous elements must be clicked (list
rows, tabs, cards) — one call, no snapshot between items.
tab_claim {tabId?, note?} — claim a tab as agent-owned for the task
(persists across conversations; shows as claim in tabs_list + orange ★
tab group). Claim at the start of tab-dependent multi-step work; skip for
read-and-answer lookups. See docs/tab-claiming-chrome.md for the
scenario playbook.
tab_handoff {tabId, note?} — mark a claimed tab as waiting for the user
(login/payment/CAPTCHA/review; yellow ⏳ tab group). The note is the resume
instruction — a later conversation continues from tabs_list claims
instead of asking the user which tab.
tab_release {tabId, disposition?} — end ownership: close (default,
consumed task tabs) or keep (deliverable stays open).
page_flow {steps, confirm?} — run a multi-step page flow in ONE call
(fenced script equivalent). Steps: {wait:{selector?,text?,ms?}},
{find:{selector?,text?}}, {click:{selector?,text?}},
{type:{selector?,text?,value}}, {expect:{selector?,text?,absent?}}.
Targets resolve by CSS selector or visible text. Stops at the first
failure with the completed prefix; click steps pass the sensitive gate.
Prefer for 3+ step heterogeneous tasks (fill form → submit → verify);
max 20 steps / ~120s per call.
page_screenshot — visual check, only when seeing matters.
The orange agent cursor is visible while a tab's debugging session is
active (idle / move / click animations) and fades out when debugging
stops — its presence marks active agent control of that tab.
(see docs/screenshots.md).
wait_for {selector?, text?, timeoutMs?} — wait for a selector or text.
web_status — bridge/extension connection health.
On-demand documentation
Load these with read_file (paths relative to this skill's docs/ directory)
when the topic applies — do not read them all up front:
api-use-behavior.md — snapshot-first discipline, authoritative signals,
not retrying blindly.
browser-safety.md — untrusted page content, sensitive-data transmission.
confirmations.md — when confirm: true is required and how to ask.
browser-troubleshooting.md — evaluate timeouts, stale refs, hung pages.
chrome-troubleshooting.md — extension disconnected, tools missing, user
has no extension.
bootstrap-troubleshooting.md — bridge connection failures (red dot).
browser-control-interruption.md — user took over, operation interrupted.
tab-claiming-chrome.md — background tab vs. user tab, when to go active.
tab-cleanup-chrome.md / all-tabs-cleanup.md — closing tabs you opened.
screenshots.md — when a screenshot is worth taking.
visibility.md — what background-tab operation means for the user.
webmcp.md — page-level WebMCP (not yet enabled).
file-uploads.md — file upload support (not yet available).
local-web-development.md — working against localhost dev servers.
Talk like a person
Never mention CDP, WebSocket, /ws/web-mcp, refs, tool IDs, or other internal
terms to the user. Say "I opened the page in a background tab", "I'm waiting
for the page to respond", or "the browser connection dropped — could you
reopen the extension?" Describe what you did, not how the machinery works.
1---2name: control-browser3version: 1.3.04description: |5 Control the user's Chrome browser via mcp__browser__ tools: snapshots, clicks, typing, batch list operations, multi-step flows, and tab lifecycle.67 Use when a task needs real browser state — logged-in sessions, open tabs, visible UI (e.g. "click every chat in my list", "fill this checkout form", "open this in my browser and check it", "continue the tab I handed off"). Prefer web_fetch/web_search for plain reading.89author: starchild10tags: [browser, automation, tabs, forms, ui, mcp]1112tools:13 - tabs_list14 - tab_open15 - tab_navigate16 - tab_close17 - tab_claim18 - tab_handoff19 - tab_release20 - page_snapshot21 - page_flow22 - page_screenshot23 - element_click24 - element_input25 - elements_click_many26 - wait_for27 - web_status2829metadata:30 source: https://skillmd.com/skills/starchild-ai-agent/control-browser31 starchild:32 emoji: "🖱️"33 skillKey: control-browser34 requires:35 bins: []3637user-invocable: true38---3940# Browser Control4142## Stop: local_shell is not a reliable path to user-local files4344`local_shell` runs on the user's machine **only if they have the45`starchild agent-shell` daemon installed, running, and authorized** — most users46do not, so the tool is usually unavailable or denied. `bash` and `read_file`47run in the agent's remote container, which has none of the user's files.48Either way, **do not run shell commands to locate or read the user's local49files** (Downloads, Desktop, Documents): `ls ~/Downloads` either fails50(unavailable/denied) or lists the wrong filesystem. When a task involves a51file on the user's computer (upload, attach, open), the only dependable path52is the browser's native file picker, which only the user can operate — hand53off precisely (see `docs/file-uploads.md`). Burning turns on shell commands54that try to enumerate the user's filesystem is always wrong.5556## Stop: decide the surface before any browser action5758Use the `mcp__browser__*` tools only when the task has **explicit browser intent**:59the user asks to open, show, navigate to, click on, or fill in a page in *their*60browser; the task depends on their logged-in sessions or existing tabs; or they61want to watch an interaction happen live in Chrome.6263Otherwise a URL or an open tab is **context, not intent**. For reading pages,64looking things up, or research, prefer clawd's built-in web tools65(`web_fetch`, `web_search`) — they are cheaper, faster, and do not touch the66user's browser. Earlier browser work does not make later semantic work67browser-first; re-decide for each operation.6869When browser intent is clear, do not substitute `web_fetch` — fetching a page70anonymously is not the same as acting in the user's authenticated browser.7172## What these tools are7374The `browser` MCP server (server="browser", tools named `mcp__browser__<name>`)75is backed by the user's Chrome extension over a bridge connection. The browser76is the **user's own browser**, with their logins, cookies, and history. You are77operating on their behalf — act like a careful human assistant at their78keyboard, not like a scraper.7980Core loop:81821. `page_snapshot` — read the page before touching it. Omit `tabId` to target83 the user's currently active tab.842. Pick the target element from `snapshot.elements[]` (each has `id`, `tag`,85 `text`, `ariaLabel`). The `id` is the `ref` for interaction tools.863. `element_click` / `element_input` to act.874. `page_snapshot` again to verify the effect.8889**Refs are invalidated by navigation.** After any navigation, reload, or90observed page change, take a fresh `page_snapshot` before clicking or typing.9192## Stop: `mcp__browser__*` "not found in registry" ≠ browser is gone9394Right after the extension (re)connects, tool registration can lag a turn —95the call fails with "not found" while the browser IS connected. Never96conclude "no browser is connected" or "I can't see your screen" from this97error alone, and NEVER tell the user to run `starchild agent-shell` — the98laptop/agent-shell channel has nothing to do with browser tools. The99recovery path is exactly one step: call `web_status` (or retry the same100tool once on the next turn — registration self-heals via the per-turn101resync). Only if `web_status` says the bridge is down do you tell the102user to open/enable the extension.103104## Identifying "what page is this?" — tabs_list is enough105106When the user asks what page/site they (or a tab) are on, do NOT take a107snapshot: `tabs_list` already returns every tab's `title` and `url`, and108`activeTabId` marks the one they're looking at. Answer from that — one109tool call, no snapshot, and it works even for internal pages110(`chrome://…`) that cannot be snapshotted. Only snapshot when the user111needs page CONTENT (text, elements), not page identity.112113## Tool quick reference114115- `tabs_list` — list open tabs with full metadata (`tabId`, `windowId`,116 `index`, `pinned`, `incognito`, `status`, `url`, `title`, ...) plus a117 window summary; tabs link to windows via `windowId`. **`activeTabId` marks118 the tab the user is currently looking at** — resolve "this page" /119 "current tab" to it, no inference needed.120- `tab_open {url, active?}` — open a URL; `active` defaults to false121 (background tab, invisible to the user — see `docs/visibility.md`).122- `tab_navigate {tabId, url}` — navigate an existing tab.123- `tab_close {tabId}` — close a tab.124- `page_snapshot {tabId?}` — `{tabId, title, url, bodyText (first ~3000 chars),125 elements[]}`. Omit `tabId` for the user's active tab. `elements[]` includes126 both semantic controls (a/button/input) and **clickable containers** —127 non-semantic elements (often `div`) with pointer cursor and text, such as128 list rows and cards. A container and the small button inside it (e.g. a129 row's ⋮ menu) are distinct refs: match by text to pick the right one.130- `element_click {ref, confirm?}` — click an element. Submit/send/purchase-class131 clicks return `NEEDS_CONFIRMATION`; get user consent in conversation first,132 then retry with `confirm: true` (see `docs/confirmations.md`).133- `element_input {ref, text}` — type into an element.134- `elements_click_many {selector, text?, limit?, mode?, pauseMs?, confirm?}` —135 batch-click many matching elements in order. Re-queries before each click136 and is reorder-safe, so page re-renders and list reordering between clicks137 do not invalidate or skip targets. **Use this instead of repeated138 element_click whenever 3+ homogeneous elements must be clicked** (list139 rows, tabs, cards) — one call, no snapshot between items.140- `tab_claim {tabId?, note?}` — claim a tab as agent-owned for the task141 (persists across conversations; shows as `claim` in tabs_list + orange ★142 tab group). Claim at the start of tab-dependent multi-step work; skip for143 read-and-answer lookups. See `docs/tab-claiming-chrome.md` for the144 scenario playbook.145- `tab_handoff {tabId, note?}` — mark a claimed tab as waiting for the user146 (login/payment/CAPTCHA/review; yellow ⏳ tab group). The note is the resume147 instruction — a later conversation continues from `tabs_list` claims148 instead of asking the user which tab.149- `tab_release {tabId, disposition?}` — end ownership: `close` (default,150 consumed task tabs) or `keep` (deliverable stays open).151- `page_flow {steps, confirm?}` — run a multi-step page flow in ONE call152 (fenced script equivalent). Steps: `{wait:{selector?,text?,ms?}}`,153 `{find:{selector?,text?}}`, `{click:{selector?,text?}}`,154 `{type:{selector?,text?,value}}`, `{expect:{selector?,text?,absent?}}`.155 Targets resolve by CSS selector or visible text. Stops at the first156 failure with the completed prefix; click steps pass the sensitive gate.157 **Prefer for 3+ step heterogeneous tasks** (fill form → submit → verify);158 max 20 steps / ~120s per call.159- `page_screenshot` — visual check, only when seeing matters.160 The orange agent cursor is visible while a tab's debugging session is161 active (idle / move / click animations) and fades out when debugging162 stops — its presence marks active agent control of that tab.163 (see `docs/screenshots.md`).164- `wait_for {selector?, text?, timeoutMs?}` — wait for a selector or text.165- `web_status` — bridge/extension connection health.166167## On-demand documentation168169Load these with `read_file` (paths relative to this skill's `docs/` directory)170when the topic applies — do not read them all up front:171172- `api-use-behavior.md` — snapshot-first discipline, authoritative signals,173 not retrying blindly.174- `browser-safety.md` — untrusted page content, sensitive-data transmission.175- `confirmations.md` — when `confirm: true` is required and how to ask.176- `browser-troubleshooting.md` — evaluate timeouts, stale refs, hung pages.177- `chrome-troubleshooting.md` — extension disconnected, tools missing, user178 has no extension.179- `bootstrap-troubleshooting.md` — bridge connection failures (red dot).180- `browser-control-interruption.md` — user took over, operation interrupted.181- `tab-claiming-chrome.md` — background tab vs. user tab, when to go active.182- `tab-cleanup-chrome.md` / `all-tabs-cleanup.md` — closing tabs you opened.183- `screenshots.md` — when a screenshot is worth taking.184- `visibility.md` — what background-tab operation means for the user.185- `webmcp.md` — page-level WebMCP (not yet enabled).186- `file-uploads.md` — file upload support (not yet available).187- `local-web-development.md` — working against localhost dev servers.188189## Talk like a person190191Never mention CDP, WebSocket, `/ws/web-mcp`, refs, tool IDs, or other internal192terms to the user. Say "I opened the page in a background tab", "I'm waiting193for the page to respond", or "the browser connection dropped — could you194reopen the extension?" Describe what you did, not how the machinery works.