Contributing to GreaseClaw - GreaseClaw Documentation

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

Quick Links

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:

Component	Path	What it does
Agent UI	`apps/app`	Chrome extension — chat interface, settings, side panel
Server	`apps/server`	Bun server — agent loop, MCP tools, API endpoints
Controller	`apps/controller-ext`	Chrome extension — bridges `chrome.*` APIs to the server

Architecture

Setup

# Clone the repo
git clone https://www.github.com/greaseclaw/greaseclaw.git
cd GreaseClaw/packages/browseros-agent

# Install dependencies
bun install

# Copy environment files
cp apps/server/.env.example apps/server/.env.development
cp apps/app/.env.example apps/app/.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 GreaseClaw:

Go to chrome://extensions/
Enable Developer mode
Click Load unpacked and select the apps/app/dist/ folder

Commands

Command	Description
`bun run start:server`	Start the server
`bun run start:agent`	Start agent extension (dev mode)
`bun run build:server`	Build server for production
`bun run build:agent`	Build agent extension
`bun run build:ext`	Build controller extension
`bun run test`	Run tests
`bun run lint`	Check with Biome
`bun run typecheck`	TypeScript 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
Linux
Windows

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 GreaseClaw

macOS (ARM64)
macOS (x64)
Windows
Linux

<chromium-src>/out/Default_arm64/GreaseClaw\ Dev.app/Contents/MacOS/GreaseClaw\ Dev \
  --enable-logging=stderr \
  --use-mock-keychain \
  --user-data-dir=/tmp/test-profile

<chromium-src>/out/Default_x64/GreaseClaw\ Dev.app/Contents/MacOS/GreaseClaw\ Dev \
  --enable-logging=stderr \
  --use-mock-keychain \
  --user-data-dir=/tmp/test-profile

<chromium-src>\out\Default_x64\BrowserOS Dev.exe \
  --enable-logging=stderr \
  --user-data-dir=%TEMP%\test-profile

<chromium-src>/out/Default_x64/browseros \
  --enable-logging=stderr \
  --user-data-dir=/tmp/test-profile

Build Flags

Flag	Description
`--chromium-src`	Path to Chromium source directory
`--setup`	Run setup phase (first build only)
`--prep`	Run prep phase (first build only)
`--build`	Run the compile phase
`--build-type`	`debug` or `release`
`--sign`	Sign the build
`--package`	Package 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

Fork the repository on GitHub
Clone your fork locally
Create a branch: git checkout -b feature/your-feature
Make changes and test them
Commit: git commit -m "feat: add your feature"
Push: git push origin feature/your-feature
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

Discord — discord.gg/YKwjt5vuKr
GitHub Issues — www.github.com/greaseclaw/greaseclaw/issues
GitHub Discussions — www.github.com/greaseclaw/greaseclaw/discussions

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

​Quick Links

​Ways to Contribute

​Path 1: Agent Development

​Architecture

​Setup

​Running Locally

​Commands

​Path 2: Browser Development

​Prerequisites

​Build Instructions

​Build Flags

​Troubleshooting

​Making Your First PR

​Sign the CLA

​Code Standards

​Getting Help