Adam Ladachowski
84 lines
3.1 KiB
Markdown
84 lines
3.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Build & Development
|
|
|
|
```bash
|
|
npm install # Install dependencies
|
|
npx playwright install webkit # Install WebKit browser
|
|
npm run build # Compile TypeScript to dist/
|
|
npm run dev # Watch mode compilation
|
|
npm start # Run the CLI (after build)
|
|
```
|
|
|
|
## Lint, Format & Typecheck
|
|
|
|
```bash
|
|
npm run check # Run all checks (lint + format)
|
|
npm run fix # Fix all auto-fixable issues
|
|
npm run lint # Lint only
|
|
npm run lint:fix # Lint with autofix
|
|
npm run format # Check formatting
|
|
npm run format:fix # Fix formatting
|
|
npm run typecheck # TypeScript type checking
|
|
```
|
|
|
|
## Code Style
|
|
|
|
- **Short methods**: Keep methods under 20 lines. Extract logic into focused helper methods.
|
|
- **Single responsibility**: Each class handles one concern. Split large classes by domain.
|
|
- **Class structure**:
|
|
- `ClaudeBrowser` - browser lifecycle and page interactions
|
|
- `BrowserServer` - HTTP server and request handling
|
|
- `Logger` (planned) - colored console output
|
|
- **Naming**: Commands use `verbNoun` pattern (e.g., `getCookies`, `setStorage`).
|
|
- **Types**: All commands in discriminated union. Add new commands to `BrowserCommand` type.
|
|
|
|
## Architecture
|
|
|
|
This is a TypeScript library providing headless browser automation via Playwright WebKit. It has three modes of operation:
|
|
|
|
1. **CLI** (`src/cli.ts`) - Direct command-line usage for screenshots, clicking, typing, and querying
|
|
2. **Server** (`src/server.ts`) - HTTP server accepting JSON commands via POST requests
|
|
3. **Library** (`src/index.ts`) - Programmatic API via `ClaudeBrowser` class
|
|
|
|
### Core Components
|
|
|
|
- **ClaudeBrowser** (`src/browser.ts`) - Main class wrapping Playwright WebKit. Handles browser lifecycle, navigation, and all DOM interactions. Uses `executeCommand()` to process typed command objects.
|
|
- **BrowserServer** (`src/server.ts`) - HTTP server that wraps ClaudeBrowser. Accepts JSON POST requests and returns JSON responses. CORS-enabled.
|
|
- **Types** (`src/types.ts`) - Discriminated union of command types (`BrowserCommand`) and response types (`CommandResponse`).
|
|
|
|
### Command Flow
|
|
|
|
Commands are typed objects with a `cmd` discriminator:
|
|
```typescript
|
|
{ cmd: 'goto', url: string }
|
|
{ cmd: 'click', selector: string }
|
|
{ cmd: 'type', selector: string, text: string }
|
|
{ cmd: 'query', selector: string }
|
|
// etc.
|
|
```
|
|
|
|
All commands return `{ ok: true, ...data }` or `{ ok: false, error: string }`.
|
|
|
|
## CLI Options
|
|
|
|
Key flags: `-s <port>` (server mode), `-q <selector>` (query), `-c <selector>` (click), `-t <sel>=<text>` (type), `-i` (interactive), `--headed` (visible browser).
|
|
|
|
## Screenshots
|
|
|
|
Save screenshots to `screenshots/` directory:
|
|
```bash
|
|
curl localhost:13373 -d '{"cmd":"screenshot","path":"screenshots/page.png"}'
|
|
```
|
|
|
|
## MCP Server
|
|
|
|
Run as MCP server for Claude Code integration:
|
|
```bash
|
|
browse-mcp
|
|
```
|
|
|
|
The MCP server (`src/mcp.ts`) exposes all browser commands as tools. It uses stdio transport and auto-launches the browser on first command.
|