BrowserOS/docs/contributing.mdx

---
title: "Contributing to BrowserOS"
description: "Let's build the best open-source browser!"
icon: "code-branch"
---

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.

## 1. Quick Links

<CardGroup cols={3}>
  <Card
    title="GitHub Repository"
    icon="github"
    href="https://github.com/BrowserOS/BrowserOS"
  >
    Star, fork, and contribute to our codebase
  </Card>
  <Card
    title="Discord Community"
    icon="discord"
    href="https://discord.gg/YKwjt5vuKr"
  >
    Join our community for discussions and support
  </Card>
  <Card
    title="Report Issues"
    icon="bug"
    href="https://github.com/BrowserOS/BrowserOS/issues"
  >
    Report bugs or suggest new features
  </Card>
</CardGroup>

## 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.

<Tabs>
  <Tab title="🐛 Report Bugs">
    Found a bug? [Open an issue](https://github.com/browseros-ai/BrowserOS/issues/new) with:
    - Clear description
    - Steps to reproduce
    - Expected vs actual behavior
    - Screenshots/videos
    - Environment details (OS, browser version, BrowserOS version)
  </Tab>

  <Tab title="💡 Suggest Features">
    Have an idea? [Share it here](https://github.com/browseros-ai/BrowserOS/issues/99) or chat with us on [Discord](https://discord.gg/YKwjt5vuKr).
  </Tab>

  <Tab title="📚 Improve Docs">
    We use <b>Mintlify</b> for our documentation. All docs live in the <code>docs/</code> directory.

    - Add new documentation pages or update existing ones under <code>docs/</code>
    - Help clarify instructions; add examples, tutorials, or guides
    - After adding or editing a page, update <code>docs/docs.json</code> to include your new or changed file in the navigation

    If you have questions about the docs system, ask in Discord!
  </Tab>
</Tabs>

## 3. Pick Your Path

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

<CardGroup cols={2}>
  <Card title="Agent Development" icon="robot">
    **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
  </Card>
  <Card title="Browser Development" icon="globe">
    **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
  </Card>
</CardGroup>

### 3.1 Agent Development

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

<Accordion title="Instructions">

#### Quick Setup

<Steps>
  <Step title="Navigate to Agent Directory">
    ```bash
    cd packages/browseros-agent
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash
    yarn install
    ```
  </Step>

  <Step title="Set Up Environment">
    ```bash
    cp .env.example .env
    ```
    Edit `.env` and add your `LITELLM_API_KEY`
  </Step>

  <Step title="Build the Extension">
    ```bash
    yarn build:dev       # One-time build
    ```
  </Step>
</Steps>

#### Load in BrowserOS

<Steps>
  <Step title="Open Extensions Page">
    Navigate to `chrome://extensions/`
  </Step>

  <Step title="Enable Developer Mode">
    Toggle **Developer mode** in the top right
  </Step>

  <Step title="Load Unpacked Extension">
    Click **Load unpacked** and select `packages/browseros-agent/dist/`
  </Step>

  <Step title="Open Agent Panel">
    Press the Agent icon from the extensions toolbar to open the agent panel
  </Step>
</Steps>

<Note>
For detailed setup, architecture, and code standards, see the [Agent Contributing Guide](https://github.com/BrowserOS/BrowserOS/blob/main/packages/browseros-agent/CONTRIBUTING.md).
</Note>

</Accordion>

### 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.

<Accordion title="Instructions">

#### Prerequisites

<Tabs>
  <Tab title="macOS">
    - macOS (tested on M4 Max)
    - Xcode and Command Line Tools
    - Python 3
    - Git
    - ~100GB of free disk space (for Chromium source)
    - ~16GB RAM (recommended)
  </Tab>
  <Tab title="Linux">
    - Ubuntu 20.04+ or similar
    - build-essential package
    - Python 3
    - Git
    - ~100GB of free disk space
    - ~16GB RAM (recommended)
  </Tab>
  <Tab title="Windows">
    - Windows 10/11
    - Visual Studio 2022 with C++ workload
    - Python 3
    - Git
    - ~100GB of free disk space
    - ~16GB RAM minimum
  </Tab>
</Tabs>

#### Build Instructions

<Steps>
  <Step title="Checkout Chromium Source">
    First, follow the official Chromium guide for your platform:

    **[Chromium: Get the Code](https://www.chromium.org/developers/how-tos/get-the-code/)**

    This will set up `depot_tools` and fetch the ~100GB Chromium source tree. This typically takes 2-3 hours depending on your internet speed.
  </Step>

  <Step title="Navigate to Build System">
    Once you have Chromium checked out, navigate to our build system:

    ```bash
    cd packages/browseros
    ```
  </Step>

  <Step title="Build Debug Version (for development)">
    <Tabs>
      <Tab title="macOS">
        ```bash
        python build/build.py --config build/config/debug.macos.yaml --chromium-src /path/to/chromium/src --build
        ```
      </Tab>
      <Tab title="Linux">
        ```bash
        python build/build.py --config build/config/debug.linux.yaml --chromium-src /path/to/chromium/src --build
        ```
      </Tab>
      <Tab title="Windows">
        ```bash
        python build/build.py --config build/config/debug.windows.yaml --chromium-src /path/to/chromium/src --build
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Build Release Version (for production)">
    <Tabs>
      <Tab title="macOS">
        ```bash
        python build/build.py --config build/config/release.macos.yaml --chromium-src /path/to/chromium/src --build
        ```
      </Tab>
      <Tab title="Linux">
        ```bash
        python build/build.py --config build/config/release.linux.yaml --chromium-src /path/to/chromium/src --build
        ```
      </Tab>
      <Tab title="Windows">
        ```bash
        python build/build.py --config build/config/release.windows.yaml --chromium-src /path/to/chromium/src --build
        ```
      </Tab>
    </Tabs>

    <Note>
    The build typically takes 1-3 hours on modern hardware (M4 Max, Ryzen 9, etc.).
    </Note>
  </Step>

  <Step title="Run BrowserOS">
    After the build completes successfully, you can run BrowserOS:

    <Tabs>
      <Tab title="macOS Debug (ARM64)">
        ```bash
        out/Default_arm64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev --user-data-dir=/tmp/test-profile
        ```
      </Tab>
      <Tab title="macOS Debug (x64)">
        ```bash
        out/Default_x64/BrowserOS\ Dev.app/Contents/MacOS/BrowserOS\ Dev --user-data-dir=/tmp/test-profile
        ```
      </Tab>
      <Tab title="macOS Release (ARM64)">
        ```bash
        out/Default_arm64/BrowserOS.app/Contents/MacOS/BrowserOS --user-data-dir=/tmp/test-profile
        ```
      </Tab>
      <Tab title="macOS Release (x64)">
        ```bash
        out/Default_x64/BrowserOS.app/Contents/MacOS/BrowserOS --user-data-dir=/tmp/test-profile
        ```
      </Tab>
      <Tab title="Linux/Windows">
        The built binary will be located in the `out/Default_x64/` directory. Run it with the `--user-data-dir` flag to create an isolated test profile.
      </Tab>
    </Tabs>

    <Tip>
    The `--user-data-dir` flag is useful for creating isolated test profiles during development.
    </Tip>
  </Step>
</Steps>

#### Troubleshooting

<Accordion title="Build fails with missing dependencies">
  - 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)
</Accordion>

<Accordion title="Out of disk space">
  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.
</Accordion>

<Accordion title="Build takes too long">
  - 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
</Accordion>

</Accordion>

## 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:

<Steps>
  <Step title="Read the CLA">
    Read the [CLA document](https://github.com/BrowserOS/BrowserOS/blob/main/CLA.md)
  </Step>

  <Step title="Sign via Comment">
    Comment on your PR:
    ```
    I have read the CLA Document and I hereby sign the CLA
    ```
  </Step>

  <Step title="Automatic Recording">
    The bot will record your signature (one-time thing)
  </Step>
</Steps>

## 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:**

```typescript
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

<Note>
claude.md file can be found at below:
- Agent: [packages/browseros-agent/CLAUDE.md](https://github.com/BrowserOS/BrowserOS/blob/main/packages/browseros-agent/CLAUDE.md)
</Note>

## 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

<Steps>
  <Step title="Fork and Clone">
    Fork the repository on GitHub and clone it locally:
    ```bash
    git clone https://github.com/YOUR-USERNAME/BrowserOS.git
    cd BrowserOS
    ```
  </Step>

  <Step title="Create a Branch">
    Create a new branch for your feature or fix:
    ```bash
    git checkout -b feature/your-feature-name
    ```
  </Step>

  <Step title="Make Changes">
    Make your changes and test them thoroughly. Follow our coding standards and ensure all tests pass.
  </Step>

  <Step title="Commit and Push">
    Commit your changes with a descriptive message:
    ```bash
    git add .
    git commit -m "feat: add new feature description"
    git push origin feature/your-feature-name
    ```
  </Step>

  <Step title="Submit PR">
    Open a pull request on GitHub with a clear description of your changes and why they're needed.
  </Step>
</Steps>

## 8. Support

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

<CardGroup cols={3}>
  <Card
    title="Discord Support"
    icon="discord"
    href="https://discord.gg/YKwjt5vuKr"
  >
    Real-time chat and support
  </Card>
  <Card
    title="GitHub Issues"
    icon="bug"
    href="https://github.com/browseros-ai/BrowserOS/issues"
  >
    Bug reports and features
  </Card>
  <Card
    title="GitHub Discussions"
    icon="comments"
    href="https://github.com/browseros-ai/BrowserOS/discussions"
  >
    General questions
  </Card>
</CardGroup>


## 9. License

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

---

Built with ❤️ from San Francisco