# Claude Browser

Multiple persistent browser tabs inside VS Code, drivable by Claude over MCP.

Open GitHub in one editor group and a Claude terminal in another. Stay signed in across
restarts. Let Claude read and click the same page you are looking at, without leaving the
editor.

## What it does

- **Many tabs, not one.** Each browser tab is an editor tab, so it splits, drags between
  groups, and reopens where you left it.
- **Sessions persist.** Cookies and local storage survive a restart and are shared by
  every tab, so signing into Slack once is enough.
- **Sites that refuse to be framed still work.** GitHub, Slack and Google all send
  `X-Frame-Options: DENY`, which is why the built-in Simple Browser cannot show them.
- **Claude drives it.** The extension hosts an MCP endpoint with tools to list tabs,
  navigate, snapshot a page, click, type, and read the console.
- **It is a real DOM.** Not a video stream of a browser: input latency is native, text
  selection and the find widget work, and audio plays.

## Getting started

```
yarn install
yarn build
```

Press <kbd>F5</kbd> to launch an Extension Development Host, then run
**Claude Browser: Open Browser Tab** from the command palette.

To let Claude drive it, open a terminal in the same window and run `claude`. The extension
writes its endpoint into the workspace `.mcp.json`, so the tools are there already. Run
**Claude Browser: Show MCP Endpoint** if you would rather register it by hand.

## Commands

| Command | What it does |
| --- | --- |
| `Claude Browser: Open Browser Tab` | Opens a URL in a new tab. |
| `Claude Browser: Open Browser Tab to the Side` | Same, in the group beside the current one. |
| `Claude Browser: Open Bookmarked Site` | Picks from `claudeBrowser.bookmarks`. |
| `Claude Browser: Reload Active Tab` | Reloads the focused tab. |
| `Claude Browser: Zoom In` / `Zoom Out` / `Reset Zoom` | Scales the page only, not the editor. Remembered per site. |
| `Claude Browser: Open Active Tab in System Browser` | Hands the current URL to the OS. |
| `Claude Browser: Sign Out of Everything` | Clears stored cookies and mirrored storage. |
| `Claude Browser: Show MCP Endpoint` | Shows the endpoint URL and the `claude mcp add` command. |
| `Claude Browser: Show Log` | Opens the output channel. |

## Settings

| Setting | Default | Purpose |
| --- | --- | --- |
| `claudeBrowser.homepage` | `https://github.com` | Opened when no URL is given. |
| `claudeBrowser.bookmarks` | GitHub, Slack | Sites in the Bookmarks view. |
| `claudeBrowser.proxyPort` | `41998` | Loopback port for the proxy. Changing it resets page storage. |
| `claudeBrowser.mcpPort` | `41999` | Loopback port for the MCP endpoint. |
| `claudeBrowser.writeWorkspaceMcpConfig` | `true` | Write the endpoint into the workspace `.mcp.json`. |
| `claudeBrowser.allowScriptEvaluation` | `true` | Expose the `evaluate_script` tool. |
| `claudeBrowser.mirrorLocalStorage` | `true` | Copy each site's local storage into extension storage. |

## How it works, in one paragraph

A VS Code webview is a sandboxed iframe, and the sites worth keeping open refuse to be
framed. So the extension runs a local rewriting proxy: each site is served from its own
loopback origin such as `github.com.s.localhost:41998`, with the framing and transport
headers rewritten on the way through. Cookies never reach the browser at all; the proxy
holds them and re-attaches them upstream, which is the only way `__Host-` prefixed session
cookies can survive being served from a different origin. A small shim is injected into
every page to reroute its network calls, keep navigation on the proxy, and carry out
commands from MCP tools.

The details, and the things this approach cannot do, are in [docs/](docs/).

## Documentation

- [Architecture](docs/architecture.md) — the pieces and how they talk
- [Proxy](docs/proxy.md) — origin mapping, header rewriting, the page shim
- [Persistence](docs/persistence.md) — where sessions live and what survives what
- [MCP](docs/mcp.md) — the tools and how to connect
- [Security](docs/security.md) — the threat model and the request guard
- [Limitations](docs/limitations.md) — what does not work, and why
- [Development](docs/development.md) — building, testing, releasing