Files

T

Adam Ladachowski eccc03ee7a 💬 Commit message: Update 2026-02-06 20:28:30, 13 files, 1401 lines

📁 Files changed: 13
📝 Lines changed: 1401

  • .gitignore
  • CLAUDE.md
  • PLAN.md
  • README.md
  • TODO.md
  • package-lock.json
  • package.json
  • browser.ts
  • cli.ts
  • index.ts
  • server.ts
  • types.ts
  • tsconfig.json

2026-02-06 20:28:30 +01:00

1.8 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Development

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)

Architecture

This is a TypeScript library providing headless browser automation via Playwright WebKit. It has three modes of operation:

CLI (src/cli.ts) - Direct command-line usage for screenshots, clicking, typing, and querying
Server (src/server.ts) - HTTP server accepting JSON commands via POST requests
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:

{ 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).

1.8 KiB Raw Blame History