Using Claude Code with Chrome

Who this is for and what you will get

This guide suits people building front-end or web apps who want Claude Code to check pages in the browser, read console errors, or fill in a batch of forms. By the end you will have the Chrome extension connected, you will understand the site permission settings, and you will know the order in which to troubleshoot a failed connection.^[1]

What the integration does

Claude Code works with the Claude in Chrome extension, so you can run browser automation from the command line or the VS Code extension. Claude opens new tabs for browser tasks and shares your browser's login state, so it can reach any site you are already signed into. Browser actions run in a visible Chrome window in real time.^[1]

When Claude meets a login page or a CAPTCHA, it pauses and asks you to handle it manually.^[1]

Typical uses include reading console errors and DOM state before fixing the code that caused them, testing form validation and user flows, working inside signed-in apps such as Google Docs, Gmail and Notion, extracting data from pages, automating repetitive tasks, uploading files, and recording a browser session as a GIF.^[1]

Before you start

You need Google Chrome or Microsoft Edge, or another Chromium browser such as Brave, Arc, Vivaldi or Opera. You also need version 1.0.36 or later of the Claude in Chrome extension from the Chrome Web Store, Claude Code, and a direct Anthropic plan (Pro, Max, Ultra, Team or Enterprise).^[1]

Two limits matter. First, sign in with /login. An API key or a long-lived token from claude setup-token keeps Chrome integration off, even with --chrome.^[1] Second, the integration is not available through third-party providers such as Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry.^[1] It is also not supported in Windows Subsystem for Linux.^[1]

First run

Start Claude Code with the flag:

claude --chrome

The first launch with Chrome shows a one-time dialog that introduces the integration and explains site permissions. Press Enter to continue.^[1]

Then describe the browser task in plain language, for example:

Go to code.claude.com/docs, click on the search box,
type "hooks", and tell me what results appear

If a permission prompt appears, it begins with Claude in Chrome wants to and offers to allow all actions on that site for the session. Approve it, and Claude opens a new tab and starts.^[1]

Run /chrome to see the connection status, manage permissions, reconnect the extension, or pick a browser. The integration is working when the status panel shows "Status: Enabled" and "Extension: Installed".^[1] With several browsers connected, Claude asks you to choose one. To change the choice later, run /chrome and select "Select browser…".^[1]

Where Claude's tabs go

The extension collects the tabs Claude opens into a Chrome tab group tied to your session. Typing /clear closes that group, open pages included, unless work that survives the clear is still running. With /resume, when you exit, or when you clear during surviving work, the group closes only if it holds nothing but empty new tabs, so pages you may still be reading stay open.^[1]

Privacy and sign-in

Claude shares your browser's login state, so it can reach any site you are signed into. It works in a visible Chrome window in real time and pauses for you at login pages and CAPTCHAs. A GIF recording captures everything visible in the browser, including account details on logged-in pages.^[1]

If the extension and Claude Code are signed in to different organizations, the browser tools report that the extension is not connected, even when both use the same account.^[1]

Site permissions and defaults

Site-level permissions come from the Chrome extension's settings, which decide which sites Claude can browse, click and type on.^[1] If Claude Code cannot detect the extension during an interactive session, it shows an install prompt titled "Claude wants to use your browser". It appears at most once per session and offers Install extension, Not now and Don't ask again.^[1]

To skip the flag each time, run /chrome and turn on "Enabled by default". The CLI and VS Code share this setting. Keep in mind that it increases context usage, since the browser tools and their instructions are always loaded.^[1] In plan mode, a permission prompt appears before Claude records a GIF or opens a new tab.^[1]

Common workflows

Read console logs. Logs can be long, so say what you are looking for:

Open the dashboard page and check the console for any errors when
the page loads.

Upload files. Claude can attach a file from your machine to an upload field. A single upload can include up to 10 MB in total. Claude refuses files with multiple hard links, and it refuses credential files such as .env, .pem, .key and anything under .ssh. A permission rule that denies Read for a file also blocks its upload.^[1]

Record a GIF. The recording captures everything visible in the browser, including account details on logged-in pages. Review it before you share it outside your team.^[1]

When the connection fails

Work through these checks in order. Confirm in chrome://extensions that the extension is installed and enabled. Check that Chrome is running and that claude --version shows a current release. Then run /chrome and select "Reconnect extension". If that does not work, restart both Claude Code and Chrome.^[1]

On macOS, the native messaging host file for Chrome lives at ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json.^[1]

A project's own settings cannot turn Chrome integration on. If a project sets CLAUDE_CODE_ENABLE_CFC, Claude Code ignores it and prints this warning:

Claude Code ignored CLAUDE_CODE_ENABLE_CFC in this project's settings: a project can't turn on Claude in Chrome. To turn it on yourself, run /chrome or start with --chrome.

To turn it on, run /chrome or start with --chrome.^[1]

Other common problems:

• The browser stops responding. A JavaScript alert, confirm or prompt blocks browser events. Dismiss the dialog yourself, then ask Claude to continue.^[1]
• The connection drops in long sessions. The extension's service worker can go idle. Run /chrome and select "Reconnect extension".^[1]
• "Browser extension is not connected". The extension may not be installed or running, or it may be signed in to a different claude.ai account or organization. Run /status and check the Organization row against the extension.^[1]

Next step

The full details are in Anthropic's Claude Code documentation for Chrome.^[1]