Claude Code in Chrome: Browser Automation From the CLI

The first time I asked Claude to check a form on my local server, it opened a tab, filled the form with invalid data, read the validation errors off the page, and told me which of the three messages was wrong. Then I asked it to check something in a web app I was signed into, and it just did — because it was my browser, with my session, not a headless one it had to authenticate separately.

That is the whole design and the whole thing to think about. This post covers what sharing browser state actually means, how to connect and what enabling it by default costs you in context, the plan-mode split between reading and acting, the file-upload restrictions, the authentication configurations that silently disable the feature, and the two failures you will hit in a long session.

It is your browser, with your sessions

Claude opens new tabs for browser tasks in a visible Chrome window, in real time, and shares your browser's login state. That is why it can draft in a Google Doc, read your Notion, or click through an internal dashboard with no API connector and no credentials configured anywhere. When it hits a login page or a CAPTCHA it stops and asks you to handle that part manually.

The tabs it opens are collected into a Chrome tab group tied to your session, and what happens to that group when the session ends depends on how it ends. Clearing the conversation closes the group including open pages, unless work that survives the clear is still running. Switching sessions, exiting, or clearing while such work runs closes the group only if it holds nothing but empty new tabs — so pages you might still be reading stay open.

Connecting, and what always-on costs

One flag starts a session with the browser attached, and a command manages everything else — status, permissions, reconnecting, and choosing which browser when more than one is connected. Site-level permissions are inherited from the Chrome extension rather than configured in Claude Code, so restricting which sites Claude may browse, click and type on happens in the extension's own settings.

# Launch with the browser attached.
claude --chrome

/chrome     # status, permissions, reconnect, pick a browser
            # Working when the panel shows:
            #   Status: Enabled
            #   Extension: Installed
            # "Enabled by default" removes the need for the flag

# Enabling by default increases context usage, because the
# browser tools are then always loaded. If your context budget
# gets tighter, turn it off and use the flag when you need it.

# Requires the Claude in Chrome extension 1.0.36 or later, and
# a direct Anthropic plan. Works in Chrome, Edge, and detected
# in Brave, Arc, Vivaldi and Opera. NOT supported under WSL.

Plan mode splits by side effect

The plan-mode behaviour here is more carefully drawn than most people notice, and it is a good model for how a read-only mode should treat a tool that can do both. Reading a page costs nothing and prompts for nothing; changing anything prompts. The interesting part is the exceptions, where a call that is normally read-only becomes state-changing because of one input flag.

# In plan mode the split is by side effect, not by tool.

# Runs with NO permission prompt:
    read_page          get_page_text      find
    reading console messages
    reading network requests
    taking a screenshot

# Prompts for approval:
    clicks             typing             navigation
    tab and window management
    recording a GIF

# The catch: an otherwise read-only call ALSO prompts when it
# sets a state-changing flag —
#     createIfEmpty on the tabs context call
#     clear on the console and network readers
#     save_to_disk on a screenshot
#
# A batch call runs without a prompt only when EVERY action
# inside it is read-only.

What it is genuinely good for

The value is not browser automation on its own — there are better tools for that if automation is all you want. It is chaining a browser action to a coding task in one workflow, without switching context or writing a test harness for something you are going to do once.

Four shapes that pay off:

File uploads, and their three limits

Claude can attach files from your machine to upload fields on a page — it reads the file and sends the contents to the browser, so this works in remote sessions too. Three restrictions apply, and the third is the one that catches people:

• Permissions carry over: Claude can upload a file only when the session is allowed to read it, so a read deny rule blocks uploading it too.
• A single upload can include up to 10 MB of files in total.
• Files with multiple hard links are refused, which is common inside package-manager stores. Copy the file and upload the copy.

Where it is silently unavailable

This is the section worth reading before you conclude something is broken, because none of these produce an error that explains itself. The common thread is authentication: the browser extension cannot authenticate with an API key or a long-lived token, so a session using either keeps the integration off even when you explicitly ask for it.

# Configurations where Chrome integration is off, and the
# reason is authentication rather than anything you configured.

# An API key, or a long-lived token from claude setup-token:
#   Claude Code keeps Chrome integration OFF even when you pass
#   --chrome, because the browser extension cannot authenticate
#   with those credentials. (Before v2.1.216 these sessions
#   could enable it, and every connection failed with a 403.)

# Third-party providers — Bedrock, Google Cloud's Agent
# Platform, Microsoft Foundry:
#   not available. If you reach Claude only through one of
#   those, you need a separate claude.ai account for this.

# Windows Subsystem for Linux:
#   not supported at all.

# Organisation policy:
#   a deniedMcpServers entry for claude-in-chrome suppresses
#   even the install prompt.

The two failures you will actually hit

Setting aside first-install issues, long sessions fail in a small number of predictable ways:

• The extension's service worker goes idle during an extended session and the connection breaks. Reconnect from the chrome command; nothing is lost.
• A JavaScript dialog — an alert, confirm or prompt — blocks the page and prevents Claude from receiving commands at all. Dismiss it manually and tell Claude to continue.
• On the very first enable, Claude Code installs a native messaging host configuration file that Chrome reads at startup, so if the extension is not detected on the first attempt, restart Chrome.
• Claude Code opens the connect tab only on that first install — it does not reopen it when a later session rewrites the configuration, such as after switching builds or config directories.

Treat this as a browser that a colleague is driving while you watch, because that is functionally what it is: your session, your logins, your tabs, in a window you can see. That framing gets the two important habits right on its own — you review a recording before sharing it, and you leave it off by default rather than always loaded, turning it on for the task that needs it. Both are cheap, and both matter more the more useful you find it.