{"owner":"daijro","repo":"camoufox","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## What this is\n\nCamoufox is an anti-detect fork of Firefox for web scraping and automation. This repo is **not the Firefox source** — it is a *build system* that fetches upstream Firefox, applies a stack of patches + code additions, and produces a hardened, fingerprint-spoofing browser. The distinguishing design choice is that fingerprint spoofing happens at the **C++/Juggler implementation level**, not via injected JavaScript, so it is invisible to page-side inspection.\n\nThe actual Firefox tree lives in `camoufox-<version>-<release>/` (e.g. `camoufox-150.0.2-beta.25/`), created by the build. That directory is generated — never edit it directly to make lasting changes; changes there are captured as patches (see \"Making patches\" below).\n\n`upstream.sh` pins `version` / `release`, and is sourced+exported by the `Makefile`, so those variables flow into every script.\n\n## Build commands\n\nThe build system is designed for **Linux**. Windows and macOS binaries are **cross-compiled from Linux** — they are never built natively. (`scripts/install-deps.sh` covers macOS/Linux host dependencies for local `make dir` + bootstrap experimentation; a full production build path is Linux/Docker.)\n\n```bash\nbash scripts/install-deps.sh   # install host build deps (Python ≥3.11, Rust, aria2, p7zip, go, msitools, wget, sqlite)\nmake dir                       # fetch Firefox source, extract, copy additions/settings, apply all patches → touches _READY\nmake bootstrap                 # install system deps (apt/dnf/pacman) + run `mach bootstrap` (one-time)\nmake build                     # ./mach build in the source dir\nmake run                       # run the built browser (wipes ~/.camoufox profile)\nmake run args=\"--headless https://test.com\"\npython3 multibuild.py --target linux windows macos --arch x86_64 arm64 i686   # full cross-platform build + package\n```\n\n`make dir` is the pipeline that matters: `setup` (fetch tarball via `aria2c` → extract → `copy-additions.sh`) → `python3 scripts/patch.py` (applies every patch, writes `mozconfig`) → `_READY`. `mach` requires **Python ≥ 3.11** (stdlib `tomllib`); older `python3` crashes with `ModuleNotFoundError: No module named 'tomllib'`.\n\nDocker is the portable path: `docker build -t camoufox-builder .` then `docker run -v \"$(pwd)/dist:/app/dist\" camoufox-builder --target <os> --arch <arch>`.\n\nPackaging: `make package-linux|package-macos|package-windows arch=<arch>` (wraps `scripts/package.py`). Launcher (Go): `make build-launcher arch=<arch> os=<os>`.\n\n## Working with patches (the core workflow)\n\nAlmost all browser-behavior changes are `patches/*.patch` (~49 patches: `fingerprint-injection.patch`, `webgl-spoofing.patch`, `navigator-spoofing.patch`, `webrtc-ip-spoofing.patch`, the `playwright/` and `librewolf/` and `ghostery/` subdirs, etc.). Do not hand-edit patch files.\n\nUse the developer UI instead:\n\n```bash\nmake edits          # launches scripts/developer.py — apply/undo/create/manage patches\n```\n\n- **New patch:** in the UI \"Reset workspace\" → edit files in `camoufox-*/` → `make build` / `make run` to test → \"Write workspace to patch\".\n- **Edit existing patch:** \"Edit a patch\" (resets workspace to that patch's state) → edit → \"Write workspace to patch\" to overwrite.\n\nLow-level equivalents: `make patch ./patches/x.patch`, `make unpatch ./patches/x.patch`, `make workspace ./patches/x.patch`, `make revert` (reset to `unpatched` tag), `make diff` (diff against `first-checkpoint`). The source dir is a git repo with `unpatched` / `first-checkpoint` / `checkpoint` tags used by these targets.\n\n## Repository layout (the parts that require cross-file understanding)\n\n- **`patches/`** — the diffs applied to Firefox source. This is where browser behavior is changed.\n- **`additions/`** — whole files copied *into* the source tree (not diffs) by `scripts/copy-additions.sh`:\n  - `additions/camoucfg/` — the C++ config layer. `MaskConfig.hpp` reads the spoofing config (from `CAMOU_CONFIG` env var / `camoufox.cfg`) that the patches consult at the C++ level; `MouseTrajectories.hpp` is the human-cursor algorithm.\n  - `additions/juggler/` — Camoufox's patched **Juggler** (Firefox's Playwright automation protocol, the Firefox analog of CDP). This is where Playwright is made undetectable — the page agent runs in an isolated scope so injected automation JS is not visible to the page.\n- **`settings/`** — `camoufox.cfg`, `chrome.css`, `properties.json`, `camoucfg.jvv`, prefs/policies. Copied into the source's `lw/` dir by `copy-additions.sh`. Edit the built config with `make edit-cfg`.\n- **`scripts/`** — `patch.py` (the patcher, LibreWolf-derived), `developer.py` (the `make edits` UI), `package.py`, `copy-additions.sh`, `install-deps.sh`.\n- **`pythonlib/`** — the `camoufox` PyPI package: the Playwright-compatible Python interface that generates + injects fingerprints via BrowserForge and launches the binary. `fingerprint-presets-v150.json` holds real scraped fingerprints. This is the user-facing API; the browser binary is the backend.\n- **`jsonvv/`** — JSON-with-validation format library used for `camoucfg.jvv` (config schema).\n- **`legacy/launcher/`** — Go launcher binary.\n- **`assets/`** — `base.mozconfig` and other build inputs.\n\n## Testing\n\nTwo suites, **both required for PRs** (they cover different layers):\n\n- **`build-tester/`** — tests the raw binary directly (bypasses the Python package); fingerprints injected via `generate_context_fingerprint` + `addInitScript` and `CAMOU_CONFIG`. Run when changing patches / C++ / JS browser layer:\n  ```bash\n  cd build-tester && npm install && pip install -r requirements.txt\n  python scripts/run_tests.py /path/to/camoufox-binary\n  ```\n- **`service-tester/`** — tests the Python package / service layer.\n- **`tests/`** — Playwright tests, run via `make tests` (add `headful=true` for headful): points at `camoufox-*/obj-*/dist/bin/camoufox-bin`.\n\n`ccache` is enabled in the build config — install it for fast incremental rebuilds (cold ~40 min, incremental ~5 min).\n\n## Constraints when editing this repo\n\n- The `camoufox-*/` source directory is regenerated — persist changes as patches, never as edits committed to that tree.\n- Keep the `Makefile` diff clean against `main` unless a change genuinely belongs there — dependency setup lives in `scripts/install-deps.sh`, not the Makefile.\n- Every PR must be tied to a GitHub issue and pass both test suites (see `CONTRIBUTING.md`).\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## What this is\n\nCamoufox is an anti-detect fork of Firefox for web scraping and automation. This repo is **not the Firefox source** — it is a *build system* that fetches upstream Firefox, applies a stack of patches + code additions, and produces a hardened, fingerprint-spoofing browser. The distinguishing design choice is that fingerprint spoofing happens at the **C++/Juggler implementation level**, not via injected JavaScript, so it is invisible to page-side inspection.\n\nThe actual Firefox tree lives in `camoufox-<version>-<release>/` (e.g. `camoufox-150.0.2-beta.25/`), created by the build. That directory is generated — never edit it directly to make lasting changes; changes there are captured as patches (see \"Making patches\" below).\n\n`upstream.sh` pins `version` / `release`, and is sourced+exported by the `Makefile`, so those variables flow into every script.\n\n## Build commands\n\nThe build system is designed for **Linux**. Windows and macOS binaries are **cross-compiled from Linux** — they are never built natively. (`scripts/install-deps.sh` covers macOS/Linux host dependencies for local `make dir` + bootstrap experimentation; a full production build path is Linux/Docker.)\n\n```bash\nbash scripts/install-deps.sh   # install host build deps (Python ≥3.11, Rust, aria2, p7zip, go, msitools, wget, sqlite)\nmake dir                       # fetch Firefox source, extract, copy additions/settings, apply all patches → touches _READY\nmake bootstrap                 # install system deps (apt/dnf/pacman) + run `mach bootstrap` (one-time)\nmake build                     # ./mach build in the source dir\nmake run                       # run the built browser (wipes ~/.camoufox profile)\nmake run args=\"--headless https://test.com\"\npython3 multibuild.py --target linux windows macos --arch x86_64 arm64 i686   # full cross-platform build + package\n```\n\n`make dir` is the pipeline that matters: `setup` (fetch tarball via `aria2c` → extract → `copy-additions.sh`) → `python3 scripts/patch.py` (applies every patch, writes `mozconfig`) → `_READY`. `mach` requires **Python ≥ 3.11** (stdlib `tomllib`); older `python3` crashes with `ModuleNotFoundError: No module named 'tomllib'`.\n\nDocker is the portable path: `docker build -t camoufox-builder .` then `docker run -v \"$(pwd)/dist:/app/dist\" camoufox-builder --target <os> --arch <arch>`.\n\nPackaging: `make package-linux|package-macos|package-windows arch=<arch>` (wraps `scripts/package.py`). Launcher (Go): `make build-launcher arch=<arch> os=<os>`.\n\n## Working with patches (the core workflow)\n\nAlmost all browser-behavior changes are `patches/*.patch` (~49 patches: `fingerprint-injection.patch`, `webgl-spoofing.patch`, `navigator-spoofing.patch`, `webrtc-ip-spoofing.patch`, the `playwright/` and `librewolf/` and `ghostery/` subdirs, etc.). Do not hand-edit patch files.\n\nUse the developer UI instead:\n\n```bash\nmake edits          # launches scripts/developer.py — apply/undo/create/manage patches\n```\n\n- **New patch:** in the UI \"Reset workspace\" → edit files in `camoufox-*/` → `make build` / `make run` to test → \"Write workspace to patch\".\n- **Edit existing patch:** \"Edit a patch\" (resets workspace to that patch's state) → edit → \"Write workspace to patch\" to overwrite.\n\nLow-level equivalents: `make patch ./patches/x.patch`, `make unpatch ./patches/x.patch`, `make workspace ./patches/x.patch`, `make revert` (reset to `unpatched` tag), `make diff` (diff against `first-checkpoint`). The source dir is a git repo with `unpatched` / `first-checkpoint` / `checkpoint` tags used by these targets.\n\n## Repository layout (the parts that require cross-file understanding)\n\n- **`patches/`** — the diffs applied to Firefox source. This is where browser behavior is changed.\n- **`additions/`** — whole files copied *into* the source tree (not diffs) by `scripts/copy-additions.sh`:\n  - `additions/camoucfg/` — the C++ config layer. `MaskConfig.hpp` reads the spoofing config (from `CAMOU_CONFIG` env var / `camoufox.cfg`) that the patches consult at the C++ level; `MouseTrajectories.hpp` is the human-cursor algorithm.\n  - `additions/juggler/` — Camoufox's patched **Juggler** (Firefox's Playwright automation protocol, the Firefox analog of CDP). This is where Playwright is made undetectable — the page agent runs in an isolated scope so injected automation JS is not visible to the page.\n- **`settings/`** — `camoufox.cfg`, `chrome.css`, `properties.json`, `camoucfg.jvv`, prefs/policies. Copied into the source's `lw/` dir by `copy-additions.sh`. Edit the built config with `make edit-cfg`.\n- **`scripts/`** — `patch.py` (the patcher, LibreWolf-derived), `developer.py` (the `make edits` UI), `package.py`, `copy-additions.sh`, `install-deps.sh`.\n- **`pythonlib/`** — the `camoufox` PyPI package: the Playwright-compatible Python interface that generates + injects fingerprints via BrowserForge and launches the binary. `fingerprint-presets-v150.json` holds real scraped fingerprints. This is the user-facing API; the browser binary is the backend.\n- **`jsonvv/`** — JSON-with-validation format library used for `camoucfg.jvv` (config schema).\n- **`legacy/launcher/`** — Go launcher binary.\n- **`assets/`** — `base.mozconfig` and other build inputs.\n\n## Testing\n\nTwo suites, **both required for PRs** (they cover different layers):\n\n- **`build-tester/`** — tests the raw binary directly (bypasses the Python package); fingerprints injected via `generate_context_fingerprint` + `addInitScript` and `CAMOU_CONFIG`. Run when changing patches / C++ / JS browser layer:\n  ```bash\n  cd build-tester && npm install && pip install -r requirements.txt\n  python scripts/run_tests.py /path/to/camoufox-binary\n  ```\n- **`service-tester/`** — tests the Python package / service layer.\n- **`tests/`** — Playwright tests, run via `make tests` (add `headful=true` for headful): points at `camoufox-*/obj-*/dist/bin/camoufox-bin`.\n\n`ccache` is enabled in the build config — install it for fast incremental rebuilds (cold ~40 min, incremental ~5 min).\n\n## Constraints when editing this repo\n\n- The `camoufox-*/` source directory is regenerated — persist changes as patches, never as edits committed to that tree.\n- Keep the `Makefile` diff clean against `main` unless a change genuinely belongs there — dependency setup lives in `scripts/install-deps.sh`, not the Makefile.\n- Every PR must be tied to a GitHub issue and pass both test suites (see `CONTRIBUTING.md`).\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## What this is\n\nCamoufox is an anti-detect fork of Firefox for web scraping and automation. This repo is **not the Firefox source** — it is a *build system* that fetches upstream Firefox, applies a stack of patches + code additions, and produces a hardened, fingerprint-spoofing browser. The distinguishing design choice is that fingerprint spoofing happens at the **C++/Juggler implementation level**, not via injected JavaScript, so it is invisible to page-side inspection.\n\nThe actual Firefox tree lives in `camoufox-<version>-<release>/` (e.g. `camoufox-150.0.2-beta.25/`), created by the build. That directory is generated — never edit it directly to make lasting changes; changes there are captured as patches (see \"Making patches\" below).\n\n`upstream.sh` pins `version` / `release`, and is sourced+exported by the `Makefile`, so those variables flow into every script.\n\n## Build commands\n\nThe build system is designed for **Linux**. Windows and macOS binaries are **cross-compiled from Linux** — they are never built natively. (`scripts/install-deps.sh` covers macOS/Linux host dependencies for local `make dir` + bootstrap experimentation; a full production build path is Linux/Docker.)\n\n```bash\nbash scripts/install-deps.sh   # install host build deps (Python ≥3.11, Rust, aria2, p7zip, go, msitools, wget, sqlite)\nmake dir                       # fetch Firefox source, extract, copy additions/settings, apply all patches → touches _READY\nmake bootstrap                 # install system deps (apt/dnf/pacman) + run `mach bootstrap` (one-time)\nmake build                     # ./mach build in the source dir\nmake run                       # run the built browser (wipes ~/.camoufox profile)\nmake run args=\"--headless https://test.com\"\npython3 multibuild.py --target linux windows macos --arch x86_64 arm64 i686   # full cross-platform build + package\n```\n\n`make dir` is the pipeline that matters: `setup` (fetch tarball via `aria2c` → extract → `copy-additions.sh`) → `python3 scripts/patch.py` (applies every patch, writes `mozconfig`) → `_READY`. `mach` requires **Python ≥ 3.11** (stdlib `tomllib`); older `python3` crashes with `ModuleNotFoundError: No module named 'tomllib'`.\n\nDocker is the portable path: `docker build -t camoufox-builder .` then `docker run -v \"$(pwd)/dist:/app/dist\" camoufox-builder --target <os> --arch <arch>`.\n\nPackaging: `make package-linux|package-macos|package-windows arch=<arch>` (wraps `scripts/package.py`). Launcher (Go): `make build-launcher arch=<arch> os=<os>`.\n\n## Working with patches (the core workflow)\n\nAlmost all browser-behavior changes are `patches/*.patch` (~49 patches: `fingerprint-injection.patch`, `webgl-spoofing.patch`, `navigator-spoofing.patch`, `webrtc-ip-spoofing.patch`, the `playwright/` and `librewolf/` and `ghostery/` subdirs, etc.). Do not hand-edit patch files.\n\nUse the developer UI instead:\n\n```bash\nmake edits          # launches scripts/developer.py — apply/undo/create/manage patches\n```\n\n- **New patch:** in the UI \"Reset workspace\" → edit files in `camoufox-*/` → `make build` / `make run` to test → \"Write workspace to patch\".\n- **Edit existing patch:** \"Edit a patch\" (resets workspace to that patch's state) → edit → \"Write workspace to patch\" to overwrite.\n\nLow-level equivalents: `make patch ./patches/x.patch`, `make unpatch ./patches/x.patch`, `make workspace ./patches/x.patch`, `make revert` (reset to `unpatched` tag), `make diff` (diff against `first-checkpoint`). The source dir is a git repo with `unpatched` / `first-checkpoint` / `checkpoint` tags used by these targets.\n\n## Repository layout (the parts that require cross-file understanding)\n\n- **`patches/`** — the diffs applied to Firefox source. This is where browser behavior is changed.\n- **`additions/`** — whole files copied *into* the source tree (not diffs) by `scripts/copy-additions.sh`:\n  - `additions/camoucfg/` — the C++ config layer. `MaskConfig.hpp` reads the spoofing config (from `CAMOU_CONFIG` env var / `camoufox.cfg`) that the patches consult at the C++ level; `MouseTrajectories.hpp` is the human-cursor algorithm.\n  - `additions/juggler/` — Camoufox's patched **Juggler** (Firefox's Playwright automation protocol, the Firefox analog of CDP). This is where Playwright is made undetectable — the page agent runs in an isolated scope so injected automation JS is not visible to the page.\n- **`settings/`** — `camoufox.cfg`, `chrome.css`, `properties.json`, `camoucfg.jvv`, prefs/policies. Copied into the source's `lw/` dir by `copy-additions.sh`. Edit the built config with `make edit-cfg`.\n- **`scripts/`** — `patch.py` (the patcher, LibreWolf-derived), `developer.py` (the `make edits` UI), `package.py`, `copy-additions.sh`, `install-deps.sh`.\n- **`pythonlib/`** — the `camoufox` PyPI package: the Playwright-compatible Python interface that generates + injects fingerprints via BrowserForge and launches the binary. `fingerprint-presets-v150.json` holds real scraped fingerprints. This is the user-facing API; the browser binary is the backend.\n- **`jsonvv/`** — JSON-with-validation format library used for `camoucfg.jvv` (config schema).\n- **`legacy/launcher/`** — Go launcher binary.\n- **`assets/`** — `base.mozconfig` and other build inputs.\n\n## Testing\n\nTwo suites, **both required for PRs** (they cover different layers):\n\n- **`build-tester/`** — tests the raw binary directly (bypasses the Python package); fingerprints injected via `generate_context_fingerprint` + `addInitScript` and `CAMOU_CONFIG`. Run when changing patches / C++ / JS browser layer:\n  ```bash\n  cd build-tester && npm install && pip install -r requirements.txt\n  python scripts/run_tests.py /path/to/camoufox-binary\n  ```\n- **`service-tester/`** — tests the Python package / service layer.\n- **`tests/`** — Playwright tests, run via `make tests` (add `headful=true` for headful): points at `camoufox-*/obj-*/dist/bin/camoufox-bin`.\n\n`ccache` is enabled in the build config — install it for fast incremental rebuilds (cold ~40 min, incremental ~5 min).\n\n## Constraints when editing this repo\n\n- The `camoufox-*/` source directory is regenerated — persist changes as patches, never as edits committed to that tree.\n- Keep the `Makefile` diff clean against `main` unless a change genuinely belongs there — dependency setup lives in `scripts/install-deps.sh`, not the Makefile.\n- Every PR must be tied to a GitHub issue and pass both test suites (see `CONTRIBUTING.md`).\n","category":"root","tokens":1634}]}