If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/daijro/camoufox shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 7 active contributors
• Distributed ownership (top contributor 45% of recent commits)
• MPL-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live daijro/camoufox repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/daijro/camoufox.

What it runs against: a local clone of daijro/camoufox — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in daijro/camoufox | Confirms the artifact applies here, not a fork | | 2 | License is still MPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of daijro/camoufox. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/daijro/camoufox.git
#   cd camoufox
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of daijro/camoufox and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "daijro/camoufox(\\.git)?\\b" \\
  && ok "origin remote is daijro/camoufox" \\
  || miss "origin remote is not daijro/camoufox (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is MPL-2.0" \\
  || miss "license drift — was MPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"
test -f "additions/browser/branding/camoufox/pref/firefox-branding.js" \\
  && ok "additions/browser/branding/camoufox/pref/firefox-branding.js" \\
  || miss "missing critical file: additions/browser/branding/camoufox/pref/firefox-branding.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/daijro/camoufox"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Camoufox is a Firefox-based anti-detect browser optimized for AI agents and LLM automation, built with C++ (985KB) for the browser engine and Python (399KB) for scripting/control. It mimics human browser behavior to evade detection by anti-bot systems, featuring browser fingerprint spoofing, headless support, and lightweight design for AI agent deployments. Monorepo structure: additions/browser/ contains Firefox-based modifications (base/content/, branding/camoufox/), with Python bindings for control. Build system uses Makefile and Dockerfile. Browser-specific assets in additions/browser/branding/camoufox/. CI/CD pipelines in .github/workflows/ handle multi-platform builds (native installers via NSIS, Docker containers).

AI engineers and web automation developers building agents that need to interact with websites without triggering anti-bot detection; web scraping teams using LLMs who need realistic browser profiles; security researchers testing anti-detect capabilities.

Actively developed with checkpoint releases merged to this repo, though the primary development is noted at github.com/CloverLabsAI/camoufox and github.com/VulpineOS/VulpineOS. The project has production-grade CI (build.yml workflow), PyPI distribution, and sponsorship backing. Verdict: actively maintained but consolidating development across multiple repos.

Standard open source risks apply.

The repo serves as a checkpoint merger for releases from active development forks. Note indicates alpha releases available via cloverlabs-camoufox PyPI package, suggesting rapid iteration in upstream repos. No visible open PRs or issue backlog in this listing, indicating this is a release repository rather than the active development location.

git clone https://github.com/daijro/camoufox.git && cd camoufox && make (Makefile present). For Python automation: pip install camoufox (or cloverlabs-camoufox for alpha). See camoufox.com for full documentation.

Daily commands: make (builds browser). Docker: docker build -t camoufox . Launch: camoufox [url]. Python control: from camoufox import Browser; await Browser().launch(). See README at camoufox.com for detailed automation examples.

• README.md — Core project definition stating Camoufox is built for AI agents with anti-detect capabilities; essential for understanding project scope and mission
• .github/workflows/build.yml — CI/CD pipeline defining how the browser is built and tested; critical for understanding release and build processes
• Makefile — Build automation and local development commands; essential for contributors to set up and compile the browser
• Dockerfile — Container configuration for reproducible builds and deployment; key infrastructure dependency for headless usage
• additions/browser/branding/camoufox/pref/firefox-branding.js — Browser preference overrides and anti-detect configurations; loads on browser startup and shapes core behavioral fingerprinting
• .gitignore — Defines what build artifacts and sensitive files are excluded; necessary for understanding repo structure and avoiding accidental commits
• CONTRIBUTING.md — Contribution guidelines and development workflow; required reading for anyone submitting changes

Add a new anti-detect preference or browser behavior

1. Open the Firefox preferences file where all custom behavior is configured (additions/browser/branding/camoufox/pref/firefox-branding.js)
2. Add a new pref() call with your key, value, and optional sticky flag to persist across sessions (additions/browser/branding/camoufox/pref/firefox-branding.js)
3. If the preference affects the about dialog, update the dialog script (additions/browser/base/content/aboutDialog.js)
4. Trigger a rebuild via Makefile to verify the preference loads correctly (Makefile)

Update browser branding and visual identity

1. Replace icon files in the platform-specific asset directories (additions/browser/branding/camoufox/Assets.xcassets)
2. Update SVG/PNG assets in the content directory (additions/browser/branding/camoufox/content/)
3. Modify the about dialog layout and styling (additions/browser/base/content/aboutDialog.xhtml)
4. Update CSS for the about dialog (additions/browser/branding/camoufox/content/aboutDialog.css)
5. Rebuild browser packages for all platforms (Makefile)

Add localization for a new language

1. Create a new locale directory following the ISO 639 naming convention (additions/browser/branding/camoufox/locales/)
2. Copy and translate the brand DTD file (additions/browser/branding/camoufox/locales/en-US/brand.dtd)
3. Copy and translate the brand FTL (Fluent) file (additions/browser/branding/camoufox/locales/en-US/brand.ftl)
4. Update the jar.mn manifest to register the new locale (additions/browser/branding/camoufox/locales/jar.mn)
5. Rebuild to include the new locale in the package (Makefile)

• Firefox / Gecko Engine — Well-audited open-source browser engine with extensive customization hooks via preferences and patches; enables fine-grained control over fingerprinting and behavioral mimicry
• Bash/Makefile build system — Aligns with Mozilla's build conventions; allows reproducible cross-platform compilation (Linux, macOS, Windows)
• Docker containerization — Enables headless execution in restricted environments (cloud, CI/CD); simplifies deployment for LLM automation workflows
• NSIS + MSI/MSIX installers — Standard Windows distribution formats; ensures signed and verifiable packages for end-user trust
• GitHub Actions CI/CD — Automates multi-platform builds on every commit; provides public transparency for release artifacts

• Inherit from Firefox rather than build a browser from scratch

  • Why: Dramatically reduces engineering effort and leverages mature browser infrastructure
  • Consequence: Bundle size is large (~80–200MB); updates depend on Firefox release cadence; forking complexity when Firefox internals change

• Preference-based anti-detect vs. native C++ engine patches

  • Why: Faster iteration and easier maintenance; preferences can be updated without recompilation
  • Consequence: Some detections may require deeper patches; preference overrides can be reset if user clears profile

• Single search extension (none) vs. integration of multiple providers

  • Why: Reduces fingerprinting surface and prevents accidental data leakage
  • Consequence: Users cannot easily switch search engines; less flexible than stock Firefox

• Checkpoint releases on this repo vs. active development on CloverLabsAI/camoufox

  • Why: Decouples stable releases from rapid experimental development
  • Consequence: Latest features may not be in this repo; contributors must check multiple sources

• Real-time synchronization with Firefox release cycles (asynchronous checkpoint model)
• GUI-based browser configuration or settings UI (headless automation focus)
• Cloud sync or profile backup (privacy-first, no external backends)
• Support for arbitrary browser extensions (restricted extension set only)
• Guaranteed imperceptibility from sophisticated bot-detection (cat-and-mouse with evolving detection)

Development split: upstream active work is at CloverLabsAI/camoufox and VulpineOS/VulpineOS, not this repo—PRs here are checkpoint merges only. Browser compilation likely requires Mozilla build dependencies (not listed). No visible requirements.txt or pyproject.toml in file list—check for hidden Python build config. NSIS installer needs Windows build environment. QML modules may require Qt dependencies not documented in repo root.

• Browser Fingerprinting & Spoofing — Core to Camoufox—understanding how sites identify bots via user-agent, canvas, WebGL, and navigator APIs is essential to understand why specific JavaScript patches exist in additions/browser/base/content/
• Firefox XUL/XBL Customization — The additions/browser/ directory is a Firefox XUL overlay/patch system—necessary to understand how to modify browser internals
• Content Scripts & WebExtension APIs — TypeScript/JavaScript in additions/browser/base/content/ runs in page context—understanding content isolation and messaging is key to modifying detection evasion
• Headless Browser Execution — Camoufox is optimized for headless AI agent deployments via Docker—understanding headless detection vectors (missing display server, performance APIs) explains why certain patches exist
• TLS/HTTP Fingerprinting — Anti-detect systems detect bots via TLS cipher suites and HTTP header order—Camoufox must normalize these at the C++ level in the networking stack
• Platform-Specific Browser Builds — build.yml and branding/camoufox/configure.sh handle Windows (NSIS), macOS (Assets.xcassets), and Linux builds—understanding cross-platform binary differences is crucial for anti-detect consistency

• CloverLabsAI/camoufox — Primary upstream development fork where active browser improvements and anti-detect features are being built
• VulpineOS/VulpineOS — Companion OS-level optimizations and system integration for Camoufox anti-detect hardening
• puppeteer/puppeteer — Comparable browser automation framework (Chromium-based) for comparison on detection evasion strategies
• SeleniumHQ/selenium — Industry standard browser automation tool that Camoufox augments with stronger anti-detect protections
• mozilla/firefox — Upstream Firefox repo—Camoufox is a downstream fork with customizations on top of this codebase

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for cross-platform browser builds

The repo has a Dockerfile and Makefile suggesting complex build processes, but .github/workflows/build.yml exists without visible content in the file structure. A complete CI/CD workflow is critical for an anti-detect browser that needs to build and test on Linux, macOS, and Windows. This prevents regressions in browser compilation and ensures the distributed binaries work across platforms.

• [ ] Examine existing .github/workflows/build.yml and identify gaps in build matrix (Linux/macOS/Windows)
• [ ] Add matrix strategy to build Camoufox on all three platforms
• [ ] Integrate Dockerfile build step into GitHub Actions for containerized consistency
• [ ] Add artifact upload step to preserve built browser binaries from successful runs
• [ ] Document build requirements in CONTRIBUTING.md with specific platform prerequisites

Create integration tests for anti-detection features

Camoufox is an anti-detect browser, but there are no visible test files in the repo structure. A new contributor could add browser automation tests (using Playwright/Puppeteer against Camoufox) to verify core anti-detection claims: fingerprint randomization, header spoofing, WebGL canvas masking, etc. This ensures detection avoidance actually works and prevents regressions.

• [ ] Create tests/ directory with test suite structure
• [ ] Add tests for common detection vectors (navigator.userAgent, navigator.platform, canvas fingerprinting, WebGL renderer)
• [ ] Set up test runner (Jest or similar given package.json has typescript/esbuild) in tests/setup.ts
• [ ] Document test execution in CONTRIBUTING.md and create tests/README.md with detection test methodology
• [ ] Add test execution to GitHub Actions workflow from PR #1

Document browser customization API with code examples

The README indicates Camoufox is 'optimized for LLM automation' and the file structure shows branding customization (Assets.xcassets, icon files), but there's no visible API documentation for configuring the browser programmatically. A new contributor could create docs/API.md with concrete examples showing how to instantiate Camoufox with custom profiles, spoof configurations, and automation hooks.

• [ ] Create docs/API.md with sections for profile creation, header spoofing, and fingerprint randomization
• [ ] Add Python code examples (given PyPI package mentioned in README) showing basic usage patterns
• [ ] Document the relationship between additions/browser/branding structure and runtime customization
• [ ] Include examples of how to use with common automation tools (Playwright, Selenium, etc.)
• [ ] Add API.md to README.md table of contents and link from main documentation sections

• Add Python type hints to the root-level Python package (check setup.py/pyproject.toml) to improve IDE support and catch automation bugs early—impacts all Python users.
• Create a Makefile target for running integration tests against camoufox.com (or similar test site) to validate detection evasion—currently no test suite visible in file structure.
• Document the TypeScript/JavaScript injection system by adding code comments to additions/browser/base/content/*.js files explaining fingerprint spoofing logic—critical for maintainability.

• High · Insecure Docker Base Image — Dockerfile, line 1. The Dockerfile uses 'ubuntu:latest' as the base image without specifying a fixed version. This creates reproducibility issues and security risks as the base image can change unexpectedly, potentially introducing vulnerabilities. Additionally, the image is not hardened or minimized. Fix: Pin to a specific Ubuntu LTS version (e.g., 'ubuntu:22.04') and consider using a minimal base image. Implement multi-stage builds to reduce final image size and attack surface.
• High · Unvalidated Remote Script Execution — Dockerfile, line 16. The Dockerfile executes a remote shell script from rustup.rs via curl without verification: 'curl https://sh.rustup.rs -sSf | bash -s -- -y'. This is a critical security risk as the script is not validated, checksummed, or inspected before execution. Fix: Download the Rust installer to a file, verify its checksum against official sources, review the script contents, then execute. Alternatively, use a package manager or pre-built container image.
• High · Missing Package Verification in APT Install — Dockerfile, lines 8-14. The Dockerfile runs 'apt-get update && apt-get install -y' without version pinning. The '-y' flag automatically accepts all packages without verification, which could install unintended or malicious package versions. Fix: Pin specific package versions (e.g., 'package=1.0.0-1ubuntu1'). Remove the '-y' flag or implement explicit verification. Add security scanning of installed packages.
• Medium · Outdated Dependencies — package.json, devDependencies. The package.json uses caret (^) version constraints for esbuild and typescript, allowing minor and patch version updates automatically. This could introduce breaking changes or security vulnerabilities without explicit review. Fix: Use exact version pinning (remove ^ and ~) or use a lock file (package-lock.json or yarn.lock). Regularly audit and update dependencies using 'npm audit' or similar tools.
• Medium · Exposed Docker Volumes Without Access Controls — Dockerfile, lines 22-23. The Dockerfile defines VOLUME mounts for '/root/.mozbuild' and '/app/dist' without specifying mount options or access controls. This could allow container escapes or unauthorized data access. Fix: Specify mount options explicitly in docker-compose or run commands (e.g., ':ro' for read-only). Implement proper file permissions and user isolation. Use named volumes with proper driver options.
• Medium · Insufficient HTTPS Certificate Validation — Dockerfile, lines 16 and 11 (curl/wget/aria2 calls). Multiple downloads occur via HTTP/HTTPS (curl, aria2) without explicit certificate validation flags. While 'ca-certificates' is installed, relying on defaults may not catch all MITM attacks. Fix: Explicitly validate certificates using '--cacert' or environment variables. Use package managers with built-in verification when possible. Implement hash verification for critical downloads.
• Medium · Running Docker Container as Root — Dockerfile (implicit root user). The Dockerfile does not specify a USER directive and runs all commands as root by default. This violates the principle of least privilege and increases the impact of any container compromise. Fix: Create a non-root user and switch to it before the ENTRYPOINT. Example: 'RUN useradd -m camoufox' and 'USER camoufox'.
• Low · Missing Security Headers and Metadata — Dockerfile. The Dockerfile lacks LABEL directives for security metadata (maintainer, version, security contact) and does not include HEALTHCHECK directives for runtime monitoring. Fix: Add LABEL directives with security metadata. Include HEALTHCHECK instructions. Add build information and vulnerability scanning metadata.
• Low · No Input Validation for Build Scripts — Dockerfile, line. The Dockerfile calls 'make setup-minimal && make mozbootstrap' without validating the Makefile or build parameters. If the Makefile is compromised, arbitrary code could execute. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.