claude --chrome: field notes on letting Claude Code drive my own browser, and where it breaks

claude --chrome is the flag that connects Claude Code to your own Chrome: the agent in the terminal opens tabs, clicks, types and reads pages in the browser you are already signed into. It is the mode where an agent is slowest and can do the most damage, and the one I use most days: the flag appears 93 times in my session notes.

• What it is. One extension, two drivers: Anthropic's Claude in Chrome extension, run from a side panel on its own or from the terminal with --chrome.
• What I use it for. A live search results page, screenshots out of Google Ads, Merchant Center and Search Console for a client project, and publishing to a social network, with reservations.
• Where it breaks. A renderer that freezes on screenshot (27 timeouts in 11 sessions), a click that reports success without clicking, a composer that eats text (8 attempts, 4 failures for one thread).
• The risk. It inherits your logged-in session. The gates: the extension allowlist, plan mode for read-only work, a state check after every click that publishes.
• When to script instead. A flow that repeats belongs in Playwright. The agent gets the browser when the answer sits on a page nobody can script in advance.

The agent behind these notes is Claude Code; the browser is one of the eight MCP servers I keep connected, under the name claude-in-chrome, which matters when we get to who can switch it off.

Can Claude use the Chrome browser?

Yes, in two ways, and the names are worth a paragraph. Anthropic's Help Center describes Claude in Chrome as "a browser extension that allows Claude to read, click, and navigate websites alongside you", driven from the Chrome side panel. Claude Code's docs describe the same extension driven from your terminal, which is what claude --chrome turns on.

My working split, my reading rather than a line from either document: Claude in Chrome is the product, an assistant in a side panel. Claude Code with Chrome is the same extension taken over by the terminal agent, so the agent that has your repo and your shell now also has your tabs. The Help Center lists both entry points, the side panel and Claude Cowork or Claude Code.

The docs' capability list for the terminal side: console errors and DOM state, forms and user flows, "any app you're logged into without API connectors", GIF recording; a separate section covers file uploads, capped at 10 MB per upload. The line to underline: "Claude opens new tabs for browser tasks and shares your browser's login state, so it can access any site you're already signed into." Everything good and everything dangerous about this mode is in that sentence.

How to start claude --chrome

Prerequisites from the docs: a Chromium browser, the Claude in Chrome extension at version 1.0.36 or higher, Claude Code, and a direct Anthropic plan (Pro, Max, Team or Enterprise), signed in with /login. With an API key or a claude setup-token token, Chrome integration stays off even with the flag: the extension cannot authenticate with those credentials.

claude --chrome

The first launch shows a one-time dialog about site permissions. After that, /chrome is the control panel. A working setup reads "Status: Enabled" and "Extension: Installed". "Enabled by default" sits in the same menu; the docs warn that browser tools then load in every session and cost context. I pass the flag only when needed.

Site permissions are "inherited from the Chrome extension" and managed there. In plan mode the docs draw a line I lean on: read_page, get_page_text, find, console and network reads and screenshots run without a prompt; clicks, typing, navigation, tab and window management and GIF recording ask. A read-only call also asks when it sets a state-changing flag, such as save_to_disk on a screenshot.

What I use the browser mode for

Three jobs, in order of how well they work.

Reading a live search results page. On 30 August I loaded a Google results page with gl=us&hl=en&pws=0 and pulled it through get_page_text to collect the People Also Ask questions for this batch of posts, this one included. One of my SEO tools has no SERP snapshots for narrow phrases. Read-only, no login, nothing to break.

Screenshots out of ad and search panels. On 28 August: 15 screenshots from Google Ads, Merchant Center and Search Console for a client project, about 25 minutes, 5 fresh tabs. A person with the panels open does it faster. What the agent adds is the write-up next to each screenshot, and the write-up is the deliverable.

Publishing to a social network. The weakest of the three; two sections below.

Failure mode 1: the renderer freezes on screenshot

The error string is "Page.captureScreenshot timed out". The natural move, another screenshot, is wrong: a frozen renderer stays frozen, and the second one times out too. My retro of 16 July counted 27 of these timeouts across 11 sessions, with a record of 7 retries in a row on one tab.

The rule I wrote into my config after that retro: one retry at most, then tools that do not render. read_page and find return structure and matched elements, get_page_text returns text; all three worked on tabs that could not paint a screenshot. If a picture is required: close the tab, open a fresh one, navigate, wait 8 to 10 seconds, shoot at once. resize_window helped on 24 August and did nothing on 28 August.

Which pages freeze: heavy single-page apps. A hosting panel, Figma, admin dashboards, and the Google panels above, which freeze after loading finishes.

Failure mode 2: the click that did not click

Clicking by screen coordinates on a Post, Reply or Publish button silently does nothing: the modal stays open, the text stays in the field, no error comes back, and the agent reports success. I learned this on 20 August. Clicking by ref, the element handle that find returns, is necessary and not sufficient: that day the first click by ref failed on 3 of 5 parts of a thread and on the comment field. The second click, with a fresh ref from a new find, went through every time.

Two rules came out of it. After every click that publishes, check the state of the page before doing anything else. Retry only with a fresh ref. Free detector: try to navigate away while the composer is open. "Leave site? unsaved changes" means the publish did not happen.

Failure mode 3: the composer eats the text

On 13 August I let the agent publish a 7-part thread through the browser. It took 8 attempts and produced 4 different failures. Twice the focus moved between tool calls and the typed text went into keyboard shortcuts. Once execCommand broke the rich-text editor and left 1419 characters of junk in the box. Once a click on Reply cleared the field without publishing. The agent got the root post, part 1 and part 2 out. I posted the rest by hand, in about a minute.

Two conclusions. Through a browser, the agent publishes safely only if it verifies the field before every click, and even then a person is faster. Since 17 August I use a prefilled URL where one exists, which opens the composer with the text in place, so the agent never types into the editor. An API beats both.

Is Claude in Chrome risky?

Yes, and Anthropic says so on the Help Center's getting-started page: "Claude in Chrome is enhanced with our safety classifiers but is still risky." The agent inherits your login state, so every account your browser is signed into is one it can act in, under your name.

The safety article says the extension "still carries inherent risks" and names the attack: prompt injection, where "malicious instructions hidden in web content (websites, emails, documents) could trick Claude into taking unintended actions". Its advice: trusted sites first, "Manually approve" to review every action, "a separate browser profile without access to sensitive accounts", and admin allowlists and blocklists for organizations.

My gates, in the order they fire. The extension allowlist decides which domains the agent can touch. Plan mode makes read-only calls free and state-changing calls a question. Every click that publishes or sends gets a state check; failure mode 2 showed why. That last one is Gate 6 of my production gates, human approval on write, spend and send. The browser is also a tool server, so the rule from the MCP server security post holds: content returned by a tool is untrusted input.

For a team that wants the terminal agent but not the browser, the docs note one lever: block the claude-in-chrome MCP server with the deniedMcpServers managed setting, and no install prompt appears.

Playwright or claude --chrome: which one for the job?

The Playwright review lists four routes to a browser: Test, Library, CLI and the official MCP server. claude --chrome is another route, with one different property: no script, and your session instead of a clean context.

Script it with Playwright when the flow repeats, needs assertions, or runs unattended: a release check or a nightly scrape. Give it to the agent when the flow runs once and nobody can write the selectors in advance: a results page, evidence out of a panel. The cost is speed and reliability; the return is that nobody wrote a script for a one-off.

Publish with neither, when you can avoid it. API first, prefilled URL second, browser click last, with the state check.

Do Cursor, Codex, Copilot and opencode have the same thing?

I checked their documentation on 30 August 2026. Short answer: everyone but opencode has a browser, and they split two ways on whose session it runs in.

Two camps, then. Claude Code and the ChatGPT extension share your logged-in session and gate it per site: an allowlist in one, a question before each new website in the other. VS Code and Cursor isolate by default and let you sign in or share a tab on purpose. The isolated default is safer; the shared one reads the panel I am already logged into, which is why I use it and why this post has three failure sections and a gate section. I did not check GitHub Copilot CLI.

Why does Claude not work on Chrome?

If nothing happens after the flag, the cause is almost always in the docs: four items on the troubleshooting page and one in the prerequisites. The extension is not detected, a modal dialog blocks the page, the service worker went idle, a Windows named pipe is taken, or the session uses an API key.

• Extension not detected. Check chrome://extensions, then /chrome and "Reconnect extension"; a Chrome restart picks up the native messaging host file.
• Modal dialogs. An alert, confirm or prompt blocks browser events; dismiss it by hand.
• Idle service worker. "Receiving end does not exist" means reconnect from /chrome.
• Windows. A named pipe conflict (EADDRINUSE) means some process holds the pipe; the docs say to restart Claude Code and close other sessions that might hold Chrome. WSL is unsupported.
• Authentication, from the prerequisites. API key and setup-token sessions keep the integration off.

Is Claude for Chrome worth it?

For me, yes, with the boundary drawn where the failures are. 93 mentions of --chrome in my session notes means the mode earned a daily slot for reading and testing: results pages, panels, console, UI checks. For publishing, it is slower than a person and needs a state check per click. The value is the loop, not the clicks.

On price: the terminal integration needs a direct Anthropic plan (Pro, Max, Team or Enterprise), and the docs mention no separate charge for the extension.

The verdict

claude --chrome is the most useful and the least reliable tool in my Claude Code setup, and both halves are true at once. It freezes on screenshots, reports clicks that did not happen, and mangles text in rich editors. The fixes are small: one retry then a text tool, a fresh ref per click, a state check after every publish, prefilled URLs instead of typing. The gates: allowlist, plan mode, Gate 6. Reading and testing, daily. Publishing, only with a check after every click, and preferably not at all.

Sources, all read on 30 August 2026: Claude Code's Chrome docs; Anthropic's Help Center on getting started with Claude in Chrome and using it safely; Cursor's Browser tool docs and Browser use help page; VS Code's browser tools page and MCP servers page; the ChatGPT docs' Computer Use page and browser extension page; the Codex docs' CLI page; opencode's MCP servers page. My own numbers come from session notes and retros dated 16 July and 13, 17, 20, 24, 28 and 30 August 2026.