Agent Chrome

agentchrome

Let your coding agents use the Chrome you already use.

Install · Let your agent install it · What it does · Tools · Security

Agent Chrome is a Chrome extension and an MCP server that let coding agents use your real, signed-in Chrome profiles. It works with Claude Code, Codex, Gemini CLI, Antigravity, Grok, Muse, Cursor, opencode and any other MCP client. Each agent works in its own tab group, and a blue border and an animated cursor show what it is doing. It can take screenshots and record video clips, and you can connect several Chrome profiles at once. The server runs on Cloudflare, or locally on your machine.

What you see while an agent works. This clip was recorded by the extension itself (MP4).

If it's useful to you, please star the repo. It helps other people find it.

Install

You need Node.js 18 or newer and Google Chrome.

1. Run the installer

curl -fsSL https://agentchrome.dev/install | sh

In one pass, the installer:

1. Creates your account and saves the key to ~/.config/agentchrome/config.json with chmod 600.
2. Adds an MCP server named agentchrome to every agent it finds, in that agent's user-level config (table below).
3. Writes the agentchrome skill once, to ~/.agents/skills/agentchrome, and symlinks it into each agent's skills folder.
4. Unpacks the extension to ~/.agentchrome/extension.
5. Prints a pairing code and copies it to your clipboard.

To keep everything on your machine with no cloud at all, add --local. See Local mode.

2. Load the extension, once per Chrome profile

The installer opens chrome://extensions and shows the folder in Finder for you.

1. In chrome://extensions, turn on Developer mode.
2. Click Load unpacked and choose ~/.agentchrome/extension. Run agentchrome extension --path to print the full path.
3. Pin Agent Chrome, click it, paste the pairing code and press Connect.

To add another profile (Work, Personal, a client's), switch to that profile, load the same folder, and run agentchrome pair for a new code. Each profile appears as its own browser in list_browsers.

3. Use it

Ask any agent:

Use agentchrome to open news.ycombinator.com, screenshot it, and record a short clip scrolling the front page.

Or let your agent install it

Paste this into Claude Code, Codex or any other coding agent:

Install agentchrome for me by following https://github.com/ShadowWalker2014/agentchrome/blob/main/AGENT_INSTALL.md

The agent runs the installer, then tells you the one step only you can do: loading the extension in Chrome and pasting the code.

Use it from Claude.ai or ChatGPT

The server is a standard remote MCP server with OAuth, so chat apps can use it as a connector. You don't need the command line tool for this.

Claude (claude.ai, Claude Desktop, Cowork): open Customize > Connectors > Add custom connector, enter https://agentchrome.dev/mcp and press Connect.

ChatGPT: turn on Developer mode under Settings > Apps & Connectors > Advanced, then create a connector with the same URL and choose OAuth.

A sign-in page opens. Paste your account key, or press Create an account if you don't have one. Then ask in chat: "Connect my Chrome." The assistant calls pairing_code and walks you through loading the extension and pasting the code.

Where each agent is configured

The installer backs up every JSON or TOML file it edits as <file>.bak-agentchrome. The skill is linked into ~/.claude/skills, ~/.codex/skills, ~/.gemini/skills, ~/.gemini/antigravity/global_skills, ~/.cursor/skills and ~/.config/opencode/skills.

Gemini CLI note: Gemini turns off every MCP server in folders you haven't trusted, so gemini mcp list shows "Disabled" there. Trust the folder with /permissions inside Gemini, and the server turns on.

Pick agents, or use OAuth instead of a key

agentchrome install claude codex grok   # only these agents
agentchrome install --oauth             # no secret in config files; each agent signs in through the browser

With OAuth, agents that support MCP sign-in (Claude Code, Codex, Gemini CLI and others) open a sign-in page on first use. Paste your account key once (agentchrome key prints it) and the agent receives short-lived tokens, refreshed for 90 days.

Add it by hand

claude mcp add --scope user --transport http agentchrome https://agentchrome.dev/mcp \
  --header "Authorization: Bearer $(agentchrome key)"

codex mcp add agentchrome --url https://agentchrome.dev/mcp --bearer-token-env-var AGENT_CHROME_MCP_KEY

Any MCP client that speaks Streamable HTTP works. Use https://<server>/mcp with a bearer key, or point it at the URL and let OAuth discovery do the rest.

What it does

You can see what the agent is doing. A blue border goes around the page, a pill shows which agent is working with a Stop button, and the agent's own cursor glides to each target. The cursor turns into a hand over links and an I-beam over text, and carries the agent's logo and name. Your own mouse is never moved. Recordings look like a person using the page. record leaves out the border, the pill and the name tag, and draws a normal cursor (MP4). Pass cursor: "agent" to keep the indicators, or "hidden" for no cursor.

Every agent gets its own tab group. The popup lists which agents are active, and lets you pause one or stop them all. Setup takes a minute. Load the extension, paste the code from the installer, and the profile is connected.

It also handles the parts of real websites that usually break browser agents:

• Drag and drop works for native HTML5 drag events (Trello-style boards, file drop areas) and for pointer-based sliders and sortable lists.
• File uploads never open the native file picker. The agent can pass real file paths from your computer, or file contents. If a click tries to open the picker, it is held back and the agent is told to fill it.
• alert, confirm, prompt and "Leave site?" dialogs are reported to the agent instead of freezing it. A navigation the agent asks for leaves an unsaved page and says so.
• New tabs opened by a link join the agent's group, and downloads are reported in the result of the click that caused them.
• Pages that fail are explained: HTTP errors such as 404, DNS failures, crashed tabs, chrome:// pages that extensions can't touch, and file:// pages that need permission.
• If you press Cancel on Chrome's "started debugging this browser" bar, every agent stops and is told why.

CLI

Tools

The tool names match Claude in Chrome, so prompts and skills written for it work unchanged.

Feature parity

Local mode

curl -fsSL https://agentchrome.dev/install | sh -s -- --local
agentchrome serve --install    # starts the local server now and at every login (macOS)

The server listens only on 127.0.0.1:47823 and rejects requests from web pages. In the extension popup, open Server and set it to http://127.0.0.1:47823 before connecting. Screenshots and recordings are saved to ~/.agentchrome/artifacts.

Self-host on Cloudflare

git clone https://github.com/ShadowWalker2014/agentchrome && cd agentchrome
pnpm install
npx wrangler login
sh scripts/deploy-cloudflare.sh my-agentchrome

The script creates a D1 database, a KV namespace and an R2 bucket, runs the migrations, deploys the Worker with its Durable Object, sets a session secret, and prints your own install line (curl -fsSL https://my-agentchrome.<you>.workers.dev/install | sh). After you create your own account, set SIGNUP_MODE to "closed" so nobody else can sign up.

It runs comfortably on the Workers free tier for personal use. Durable Objects hibernate between calls, so an idle extension connection costs nothing.

Security

• Keys: account keys (acm_sk_…) and device tokens (acm_dt_…) are 256-bit random values. The server stores only their SHA-256 hashes. The local config file is chmod 600.
• Pairing: a browser joins your account only with a single-use 10-character code that expires after 15 minutes, created by someone who already holds the account key. Each Chrome profile gets its own device token, which you can revoke on its own.
• OAuth 2.1: PKCE (S256), dynamic client registration, refresh-token rotation and RFC 9728 discovery, using @cloudflare/workers-oauth-provider.
• Isolation: each account has its own Durable Object. MCP session ids are signed with HMAC and bound to the account, so one account cannot use another's session.
• Recordings: screenshots and videos you choose to save go to R2 behind unguessable 144-bit links and are deleted after 7 days.
• Control in the browser: the Stop button on the page or in the popup pauses every agent at once. You can also ask before each new site, block sites, and keep history access off, which is the default.
• Rate limits: sign-up, pairing and the sign-in page are rate-limited per IP address.
• Untrusted pages: the skill and the server instructions tell agents never to follow instructions found inside web pages.

Please report vulnerabilities through a private GitHub security advisory.

How it works

Claude Code ─┐                    ┌──────────────────────────────┐        ┌─ Chrome "Work" profile
Codex ───────┤  MCP over HTTPS    │ Cloudflare Worker            │  WSS   │   (extension, paired)
Gemini ──────┼──────────────────► │  /mcp  OAuth 2.1 or API key  │ ◄────► ├─ Chrome "Personal" profile
Grok, Muse … ┘                    │  Durable Object per account  │        └─ …
                                  └──────────────────────────────┘

The extension keeps one WebSocket open to the server. The server runs on Cloudflare Workers with one Durable Object per account. Each MCP session gets its own tab group in every paired profile. Tools that act on a page use the Chrome debugger protocol for input, screenshots, console and network logs. A small content script provides element refs, the accessibility tree, the overlay and the agent cursor.

Development

pnpm install
pnpm --filter @agentchrome/server exec wrangler d1 migrations apply agent-chrome-mcp --local
pnpm dev:server                         # Worker on http://127.0.0.1:8787
node scripts/build-all.mjs              # extension, CLI and public assets
pnpm test:e2e                           # end-to-end tests: real Chromium, the extension and the MCP SDK client
node --test tests/e2e/edge.test.mjs     # drag and drop, file pickers, dialogs, new tabs, downloads, errors
ACM_SERVER=https://… pnpm test:e2e      # the same suite against a deployed server
sh tests/e2e/local.sh                   # the same suite against local mode

See AGENTS.md for the architecture and the rules for contributors.

Star history

If agentchrome saves you time, please star it. Stars help other developers find the project.

License

MIT