# browser-ext

**Repository Path**: liufbox/browser-ext

## Basic Information

- **Project Name**: browser-ext
- **Description**: claude code 浏览器插件，以便claude code 可以通过打开浏览器、操作浏览器，获取内容
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Code Browser Agent

A browser extension + bridge server that allows Claude Code CLI to control a browser: extract page content, perform actions (click, type, scroll, etc.), and iterate in a loop for complex browser automation tasks.

## Architecture

```
Claude Code CLI ──HTTP REST──▶ Bridge Server (localhost:3147) ──WebSocket──▶ Browser Extension (MV3)
```

Three components:
1. **Browser Extension** - Chrome/Edge extension (Manifest V3) for DOM extraction and page automation
2. **Bridge Server** - Local Node.js WebSocket + HTTP server
3. **Claude Code** - Communicates via HTTP REST API to control the browser

## Quick Start

### 1. Install the Extension

#### Chrome
1. Open `chrome://extensions/`
2. Enable **Developer mode** (top right)
3. Click **Load unpacked**
4. Select the `extension/` directory

#### Edge
1. Open `edge://extensions/`
2. Enable **Developer mode** (left sidebar)
3. Click **Load unpacked**
4. Select the `extension/` directory

### 2. Start the Bridge Server

```bash
cd bridge-server
npm install
node server.js
```

The server will print connection info:
```
========================================
  Claude Browser Agent - Bridge Server
========================================
  Server:    http://127.0.0.1:3147
  WebSocket: ws://127.0.0.1:3147/ws
  Auth token: abc123def456...

  Use this token in all API requests:
  Authorization: Bearer abc123def456...
========================================
```

### 3. Verify Connection

```bash
# Copy the auth token from server output
TOKEN="abc123def456..."

# Check health
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:3147/api/v1/health
```

Expected response:
```json
{
  "status": "ok",
  "extensionConnected": true,
  "uptime": 123.456,
  "version": "1.0.0"
}
```

## API Reference

All requests require `Authorization: Bearer <token>` header.

### Sessions

**Create session**
```bash
curl -X POST http://127.0.0.1:3147/api/v1/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-session"}'
```

**List sessions**
```bash
curl http://127.0.0.1:3147/api/v1/sessions \
  -H "Authorization: Bearer $TOKEN"
```

**Delete session**
```bash
curl -X DELETE http://127.0.0.1:3147/api/v1/sessions/<session-id> \
  -H "Authorization: Bearer $TOKEN"
```

### Extract Page Content

```bash
curl -X POST http://127.0.0.1:3147/api/v1/sessions/<session-id>/extract \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

Response includes:
- `url` - Current page URL
- `title` - Page title
- `interactiveElements` - List of clickable/typable elements with ref numbers
- `textContent` - Visible text content
- `domTree` - Structured DOM representation

### Execute Actions

```bash
curl -X POST http://127.0.0.1:3147/api/v1/sessions/<session-id>/action \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "click",
    "args": { "selector": "button[type=\"submit\"]" }
  }'
```

#### Supported Commands

| Command | Args | Description |
|---------|------|-------------|
| `click` | `{ selector }` or `{ ref }` | Click an element |
| `type` | `{ selector, text }` or `{ ref, text }` | Type text into an input |
| `type` | `{ selector, text, enter: true }` | Type and press Enter |
| `hover` | `{ selector }` or `{ ref }` | Hover over an element |
| `scroll` | `{ direction: "down" }` or `{ x, y }` | Scroll the page |
| `select` | `{ selector, value }` | Select an option in a dropdown |
| `evaluate` | `{ code }` | Execute JS in the page |
| `wait` | `{ selector }` or `{ timeout: 3000 }` | Wait for element or time |
| `navigate` | `{ url }` | Navigate to a URL |
| `extract` | `{}` | Extract page content |

### Screenshot

```bash
curl -X POST http://127.0.0.1:3147/api/v1/sessions/<session-id>/screenshot \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"format": "jpeg", "quality": 80}'
```

### Open New Tab

```bash
curl -X POST http://127.0.0.1:3147/api/v1/tabs/open \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
```

## Usage with Claude Code

The typical workflow is an extract → analyze → act loop:

1. **Create a session**
2. **Extract** the current page content
3. Claude Code **analyzes** the DOM structure
4. Claude Code sends **action** commands (click, type, etc.)
5. **Extract** again to see the updated page
6. Repeat until the task is complete

### Example Claude Code workflow:

```
1. POST /api/v1/sessions → get sessionId
2. POST /api/v1/sessions/:id/extract → get page DOM
3. [Claude analyzes DOM, finds the login form]
4. POST /api/v1/sessions/:id/action { "command": "type", "args": { "selector": "#username", "text": "admin" } }
5. POST /api/v1/sessions/:id/action { "command": "type", "args": { "selector": "#password", "text": "secret", "enter": true } }
6. POST /api/v1/sessions/:id/extract → verify login succeeded
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `BRIDGE_PORT` | `3147` | Server port |
| `BRIDGE_HOST` | `127.0.0.1` | Bind address |

### Extension Settings

Open the extension popup to configure:
- **Server URL** - WebSocket URL (default: `ws://127.0.0.1:3147/ws`)

## File Structure

```
browser-ext/
├── extension/
│   ├── manifest.json           # Extension config (MV3)
│   ├── background.js           # Service worker
│   ├── content-script.js       # DOM extraction + actions
│   ├── offscreen.html          # Offscreen document shell
│   ├── offscreen.js            # WebSocket client
│   ├── popup/
│   │   ├── popup.html          # Status popup
│   │   └── popup.js            # Popup logic
│   └── icons/                  # Extension icons
├── bridge-server/
│   ├── package.json            # Node.js dependencies
│   ├── server.js               # HTTP + WebSocket server
│   ├── api.js                  # REST API routes
│   └── protocol.js             # Message protocol helpers
└── README.md
```

## Security

- Bridge server binds to `127.0.0.1` only (no external access)
- All API requests require Bearer token authentication
- WebSocket connections require token authentication
- Content scripts run in isolated worlds (cannot access page JS)

## Troubleshooting

**Extension not connecting:**
- Verify the bridge server is running: `curl http://127.0.0.1:3147/api/v1/health`
- Check the popup shows "Connected" status
- Verify the server URL in the popup matches the running server

**"Extension not connected" errors:**
- The extension's offscreen document may have been killed. Click the extension icon to re-create it.
- Check browser console for errors in `offscreen.js`

**Port already in use:**
```bash
# Windows
netstat -ano | findstr :3147
taskkill /PID <PID> /F

# macOS/Linux
lsof -ti:3147 | xargs kill
```

## License

MIT