Skip to content

CONTRIBUTING.BrowserOS.md

Latest commit

聽

History

History
124 lines (89 loc) 路 5.36 KB

CONTRIBUTING.BrowserOS.md

File metadata and controls

124 lines (89 loc) 路 5.36 KB
Raw

Contributing to BrowserOS

The agent platform for BrowserOS, the browser you drive with an AI agent built in. Start at the root contributing guide if you have not already, then come back here.

Working on BrowserOS neo instead? See CONTRIBUTING.md.

What you will be working on

BrowserOS is two pieces that run together.

Project What it is Stack
apps/app The extension. New tab, side panel chat, onboarding and settings WXT + React extension, AI SDK React bindings, Radix and shadcn, PostHog
apps/server The server. The MCP tool surface plus the agent loop that runs your tasks Bun. Hono with zod-validator, MCP served over Hono, Drizzle ORM with drizzle-kit, AI SDK across Anthropic, OpenAI, Google, Bedrock, Azure, OpenRouter and more

The extension talks to the server over its HTTP routes, typed end to end with Hono RPC. There is no schema to regenerate.

Prerequisites

Tool Why Install
Bun The package manager and runtime. Version pinned in package.json curl -fsSL https://bun.sh/install | bash
Go The dev supervisor is a Go program compiled on every run brew install go
BrowserOS The supervisor launches the installed app Download

Rust is not needed for this path. It is only required for the BrowserOS neo backend.

The dev loop is macOS only today. The supervisor resolves the browser through a hard-coded /Applications/... path, so Linux and Windows contributors can install dependencies and run the checks, but cannot launch either product yet.

Setup

cd packages/browseros-agent
bun install
cp .env.development.example .env.development

Everything in .env.development is optional for a first run. It holds analytics keys, Sentry DSNs, and port overrides, none of which you need to get the dev loop working. Copy it and move on.

bun run dev:setup does the same install with a frozen lockfile, which is what CI does.

Run it

bun run dev:watch

That starts three processes and launches the browser against them:

apps/app       wxt                      the extension, with hot reload
apps/app       bun run dev:web          the web preview
apps/server    bun --watch src/index.ts the server, restarting on change

Stop everything with bun run dev:stop.

:new versus plain

There are two variants and the difference matters more than the name suggests.

bun run dev:watch bun run dev:watch:new
Ports Fixed: CDP 9000, server 9100, extension 9300 Random, in the 9000 to 9999 range
Profile A persistent dev profile that keeps its state A fresh temporary directory each run
On start Kills anything holding those ports, and any browser already using that profile Only its own server port, cleared just before launch
Reach for it when You want your logins and settings to survive a restart Running more than one at once, testing first-run behaviour, or not wanting to disturb a running instance

:new is the safer default while you are getting oriented, though it is not entirely hands-off: the server process clears its own port immediately before launching, so a process that grabs that port in the gap after it was picked will still be killed. Both variants take a lock on the profile, so two watch runs can never supervise the same one.

Running the BrowserOS neo stack instead

dev:watch and dev:claw:watch are exclusive, not additive. One command runs one product. To work on neo, see CONTRIBUTING.md.

Before you open a PR

bun run check    # lint, typecheck and fallow
bun test         # TypeScript suites

Lint and formatting are Biome. bun run lint:fix applies what it can.

Handy extras

Command What it does
bun run start:server The server on its own, without the browser
bun run start:agent The extension dev server on its own
bun run dev:app-onboard The onboarding flow on its own
bun run devtools AI SDK devtools against the server
bun run dev:reset Wipe the dev profile and start clean
bun run dev:cleanup Stop dev processes and free the ports
bun run dev:manual Build the extension statically instead of hot reloading, for when you need to load it by hand

Where things live

apps/
  app/                   the extension
    entrypoints/         WXT entrypoints
    screens/             one folder per screen
    components/          shared UI
    modules/             cross-cutting infrastructure
    hooks/               global hooks
    lib/                 utilities
    schema/              GraphQL schema
  server/
    src/
      agent/             the agent loop
      api/               HTTP routes
      tools/             the MCP tool surface
      lib/               shared internals
    tests/
  app-onboard/           first-run onboarding (Vite)
packages/                shared TypeScript packages
tools/dev/               the Go dev supervisor

Getting help

Discord 路 Slack 路 Discussions

PR conventions, the CLA, and the browser build all live in the root contributing guide.