Skip to main content
Hey there! Thanks for your interest in BrowserOS. Whether you’re fixing bugs, adding features, improving docs, or just poking around the code, we’re glad you’re here. BrowserOS is a monorepo with two main parts:
  • Agent - The Chrome extension with AI features (TypeScript/React)
  • Browser - The custom Chromium build (C++/Python)
Most folks start with the agent since it’s way easier to set up and iterate on.

GitHub Repository

Star, fork, and contribute to our codebase

Discord Community

Join our community for discussions and support

Report Issues

Report bugs or suggest new features

​
2. Ways to Contribute

You can contribute to BrowserOS in many ways! Whether you want to build features or help out in other ways, we appreciate all contributions.
  • 🐛 Report Bugs
  • 💡 Suggest Features
  • 📚 Improve Docs
Found a bug? Open an issue with:
  • Clear description
  • Steps to reproduce
  • Expected vs actual behavior
  • Screenshots/videos
  • Environment details (OS, browser version, BrowserOS version)

​
3. Pick Your Path

If you want to contribute to development, here are two paths you can take:

Agent Development

What you’ll work on:
  • AI agent features & tools
  • UI/UX improvements
  • Browser automation
  • Testing & docs
What you need:
  • Node.js 18+
  • ~500MB disk space
  • 10 minutes to set up
Skills: TypeScript, React, Chrome APIs

Browser Development

What you’ll work on:
  • Chromium patches
  • Build system
  • Platform features
  • Core browser stuff
What you need:
  • ~100GB disk space
  • 16GB+ RAM (recommended)
  • 3+ hours for first build
Skills: C++, Python, Chromium internals

​
3.1 Agent Development

The agent is a Chrome extension that provides AI-powered automation. Most contributors work here.

​
Quick Setup

1

Navigate to Agent Directory

cd packages/browseros-agent
2

Install Dependencies

yarn install
3

Set Up Environment

cp .env.example .env
Edit .env and add your LITELLM_API_KEY
4

Build the Extension

yarn build:dev       # One-time build

​
Load in BrowserOS

1

Open Extensions Page

Navigate to chrome://extensions/
2

Enable Developer Mode

Toggle Developer mode in the top right
3

Load Unpacked Extension

Click Load unpacked and select packages/browseros-agent/dist/
4

Open Agent Panel

Press the Agent icon from the extensions toolbar to open the agent panel
For detailed setup, architecture, and code standards, see the Agent Contributing Guide.

​
3.2 Browser Development

Building the custom Chromium browser requires significant disk space and time. Only go down this path if you’re working on browser-level features like patches to Chromium itself.

​
Prerequisites

  • macOS
  • Linux
  • Windows
  • macOS (tested on M4 Max)
  • Xcode and Command Line Tools
  • Python 3
  • Git
  • ~100GB of free disk space (for Chromium source)
  • ~16GB RAM (recommended)

​
Build Instructions

1

Checkout Chromium Source

First, follow the official Chromium guide for your platform:Chromium: Get the CodeThis will set up depot_tools and fetch the ~100GB Chromium source tree. This typically takes 2-3 hours depending on your internet speed.
2

Navigate to Build System

Once you have Chromium checked out, navigate to our build system:
cd packages/browseros
3

Build Debug Version (for development)

  • macOS
  • Linux
  • Windows
python build/build.py --config build/config/debug.macos.yaml --chromium-src /path/to/chromium/src --build
4

Build Release Version (for production)

  • macOS
  • Linux
  • Windows
python build/build.py --config build/config/release.macos.yaml --chromium-src /path/to/chromium/src --build
The build typically takes 1-3 hours on modern hardware (M4 Max, Ryzen 9, etc.).
5

Run BrowserOS

After the build completes successfully, you can run BrowserOS:
  • macOS Debug (ARM64)
  • macOS Debug (x64)
  • macOS Release (ARM64)
  • macOS Release (x64)
  • Linux/Windows
out/Default_arm64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev --user-data-dir=/tmp/test-profile
The --user-data-dir flag is useful for creating isolated test profiles during development.

​
Troubleshooting

  • Make sure you’ve followed all prerequisite steps from the Chromium build guide
  • Ensure Xcode is up to date (macOS)
  • Verify all required packages are installed (Linux)
  • Check Visual Studio installation (Windows)
Chromium requires significant disk space (~100GB). Ensure you have enough free space before starting the build. You can use df -h on Unix systems or check Disk Management on Windows.
  • Use ccache to speed up rebuilds
  • Consider using a machine with more CPU cores
  • Build only the components you need for development
  • Use the debug build for faster compilation times

​
4. Making Your First Contribution

Open a PR on GitHub with:
  • Clear title in conventional commit format
  • Description explaining what changed and why
  • Screenshots/videos for UI changes
  • Link to related issues (e.g., “Fixes #123”)

​
Sign the CLA

On your first PR, our bot will ask you to sign the Contributor License Agreement:
1

Read the CLA

Read the CLA document
2

Sign via Comment

Comment on your PR:
I have read the CLA Document and I hereby sign the CLA
3

Automatic Recording

The bot will record your signature (one-time thing)

​
5. Code Standards

​
TypeScript (Agent)

  • Strict typing - Always declare types, avoid any
  • Zod schemas - Use Zod instead of TypeScript interfaces
  • Path aliases - Use @/lib not relative paths like ../
  • Naming:
    • Classes: PascalCase
    • Functions/variables: camelCase
    • Constants: UPPERCASE
    • Private methods: prefix with _
Example: 
import { z } from 'zod'

// Good: Zod schema with inline comments
export const ToolInputSchema = z.object({
  action: z.enum(['click', 'type']),  // Action to perform
  target: z.string().min(1),  // Element selector
  timeout: z.number().default(5000)  // Timeout in ms
})

export type ToolInput = z.infer<typeof ToolInputSchema>

​
React (Agent UI)

  • Styling: Tailwind CSS only (no SCSS or CSS modules)
  • Hooks: Only at top level
  • Props: Define with Zod schemas
  • Testing: Vitest (not Jest)

​
General Guidelines

  • Keep functions short (<20 lines ideally)
  • Write tests for new features
  • Use descriptive variable names
  • Handle errors gracefully
claude.md file can be found at below:

​
6. Project Structure

monorepo/
├── packages/
│   ├── browseros/              # Chromium build system
│   │   ├── build/             # Python build scripts
│   │   ├── chromium_patches/  # Patches to Chromium source
│   │   └── resources/         # Icons, configs
│   │
│   └── browseros-agent/        # Chrome extension
│       ├── src/
│       │   ├── lib/           # Core agent logic
│       │   ├── sidepanel/     # Side panel UI
│       │   ├── newtab/        # New tab page
│       │   └── background/    # Extension background
│       └── docs/              # Architecture docs
│
├── docs/                       # General documentation
└── CONTRIBUTING.md            # Contributing guide

​
7. Development Workflow

1

Fork and Clone

Fork the repository on GitHub and clone it locally:
git clone https://github.com/YOUR-USERNAME/BrowserOS.git
cd BrowserOS
2

Create a Branch

Create a new branch for your feature or fix:
git checkout -b feature/your-feature-name
3

Make Changes

Make your changes and test them thoroughly. Follow our coding standards and ensure all tests pass.
4

Commit and Push

Commit your changes with a descriptive message:
git add .
git commit -m "feat: add new feature description"
git push origin feature/your-feature-name
5

Submit PR

Open a pull request on GitHub with a clear description of your changes and why they’re needed.

​
8. Support

Stuck? Need clarification? We’re here to help.

Discord Support

Real-time chat and support

GitHub Issues

Bug reports and features

GitHub Discussions

General questions

​
9. License

By contributing, you agree that your contributions will be licensed under AGPL-3.0.
Built with ❤️ from San Francisco
⌘I