Skip to main content
BrowserOS has two main parts you can contribute to:
  • Agent — The AI features, UI, and browser automation (TypeScript/React)
  • Browser — The custom Chromium build (C++/Python)
Most contributors work on the Agent since it’s much easier to set up.

​
Ways to Contribute

Report bugs — Open an issue with steps to reproduce, expected vs actual behavior, and screenshots. Suggest features — Share ideas on GitHub or Discord. Improve docs — Docs live in docs/ and use Mintlify. Edit pages and update docs/docs.json for navigation.

​
Path 1: Agent Development

The Agent is a monorepo with 3 components:
ComponentPathWhat it does
Agent UIapps/agentChrome extension — chat interface, settings, side panel
Serverapps/serverBun server — agent loop, MCP tools, API endpoints
Controllerapps/controller-extChrome extension — bridges chrome.* APIs to the server

​
Architecture

BrowserOS Agent architecture diagram

​
Setup

# Clone the repo
git clone https://github.com/YOUR-USERNAME/BrowserOS.git
cd BrowserOS/packages/browseros-agent

# Install dependencies
bun install

# Copy environment files
cp apps/server/.env.example apps/server/.env.development
cp apps/agent/.env.example apps/agent/.env.development

​
Running Locally

# Terminal 1: Start the server
bun run start:server

# Terminal 2: Start the agent extension (dev mode)
bun run start:agent
Then load the extension in BrowserOS:
  1. Go to chrome://extensions/
  2. Enable Developer mode
  3. Click Load unpacked and select the apps/agent/dist/ folder

​
Commands

CommandDescription
bun run start:serverStart the server
bun run start:agentStart agent extension (dev mode)
bun run build:serverBuild server for production
bun run build:agentBuild agent extension
bun run build:extBuild controller extension
bun run testRun tests
bun run lintCheck with Biome
bun run typecheckTypeScript check

​
Path 2: Browser Development

Only go down this path if you’re working on Chromium-level features like patches to the browser itself. Requirements:
  • ~100GB disk space
  • 16GB+ RAM recommended
  • 3+ hours for first build

​
Prerequisites

  • macOS with Xcode and Command Line Tools
  • Python 3.12+
  • UV (Python package manager)
  • Git

​
Build Instructions

1. Clone Chromium source Follow the official Chromium: Get the Code guide. This sets up depot_tools and fetches ~100GB of source code. Note the path where you clone it (e.g., ~/chromium/src). 2. Install UV and dependencies 
# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Navigate to build system
cd packages/browseros

# Install dependencies
uv sync
3. Build debug version 
uv run browseros build \
  --chromium-src <your-chromium-src-path> \
  --setup \
  --prep \
  --build \
  --build-type debug
The --setup and --prep flags are only needed for the first build. After that, just use --build for incremental builds: 
uv run browseros build --chromium-src <path> --build --build-type debug
4. Run BrowserOS 
<chromium-src>/out/Default_arm64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev \
  --enable-logging=stderr \
  --use-mock-keychain \
  --user-data-dir=/tmp/test-profile

​
Build Flags

FlagDescription
--chromium-srcPath to Chromium source directory
--setupRun setup phase (first build only)
--prepRun prep phase (first build only)
--buildRun the compile phase
--build-typedebug or release
--signSign the build
--packagePackage for distribution

​
Troubleshooting

Build fails with missing dependencies — Make sure you followed all steps from the Chromium build guide for your platform. Out of disk space — Chromium needs ~100GB. Check with df -h. Build takes too long — Use ccache, more CPU cores, or stick to debug builds. UV command not found — Restart your terminal after installing UV.

​
Making Your First PR

  1. Fork the repository on GitHub
  2. Clone your fork locally
  3. Create a branch: git checkout -b feature/your-feature
  4. Make changes and test them
  5. Commit: git commit -m "feat: add your feature"
  6. Push: git push origin feature/your-feature
  7. Open a PR with a clear description

​
Sign the CLA

On your first PR, our bot will ask you to sign the Contributor License Agreement. Just comment: 
I have read the CLA Document and I hereby sign the CLA

​
Code Standards

TypeScript:
  • Use strict typing, avoid any
  • Use Zod schemas instead of TypeScript interfaces
  • Use path aliases (@/lib) not relative paths (../)
  • Naming: PascalCase for classes, camelCase for functions
React:
  • Tailwind CSS only (no SCSS or CSS modules)
  • Hooks at top level only
  • Test with Vitest
General:
  • Keep functions short (under 20 lines)
  • Write tests for new features
  • Handle errors gracefully

​
Getting Help

By contributing, you agree that your contributions will be licensed under AGPL-3.0.