# Humanized Browser

Operate your real Chrome browser in a **humanized** way from Cursor: natural mouse paths, typing cadence, and scroll pauses — so everyday tasks feel like a person, not a bot.

## Architecture

```
User (Cursor Agent)
    → MCP stdio (packages/mcp-server)
    → WebSocket 127.0.0.1:19501
    → Chrome extension (packages/extension)
    → Humanized click / type / scroll / navigate
```

| Layer | Role |
|-------|------|
| **Cursor Agent** | Plans the task and calls tools |
| **MCP server** | Tool surface, pairing token, localhost WS hub |
| **Chrome extension** | Snapshot + humanized execution on your tabs |

We do **not** rebuild a daily LLM agent loop — Cursor is the brain. This repo is the hand.

## Prerequisites

- Node.js 20+
- pnpm 9+ (`npm install -g pnpm`)
- Google Chrome (or Chromium)
- Cursor with Agent / MCP enabled

## Setup

### 1. Install & build

```bash
pnpm install
pnpm build
```

### 2. Load the extension

1. Open `chrome://extensions`
2. Enable **Developer mode**
3. **Load unpacked** → select `packages/extension/dist`
4. Keep the extension enabled

### 3. Pair with the MCP server

When Cursor starts the MCP server it writes:

- `~/.humanized-browser/credentials.json` — `{ token, port }`
- Token also printed on **stderr** of the MCP process

Open the **Humanized Browser** popup → paste token → set port (default `19501`) → **Connect**.  
Badge shows `ON` when connected.

### 4. Cursor MCP config

Project config is already at [`.cursor/mcp.json`](.cursor/mcp.json) (absolute path to the built MCP entry). After `pnpm build`, reload MCP in Cursor (Settings → MCP), or restart Cursor.

If you move the repo, update the `args` path in `.cursor/mcp.json` accordingly.

## Tools

| Tool | Purpose |
|------|---------|
| `browser_status` | Extension online? |
| `tabs_list` | List tabs |
| `navigate` | Open URL (humanized pause after load) |
| `snapshot` | Compressed page tree + `ref`s |
| `click` | Bezier mouse path + jitter |
| `type` | Variable key delays |
| `scroll` | Humanized scroll / scroll-into-view |
| `wait` | Delay or wait for selector/ref |
| `screenshot` | Viewport capture (prefer snapshot for actions) |

## Example prompt (in Cursor Agent)

> Use humanized-browser tools: open https://example.com, snapshot the page, and click the “More information…” link if present.

## Humanize defaults

Humanized timing is **on by default**. Popup **Fast mode** skips delays for debugging only — do not use it for real sites you care about.

## Security

- WebSocket hub binds to **127.0.0.1 only**
- Extension must present the pairing token
- No remote browser control in this MVP

## Packages

- `packages/shared` — protocol + humanize helpers
- `packages/mcp-server` — MCP stdio + WS hub
- `packages/extension` — MV3 execution plane

## End-to-end checklist

1. `pnpm build` succeeds
2. Extension loads from `packages/extension/dist` without errors
3. Cursor MCP shows `humanized-browser` connected
4. Popup Connect → status `connected` / badge `ON`
5. In Agent: call `browser_status` → connected
6. `navigate` → `snapshot` → `click`/`type` with visible humanized motion

## Out of scope (later)

- Cursor SDK headless runner
- Native Messaging instead of WS
- Domain allowlists / recording