# noemica-io/open-claude-in-chrome architecture

> Architecture diagram of the GitHub repository noemica-io/open-claude-in-chrome, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/noemica-io/open-claude-in-chrome
- Repository: https://github.com/noemica-io/open-claude-in-chrome

## Overview

Open Claude in Chrome exposes browser automation to Claude Code through an MCP server, a native-messaging bridge, and a Chromium extension. The main workflow dispatches tool requests to the extension, which operates on browser tabs and returns results. Optional code mode runs model-written code in a sandbox and routes tool callbacks through the upstream server. The extension also humanizes actions and supports imitation-learning recordings and audits. The tree includes a separate REAL browser-agent environment; its unsampled subsystems are shown cautiously, with links only where the index documents imports.

Main entry points: [`extension/background.js`](https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/background.js) (Extension dispatcher), [`host/codemode/common.js`](https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/codemode/common.js) (Code-mode plumbing), [`REAL/src/agisdk/REAL/browsergym/core/env.py`](https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/core/env.py) (Browser task environment), [`host/mcp-server.js`](https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/mcp-server.js) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["MCP and host bridge"]
  node_mcp["MCP server<br/>[mcp-server.js]"]
  node_definitions["Tool definitions"]
  node_runtime["Tool runtime<br/>[tool-runtime.js]"]
  node_native["Native host<br/>[native-host.js]"]
  node_endpoint["Browser endpoint<br/>[endpoint.js]"]
end

subgraph group_extension["Browser automation"]
  node_extension_bg["Extension dispatcher<br/>[background.js]"]
  node_humanize["Action humanizer<br/>[index.js]"]
  node_cursor["Cursor planner<br/>[cursor.js]"]
  node_rng["Seeded randomness<br/>[rng.js]"]
end

subgraph group_recording["Recording and audit"]
  node_rec_capture["Trace capture<br/>[capture.js]"]
  node_rec_offscreen["Recording processor<br/>[offscreen.js]"]
  node_transcribe["Audio transcription<br/>[transcribe.js]"]
  node_rec_options["Recording viewer<br/>[options.js]"]
  node_audit[("Session audit<br/>[index.js]")]
end

subgraph group_codemode["Sandboxed code mode"]
  node_codemode["Code-mode server<br/>[server-codemode.js]"]
  node_hybrid["Hybrid server<br/>[server-hybrid.js]"]
  node_common["Code-mode plumbing<br/>[common.js]"]
  node_worker["Sandbox worker<br/>[worker.js]"]
end

subgraph group_real["REAL agent environment"]
  node_real_env["Browser task environment<br/>[env.py]"]
  node_real_observation["Observation builder<br/>[observation.py]"]
  node_real_actions["Action execution<br/>[highlevel.py]"]
  node_real_parser["Action parser<br/>[parsers.py]"]
  node_real_tasks["Task definitions<br/>[task.py]"]
  node_real_loop["Experiment loop<br/>[loop.py]"]
  node_real_agent["Demo agent<br/>[basic_agent.py]"]
  node_real_obs_utils["Observation utilities<br/>[obs.py]"]
end

node_claude(("Claude Code"))
node_browser["Chromium browser"]

node_claude -->|"stdio MCP"| node_mcp
node_mcp -->|"registers tools"| node_definitions
node_mcp -.->|"dispatches tools"| node_runtime
node_runtime -.->|"TCP requests"| node_native
node_native -->|"routes bridge"| node_endpoint
node_endpoint -->|"TCP bridge"| node_extension_bg
node_extension_bg -->|"controls tabs"| node_browser
node_extension_bg -->|"requests plans"| node_humanize
node_humanize -->|"plans movement"| node_cursor
node_humanize -->|"samples randomness"| node_rng
node_cursor -->|"uses distributions"| node_rng
node_extension_bg -->|"records activity"| node_audit
node_rec_options -->|"validates key"| node_transcribe
node_rec_offscreen -->|"transcribes audio"| node_transcribe
node_rec_options -->|"shows audit data"| node_audit
node_claude -->|"stdio MCP"| node_hybrid
node_claude -->|"stdio MCP"| node_codemode
node_codemode -->|"starts plumbing"| node_common
node_hybrid -->|"starts plumbing"| node_common
node_common -->|"runs sandbox"| node_worker
node_worker -->|"tool callbacks"| node_common
node_real_env -->|"builds observations"| node_real_observation
node_real_env -->|"executes actions"| node_real_actions
node_real_env -->|"sets up task"| node_real_tasks
node_real_actions -->|"uses parser"| node_real_parser
node_real_loop -->|"uses agent"| node_real_agent
node_real_agent -->|"imports actions"| node_real_actions
node_real_agent -->|"imports utilities"| node_real_obs_utils

click node_mcp "https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/mcp-server.js"
click node_definitions "https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/tool-definitions.js"
click node_runtime "https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/tool-runtime.js"
click node_native "https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/native-host.js"
click node_endpoint "https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/endpoint.js"
click node_extension_bg "https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/background.js"
click node_humanize "https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/humanize/index.js"
click node_cursor "https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/humanize/cursor.js"
click node_rng "https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/humanize/rng.js"
click node_rec_capture "https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/recorder/capture.js"
click node_rec_offscreen "https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/recorder/offscreen.js"
click node_transcribe "https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/recorder/transcribe.js"
click node_rec_options "https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/recorder/options.js"
click node_audit "https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/audit/index.js"
click node_codemode "https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/codemode/server-codemode.js"
click node_hybrid "https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/codemode/server-hybrid.js"
click node_common "https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/codemode/common.js"
click node_worker "https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/codemode/worker/worker.js"
click node_real_env "https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/core/env.py"
click node_real_observation "https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/core/observation.py"
click node_real_actions "https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/core/action/highlevel.py"
click node_real_parser "https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/core/action/parsers.py"
click node_real_tasks "https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/core/task.py"
click node_real_loop "https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/experiments/loop.py"
click node_real_agent "https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/demo_agent/basic_agent.py"
click node_real_obs_utils "https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/utils/obs.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_definitions,node_runtime,node_native,node_endpoint,node_browser toneBlue
class node_extension_bg,node_humanize,node_cursor,node_rng toneAmber
class node_rec_capture,node_rec_offscreen,node_transcribe,node_rec_options,node_audit toneMint
class node_codemode,node_hybrid,node_common,node_worker toneRose
class node_real_env,node_real_observation,node_real_actions,node_real_parser,node_real_tasks,node_real_loop,node_real_agent,node_real_obs_utils,node_claude toneIndigo
```

## Components

### MCP and host bridge

- [MCP server](https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/mcp-server.js): `host/mcp-server.js`
- [Tool definitions](https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/tool-definitions.js): `host/tool-definitions.js`
- [Tool runtime](https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/tool-runtime.js): `host/tool-runtime.js`
- [Native host](https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/native-host.js): `host/native-host.js`
- [Browser endpoint](https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/endpoint.js): `host/endpoint.js`

### Browser automation

- [Extension dispatcher](https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/background.js): `extension/background.js`
- [Action humanizer](https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/humanize/index.js): `extension/humanize/index.js`
- [Cursor planner](https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/humanize/cursor.js): `extension/humanize/cursor.js`
- [Seeded randomness](https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/humanize/rng.js): `extension/humanize/rng.js`

### Recording and audit

- [Trace capture](https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/recorder/capture.js): `extension/recorder/capture.js`
- [Recording processor](https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/recorder/offscreen.js): `extension/recorder/offscreen.js`
- [Audio transcription](https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/recorder/transcribe.js): `extension/recorder/transcribe.js`
- [Recording viewer](https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/recorder/options.js): `extension/recorder/options.js`
- [Session audit](https://github.com/noemica-io/open-claude-in-chrome/blob/main/extension/audit/index.js): `extension/audit/index.js`

### Sandboxed code mode

- [Code-mode server](https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/codemode/server-codemode.js): `host/codemode/server-codemode.js`
- [Hybrid server](https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/codemode/server-hybrid.js): `host/codemode/server-hybrid.js`
- [Code-mode plumbing](https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/codemode/common.js): `host/codemode/common.js`
- [Sandbox worker](https://github.com/noemica-io/open-claude-in-chrome/blob/main/host/codemode/worker/worker.js): `host/codemode/worker/worker.js`

### REAL agent environment

- [Browser task environment](https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/core/env.py): `REAL/src/agisdk/REAL/browsergym/core/env.py`
- [Observation builder](https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/core/observation.py): `REAL/src/agisdk/REAL/browsergym/core/observation.py`
- [Action execution](https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/core/action/highlevel.py): `REAL/src/agisdk/REAL/browsergym/core/action/highlevel.py`
- [Action parser](https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/core/action/parsers.py): `REAL/src/agisdk/REAL/browsergym/core/action/parsers.py`
- [Task definitions](https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/core/task.py): `REAL/src/agisdk/REAL/browsergym/core/task.py`
- [Experiment loop](https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/experiments/loop.py): `REAL/src/agisdk/REAL/browsergym/experiments/loop.py`
- [Demo agent](https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/demo_agent/basic_agent.py): `REAL/src/agisdk/REAL/demo_agent/basic_agent.py`
- [Observation utilities](https://github.com/noemica-io/open-claude-in-chrome/blob/main/REAL/src/agisdk/REAL/browsergym/utils/obs.py): `REAL/src/agisdk/REAL/browsergym/utils/obs.py`

### Other components

- **Claude Code**
- **Chromium browser**

## Connections

- Claude Code → MCP server: stdio MCP
- MCP server → Tool definitions: registers tools (evidence: `host/tool-definitions.js`)
- MCP server → Tool runtime: dispatches tools
- Tool runtime → Native host: TCP requests
- Native host → Browser endpoint: routes bridge (evidence: `host/native-host.js`)
- Browser endpoint → Extension dispatcher: TCP bridge
- Extension dispatcher → Chromium browser: controls tabs
- Extension dispatcher → Action humanizer: requests plans (evidence: `extension/background.js`)
- Action humanizer → Cursor planner: plans movement (evidence: `extension/humanize/index.js`)
- Action humanizer → Seeded randomness: samples randomness (evidence: `extension/humanize/index.js`)
- Cursor planner → Seeded randomness: uses distributions (evidence: `extension/humanize/cursor.js`)
- Extension dispatcher → Session audit: records activity (evidence: `extension/background.js`)
- Recording viewer → Audio transcription: validates key (evidence: `extension/recorder/options.js`)
- Recording processor → Audio transcription: transcribes audio (evidence: `extension/recorder/offscreen.js`)
- Recording viewer → Session audit: shows audit data (evidence: `extension/recorder/options.js`)
- Claude Code → Hybrid server: stdio MCP
- Claude Code → Code-mode server: stdio MCP
- Code-mode server → Code-mode plumbing: starts plumbing (evidence: `host/codemode/server-codemode.js`)
- Hybrid server → Code-mode plumbing: starts plumbing (evidence: `host/codemode/server-hybrid.js`)
- Code-mode plumbing → Sandbox worker: runs sandbox (evidence: `host/codemode/common.js`)
- Sandbox worker → Code-mode plumbing: tool callbacks
- Browser task environment → Observation builder: builds observations (evidence: `REAL/src/agisdk/REAL/browsergym/core/env.py`)
- Browser task environment → Action execution: executes actions (evidence: `REAL/src/agisdk/REAL/browsergym/core/env.py`)
- Browser task environment → Task definitions: sets up task (evidence: `REAL/src/agisdk/REAL/browsergym/core/env.py`)
- Action execution → Action parser: uses parser (evidence: `REAL/src/agisdk/REAL/browsergym/core/action/highlevel.py`)
- Experiment loop → Demo agent: uses agent (evidence: `REAL/src/agisdk/REAL/browsergym/experiments/loop.py`)
- Demo agent → Action execution: imports actions (evidence: `REAL/src/agisdk/REAL/demo_agent/basic_agent.py`)
- Demo agent → Observation utilities: imports utilities (evidence: `REAL/src/agisdk/REAL/demo_agent/basic_agent.py`)
