Skip to main content
Glama

claude-has-hands

A guarded local bridge that lets AI coding CLIs drive your existing, signed-in Chrome. A Chrome MV3 extension and a native messaging host expose one set of browser_* tools over MCP (stdio and HTTP), a localhost REST API and a chh shell command, so Claude Code, Codex, Gemini CLI or any tool that can run a shell command can use the same browser.

Why

Browser automation frameworks start a fresh browser with no sessions, and sites with MFA or device trust block them. This project goes the other way. It works inside the browser you already use, with its cookies, extensions and device trust, and it never asks the agent for credentials. Signing in and passing MFA stay human steps: the agent waits while you do them.

The bridge is a local tool for one user. It is not a cloud browser service and not a test framework.

Related MCP server: browserpilot-mcp

Architecture

 Chrome (your profile)                       Native host (Node, spawned by Chrome)
┌─────────────────────────┐   native         ┌──────────────────────────────────────┐
│ MV3 extension           │   messaging      │ dispatcher (request/response match)  │
│  - CDP via chrome.debugger ◀──────────────▶ │ tool registry (zod schemas)          │
│  - DOM + MAIN-world capture│  (stdio)      │                                      │
└─────────────────────────┘                  │  Unix socket   REST 127.0.0.1:<port> │
                                             │  bridge.sock   Bearer token          │
                                             └───────┬──────────────┬───────────────┘
                                                     │              │
                                        mcp-server.js│     ┌────────┴─────────┬──────────────┐
                                        (direct MCP) │     │ mcp-adapter.js   │ chh CLI      │
                                                     │     │ MCP over stdio   │ curl wrapper │
                                                     │     │ or HTTP          │              │
                                                     ▼     ▼                  ▼              ▼
                                                  Claude Code            Codex, Gemini, shell tools
  • extension/ is the MV3 extension. Its service worker keeps the native host alive and runs each command through the Chrome DevTools Protocol and content scripts.

  • native-host/src/dispatcher.ts is the single command router. tool-registry.ts is the single source of truth for tool names, zod input schemas and result formatting. Every transport reads from it.

  • native-host/src/rest-server.ts is the localhost REST API (GET /v1/status, GET /v1/tools, POST /v1/call).

  • native-host/src/mcp-adapter.ts is an MCP server that forwards each tool call to the REST API. mcp-server.js is the older path that talks to the Unix socket directly.

  • bin/chh is a shell wrapper around the REST API for agents without MCP.

Install

Requirements: Google Chrome on macOS or Linux, Node.js 22.18 or later (the unit tests run TypeScript natively), npm. The chh CLI also needs curl and python3.

git clone https://github.com/isaacasamoah/claude-has-hands.git
cd claude-has-hands
npm ci
npm run build
  1. Open chrome://extensions, enable Developer mode and choose Load unpacked. Select the extension/ directory (not extension/dist/).

  2. Copy the extension ID and run ./scripts/install.sh <extension-id>. It builds the project, writes a launcher that records the absolute path of your Node binary (Chrome starts native hosts with a minimal PATH) and registers the native messaging host for that extension ID.

  3. Reload the extension. Chrome starts the native host, which writes bridge.json and a fresh bridge.token under ~/.claude/claude-has-hands/.

Connect an agent

Use the absolute path of this checkout in place of <repo>. Chrome and the extension must be running.

# Claude Code
claude mcp add claude-has-hands -- node <repo>/native-host/dist/mcp-adapter.js

# Codex
codex mcp add claude-has-hands -- node <repo>/native-host/dist/mcp-adapter.js

# Gemini CLI
gemini mcp add claude-has-hands node <repo>/native-host/dist/mcp-adapter.js

The adapter reads bridge.json and the token on every call, so it keeps working when the host restarts on a new port with a new token.

For any agent with a shell tool, use the CLI:

<repo>/bin/chh status
<repo>/bin/chh tools
<repo>/bin/chh call browser_navigate '{"url":"https://example.com"}'
<repo>/bin/chh call browser_survey '{}'

./scripts/install-cli.sh links chh and one browser_<tool> command per tool into ~/.local/bin.

Plain REST:

URL="$(jq -r .url ~/.claude/claude-has-hands/bridge.json)"
TOKEN="$(cat ~/.claude/claude-has-hands/bridge.token)"
curl -sS -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"tool":"browser_status","input":{}}' "${URL}/v1/call"

To serve MCP over HTTP, set CHH_MCP_HTTP_PORT (or CHH_MCP_TRANSPORT=http|both) when starting mcp-adapter.js. Clients must send the same bearer token as for REST.

Tools

The tool reference is generated from the registry: see docs/tools.md. It covers navigation and tabs, accessibility-tree and DOM inspection, click, type, select, scroll and key presses, screenshots and frame-sequence capture, console and network inspection, waits, file upload, JavaScript evaluation and batches. chh tools returns the full JSON Schema for each tool.

browser_console and browser_network read ring buffers filled by a capture script injected at document_start. Network capture stores method, URL, status and timing only, never request or response bodies. Pages opened before the extension started need a reload for full coverage.

Security model

Details and reporting instructions are in SECURITY.md. In short:

  • The REST server binds to 127.0.0.1 only.

  • Every request needs Authorization: Bearer <token>. The token is compared with crypto.timingSafeEqual after a length check.

  • Requests carrying a browser Origin other than localhost, 127.0.0.1 or [::1] get a 403, which blocks DNS-rebinding and cross-site requests from web pages. There is no CORS.

  • The token is regenerated every time the host starts. bridge.token, bridge.json and bridge.sock are mode 0600.

  • The Unix socket requires a token handshake. The HTTP MCP transport applies the same origin and bearer checks as REST.

  • Request bodies are capped at about 1 MB, matching Chrome's native messaging frame limit. Responses carry Cache-Control: no-store.

  • browser_navigate accepts only an allowlist of URL schemes.

The bridge does not read, store or replay passwords and does not bypass MFA. It can still see whatever the page shows: DOM reads, screenshots, console output and browser_eval results can contain sensitive data from a signed-in session.

Configuration

Variable

Purpose

CHH_BRIDGE_URL

Override the REST URL (default: read from bridge.json)

CHH_BRIDGE_TOKEN_FILE

Override the token path

CHH_BRIDGE_JSON

Override the discovery file path

CHH_BRIDGE_PORT

Pin the REST port (default: OS-assigned)

CHH_BRIDGE_REST=off

Disable the REST server; the host serves the Unix socket only

CHH_MCP_HTTP_PORT

Serve MCP over HTTP on this port

CHH_MCP_TRANSPORT

stdio (default), http or both

Reliability

Chrome starts the native host from the extension's MV3 service worker, and the host lives only as long as that worker. The worker pings the host over the native port about every 20 seconds, which resets Chrome's idle timer, and a chrome.alarms handler restarts the connection if the worker dies anyway. Each restart means a new port and a new token, which the adapter and chh pick up from bridge.json.

Limitations and non-goals

  • Chrome only, on macOS and Linux. Chrome for Testing and other browsers are untested.

  • Single user, single machine. There is no remote access, multi-user mode or cloud browser fallback.

  • The extension asks for <all_urls> and the debugger permission, and Chrome shows its debugging banner while attached. Connect only agents you trust with the whole browser session.

  • There is no per-site policy or action tiering. The calling agent or harness owns approval for actions such as submitting forms.

  • browser_gif returns a frame sequence, not an encoded GIF, because one native messaging message is capped near 1 MB.

  • No streaming events for browser_observe.

Development

npm run typecheck
npm test              # typecheck, then node --test test/unit/*.test.ts
npm run build         # typecheck, then esbuild into extension/dist and native-host/dist
npm run docs:tools    # regenerate docs/tools.md
npm run dev           # rebuild on change

Unit tests cover the wire protocol, dispatcher, REST and MCP transports, keepalive and the tool registry, and run without a browser. The declarative scenarios in test/scenarios/ and the fixture pages in test/ are for driving a real Chrome by hand and are not part of npm test.

Licence

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables remote AI agents to control a local, authenticated desktop browser over MCP through an outbound WebSocket bridge and Chrome extension, supporting tab management, navigation, page reading, clicking, typing, scrolling, screenshots, and JavaScript evaluation.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Codex or any MCP client to inspect and operate explicitly allowed browser tabs in paired Chromium profiles through a secure local-only bridge. Supports DOM snapshots with stable references, navigation, clicking, typing, scrolling, screenshots, and multiple sessions/profiles.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to interact with live Chrome and Chrome Dev sessions through MCP tools, including finding and focusing active tabs, evaluating JavaScript in tab DOMs or extension service workers, and capturing screenshots without remote-debugging consent modals.
      1
      MIT