Claude Code with Chrome: set up browser automation from the terminal

Claude Code works with Chrome through the Claude in Chrome browser extension: install the extension, start Claude Code with claude --chrome, and Claude can open tabs, click, type, read console errors and take screenshots in your real browser. It uses your existing login state, so it can reach any site you are already signed into, and it pauses for you to handle logins and CAPTCHAs.

This guide covers setup, what the integration is good for, permissions and the common fixes. All facts come from the official Use Claude Code with Chrome page, read on 24 October 2026.

What does Claude Code Chrome integration do?

It lets you chain browser actions with coding tasks in one session. Build a feature, then ask Claude to open it in the browser and check it, without switching tools. Browser actions run in a visible Chrome window, so you can watch what happens.

The docs list these capabilities:

• Live debugging: read console errors and DOM state, then fix the code that caused them.
• Design verification: build a UI from a mock, then check it in the browser.
• Web app testing: form validation, visual regressions, user flows.
• Authenticated web apps: work in Google Docs, Gmail, Notion or any app you are logged into, without API connectors.
• Data extraction: pull structured data from pages and save it locally.
• Task automation: data entry, form filling, multi-site workflows.
• File uploads: attach files from your machine to upload fields.
• Session recording: record interactions as GIFs.

Claude collects the tabs it opens into a Chrome tab group tied to your session. Typing /clear closes that group, unless work that survives the clear is still running; exiting or switching sessions closes it only if it holds nothing but empty new tabs.

What do you need before you start?

The prerequisites from the docs:

Two limits catch people out. First, Chrome integration "isn't supported in Windows Subsystem for Linux (WSL)." Second, if you authenticate with an API key or a long-lived token from claude setup-token, Claude Code keeps Chrome integration off "even when you pass --chrome." It is also not available through Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry; the docs say you need a separate claude.ai account in that case.

In Enterprise organizations with HIPAA enabled, Claude in Chrome is off by default and an Owner can turn it on in organization settings.

How do you set up Claude Code with Chrome?

1. Install the Claude in Chrome extension from the Chrome Web Store and sign in.
2. Start Claude Code with the flag:

claude --chrome

3. The first launch shows a one-time dialog explaining how site permissions work. Press Enter.
4. Ask Claude to use the browser. The docs use this example:

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

When Claude asks before a browser action, the dialog starts with "Claude in Chrome wants to" and offers to allow all actions on that site for the session.

If you skip the flag and Claude needs a browser anyway, Claude Code can show a prompt titled "Claude wants to use your browser" with three choices: Install extension, Not now and Don't ask again. It asks at most once per session.

Run /chrome at any time to check status, manage permissions, reconnect, or pick which connected browser to use. The integration is working when the panel shows "Status: Enabled" and "Extension: Installed."

How do you turn Chrome on by default?

Run /chrome and select Enabled by default. In the VS Code extension, type /chrome in the prompt box and turn on the same switch. The two share one setting.

There is a cost. The docs note that enabling Chrome by default "increases context usage since the browser tools and their instructions are always loaded." If you notice that, turn it off and connect only when needed with --chrome, or type @browser in the VS Code prompt box.

A safety detail: a project cannot switch Chrome on for you. If a repository's .claude/settings.json sets CLAUDE_CODE_ENABLE_CFC, Claude Code ignores it and warns you, because "a repository you check out must not be able to connect Claude to your browser."

How do permissions work in the browser?

Site-level permissions come from the Chrome extension. You manage which sites Claude can browse, click and type on in the extension's settings, not in Claude Code.

A few rules worth knowing:

• In plan mode, Claude asks before it records a GIF, opens a new tab or runs a shortcut.
• File uploads follow your Claude Code read permissions. If a rule denies Read on a file, Claude can't upload it either.
• A single upload can include up to 10 MB of files in total.
• Claude refuses to upload files with credential-style names or folders, such as .env, .pem or .key files, or anything under .ssh (Claude Code v2.1.293 or later).

GIF recordings capture everything visible, "including account details on logged-in pages," so review them before sharing. See the permissions guide for how Claude Code rules work in general.

What are good prompts for Claude Code in Chrome?

These are adapted from the workflows in the docs. Treat them as starting points:

I just updated the login form validation. Open localhost:3000,
submit the form with invalid data, and check that the error
messages appear correctly.

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

Go to the product listings page and extract the name, price and
availability for each item. Save the results as a CSV file.

For console debugging, the docs advise telling Claude which patterns to look for "rather than asking for all console output, since logs can be verbose." To see every browser tool available, run /mcp, select claude-in-chrome, then View tools.

If you want scripted, repeatable browser tests rather than an agent driving your own browser, compare the webapp-testing skill or the Playwright CLI skill.

How do you fix Chrome connection problems?

Start with the docs' checklist when the extension is not detected:

1. Check the extension is installed and enabled at chrome://extensions.
2. Run claude --version to confirm Claude Code is current.
3. Make sure Chrome is running.
4. Run /chrome and select "Reconnect extension."
5. Restart both Claude Code and Chrome.

On the first enable, Claude Code installs a native messaging host file that Chrome reads at startup, so a Chrome restart often fixes a first-time failure. On macOS the Chrome copy lives at ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json.

Common errors and fixes:

If you belong to several claude.ai organizations, run /status and check the Organization row; the extension must match it.

Keeping browser prompts you reuse

Browser checks tend to repeat: the same smoke test after each deploy, the same console sweep, the same form run. Kipt keeps prompts like these as Markdown in a private GitHub repo you own, with {{name}} or {{name:default}} blanks for the URL or page, and Cmd+K search to find them again.

For a deeper look at the extension itself, including shortcuts and scheduling, see Anthropic's Get started with Claude in Chrome help article.