# agent-in-chrome

[日本語](README.ja.md)

Two Chrome/Edge extensions that let an AI agent use your browser, plus the native host that
connects them to Claude Code, Codex, Devin or any other MCP client. They are open-source
reimplementations of Anthropic's "Claude in Chrome" and OpenAI's ChatGPT/Codex browser extension,
written from notes on how those extensions behave. No code, prompts or images were copied.

You bring the model. The side panels work with an Anthropic key, an OpenAI key, or any
OpenAI-compatible endpoint (DeepSeek, OrcaRouter, OpenRouter, Ollama, LM Studio). If you already
use a coding agent, you can skip the side panel and give that agent the browser over MCP.

<p>
  <img src="docs/images/claude-style-plan.png" width="360" alt="Claude-style side panel asking to approve a plan">
  <img src="docs/images/codex-style-approval.png" width="360" alt="Codex-style side panel asking for site access">
</p>

## The two extensions

**claude-compat** mirrors Claude in Chrome. The agent looks at screenshots and clicks by
coordinate, or by element refs from an accessibility tree. It works inside a tab group per
conversation. It has the same 23 tools with the same names and input schemas (`computer`,
`navigate`, `read_page`, `find`, `form_input`, `browser_batch`, ...), so prompts and tooling written
for the original also work here. The side panel adds plan approval, per-site permissions, saved
shortcuts with schedules, workflow recording ("Teach") and GIF export.

**codex-compat** mirrors the Codex browser extension. The extension itself does little. It hands
out tabs to agent sessions, passes Chrome DevTools Protocol commands through, and cleans up
scratch tabs when a task ends. The agent reads pages as accessibility text with numbered elements
and diffs between steps, which keeps token use low and works with text-only models. It can also
connect the side panel to a local `codex app-server`.

Both can be installed at the same time. The Claude-style one suits visual pages. The Codex-style
one is cheaper for text-heavy work like research and form filling.

## Install

You need Node.js 20 or newer and Chrome, Edge, Brave, Vivaldi or Opera (version 116+).

```sh
git clone https://github.com/youseiushida/agent-in-chrome
cd agent-in-chrome
npm install
npm run build
node native-host/dist/aic-install.mjs
```

`aic-install` registers the native messaging host for every browser it finds (`--browser edge` to
limit it, `--uninstall` to undo). Then open `chrome://extensions` or `edge://extensions`, turn on
developer mode and load these two folders with "Load unpacked":

- `extensions/claude-compat/dist`
- `extensions/codex-compat/dist`

Restart the browser once so it picks up the native host.

## Using the side panel

Click the extension icon (the Claude-style one also opens with Ctrl+E / ⌘E), pick a provider, paste
an API key and describe the task. Keys stay in `chrome.storage.local` and are only sent to the
provider you chose. For DeepSeek, choose "OpenAI-compatible" with base URL
`https://api.deepseek.com/v1` and model `deepseek-flash`.

The Claude-style panel starts in "Ask before acting": the agent proposes a plan, you approve it,
and it only works on the sites in that plan. "Act without asking" turns prompts off. In the
Codex-style panel the same switch is in settings as "Don't ask before using sites".

## Using it from Claude Code, Codex or Devin

`native-host/dist/aic-mcp.mjs` is an MCP server. Use `claude` for the Claude-style tools or
`codex` for the text-first tools.

```sh
# Claude Code
claude mcp add aic-browser -s user -- node /path/to/agent-in-chrome/native-host/dist/aic-mcp.mjs claude

# Devin CLI
devin mcp add -s user aic_browser -- node /path/to/agent-in-chrome/native-host/dist/aic-mcp.mjs codex
```

For Codex, add this to `~/.codex/config.toml`:

```toml
[mcp_servers.aic_browser]
command = "node"
args = ["/path/to/agent-in-chrome/native-host/dist/aic-mcp.mjs", "codex"]
tool_timeout_sec = 180
```

By default the Claude-style server asks before acting on a site. A small "AIC" window pops up in
the browser. To let the agent work without prompts, create `%APPDATA%\aic\config.json`
(`~/.aic/config.json` on macOS/Linux):

```json
{ "permissionMode": "skip_all_permission_checks", "autoApprove": true }
```

To keep the agent away from certain sites, list them under `blockedSites` in the same file (used by
the `codex` server) or in the Claude-style extension's options page (used by the `claude` server).
`aic-install` prints the exact commands for your machine. [docs/USAGE.md](docs/USAGE.md) covers the rest of the options.

## Compatibility with the official clients

`aic-install --claude-code-compat` makes the host listen on the pipe name the official Claude Code
browser integration looks for. `--codex-compat` does the same for the Codex desktop app's browser
runtime. In those modes the vendors' own clients can drive these extensions. Don't run them next
to the official extensions' hosts; they would fight over the same pipe.

## What is not here

Anything that depends on the vendors' accounts or servers is left out. That covers claude.ai
sign-in, Anthropic's server-side site safety check (replaced by a local blocklist), pairing with
Claude Desktop, and ChatGPT's hosted side chat. The Codex-style tools don't include WebMCP,
sign-in handoff or the virtual clipboard yet.

## Development

```sh
npm test           # unit tests (vitest), ~720 of them
npm run typecheck
npm run e2e        # launches Chromium with both extensions via Playwright
```

The MCP scenarios in `npm run e2e` need `aic-install --browser chrome,chromium` first. They pin
themselves to the test browser, so a browser you have open is not touched.

The code is split into packages. `protocol` holds the wire formats. `browser-core` holds CDP,
screenshots, input, tab groups and permissions. `claude-tools` has the 23 tools. `cdp-actions` has
the accessibility snapshot and the text-first tool set. `agent` holds the model providers and the
agent loop, and `ui` the React components. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) describes
the protocols. `analysis/` has the behavioural notes the implementation was written from (vendor
keys and client IDs are redacted).

## License

Apache-2.0. Not affiliated with Anthropic or OpenAI. "Claude", "Codex" and "ChatGPT" are their
trademarks and appear here only to say what this is compatible with.