browser-automation: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

@popoverai/browser-automation ships the agentic-demo CLI and library: narrated demo videos from agent-browser flows. A steps file (agent-browser commands plus a narration sentence per step) goes in; an mp4 comes out. agent-browser owns the browser (local Chrome, --cdp, or a cloud provider); the AI SDK owns narration; ffmpeg stitches.

It began as a fork of @browserbasehq/mcp-server-browserbase and carried a Stagehand MCP server until agent-browser proved the better agentic interface; that surface was removed (see CHANGELOG 0.14.0). There is no MCP server, no Stagehand, no Browserbase session management, no Docker image.

Single package, no workspace — alias/agentic-demo/ is the one exception, and it is a name, not a package: one file, no build, no tests, published separately (see Releases). TypeScript, ESM, Node 22+ (ai@7 sets the floor; agent-browser itself prefers 24 but runs on 22).

What's worth doing

We are a pre-revenue startup. Work earns its place by changing something for a person using the product, or by unblocking work that does.

The common miss is insurance against futures nobody has chosen — portability away from a platform we have no plan to leave, resilience at a scale we have not reached, an abstraction over a second implementation that does not exist. The cost lands now; the benefit waits on a decision no one has made. A working system coupled to its platform is not a problem.

Before proposing work — a fix, a refactor, a ticket, a review finding — name who is affected today, at our scale, on the stack we run. If you can't, report it as an observation rather than a problem.

Layout

• src/cli.ts — the agentic-demo binary: record (default), validate, guide, schema, example
• src/stepsFile.ts — the steps-file schema (zod/v4), its JSON Schema, and the starter example; the single source of truth for the input format
• src/agentBrowserClient.ts — spawn-based wrapper over the agent-browser CLI (batch via stdin JSON, stream status/enable/disable)
• src/agentBrowserRecorder.ts — captures the daemon's viewport stream, runs each step as one agent-browser batch --bail, builds the timeline
• src/render.ts — per-segment narration + ffmpeg encode, concat; segment length is max(video, audio)
• src/speech.ts — narration through the AI SDK's generateSpeech, or a pure-JS silent WAV when no speech is configured
• src/speechProviders.ts — CLI-side --tts <provider[:model]> resolution; openai, elevenlabs, hume, deepgram are bundled, and so is the AI Gateway, which comes from ai itself (@ai-sdk/gateway is not importable under pnpm)
• src/speechEndpoint.ts — --tts <url>: a speech model that asks an HTTP endpoint for each line, so the recording machine holds no provider key. The request it sends is a public contract, documented in README.md → "Voice endpoint"
• src/timeline.ts — CapturedFrame / TimelineEntry shared types
• SKILL.md — the agent-facing guide, printed by agentic-demo guide; shipped in the package so it always matches the binary
• README.md — the npm page of both packages, in two parts. The top is for a person asking "what is this for and how do I use it", who may never open a terminal: intro, Quick Start (a prompt to paste), Before You Record, the AGENTS.md snippet. Below ## Reference is what a CLI's README documents by convention: Installation, Commands, Options, Steps File, Narration, License. Commands and Options repeat --help, so change them in the same commit as any flag. Agent guidance belongs in SKILL.md, design rationale and history here or in CHANGELOG.md. Links must be absolute: the alias publishes the file from another directory.
• alias/agentic-demo/ — the agentic-demo npm package: a bin that resolves @popoverai/browser-automation and imports its dist/cli.js, so npx agentic-demo … works without a second implementation. The main package's bin is spelled agentic-demo too, so there is one name to type however the CLI got there. Its prepack copies in the root README (gitignored here), so both npm pages are the same page.
• tests/ — vitest, one file per subject; ffmpeg and agent-browser are stubbed (an exec seam and a fake stream WebSocket server), speech models are MockSpeechModelV4 from ai/test