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/Alex313031/thorium 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.

WAIT — Single-maintainer risk — review before adopting

• Last commit 1d ago
• 2 active contributors
• BSD-3-Clause licensed
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 93% of recent commits
• ⚠ No CI workflows detected

_{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 Alex313031/thorium repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Alex313031/thorium.

What it runs against: a local clone of Alex313031/thorium — 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 Alex313031/thorium | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 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 Alex313031/thorium. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Alex313031/thorium.git
#   cd thorium
#
# 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 Alex313031/thorium and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause 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"

# 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/Alex313031/thorium"
  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).

Thorium is a performance-optimized Chromium fork built for Linux with aggressive compiler optimizations (LTO, PGO, LLVM loop unrolling) and CPU-specific SIMD variants (SSE3/SSE4/AVX/AVX2). It maintains Chromium's full featureset while adding custom patches and enhancements, distributed as precompiled binaries for Linux and cross-compiled builds for Windows, macOS, Android, and Raspberry Pi. Monorepo structure: root contains shared build config (args.gn), platform-specific subdirectories (arm/android, arm/raspi with custom .gni files and patches), and documentation. arm/third_party/ vendored codec libraries (libaom, libvpx, widevine CDM). Patches stored as .patch files (e.g., arm/raspi/netflix.patch, arm/raspi/widevine-other-locations.patch) applied during build.

Linux users and power users seeking a faster, leaner Chrome alternative; ARM/embedded systems enthusiasts wanting Chromium on Raspberry Pi or Android; developers interested in Chromium fork architecture and optimization techniques; contributors to Chromium-based projects who want to test against a customized variant.

Actively developed with recent commits and tagged semantic releases; follows Chromium's LTS version cycle, ensuring stable base code. Appears production-ready for Linux desktop use given consistent binary releases and multi-platform build infrastructure. Single maintainer (Alex313031) presents continuity risk but project structure and GitHub Actions setup suggest sustainability.

Single-maintainer project creates bus-factor risk; rebuild complexity due to Chromium's massive dependency graph (126K+ C files, 3.5M C++ LOC) means security patches depend on upstream Chromium cadence. No visible test suite in repo root, relying entirely on Chromium's upstream testing. Cross-platform build fragmentation (separate repos for Win/Mac/Android/Pi) increases coordination overhead.

Ongoing sync with Chromium LTS releases (tracked in TODO.md); ARM/Raspberry Pi support maintenance (widevine CDM patching, custom raspi_args.gn); CPU-specific SIMD build variant releases. GitHub Issues and TODO.md indicate active discussion around feature parity and optimization tuning.

Clone the repo: git clone https://github.com/Alex313031/thorium.git && cd thorium. For Linux builds, run ./build.sh (inferred from standard Chromium build flow, though explicit script not shown). For ARM: cd arm && bash setup_arm.sh then build with arm-specific args. Requires Chromium depot_tools and full build toolchain.

Daily commands: Thorium is a browser, not a dev server. Run the built binary directly: ./out/Release/thorium-browser (Linux) after building. For development/rebuilding: gn gen out/Release --args='import("//args.gn")' then ninja -C out/Release chrome (standard Chromium build). Platform-specific: arm/raspi_args.gn for Pi builds, arm/android/*_args.gn for Android variants.

• args.gn: Master build configuration controlling compiler optimizations (LTO, PGO, SIMD flags) applied to all Linux builds
• arm/raspi/raspi_args.gn: Raspberry Pi-specific build args including ARM CPU tuning and custom codec/widevine configuration
• arm/setup_arm.sh: ARM build bootstrap script that patches and prepares the Chromium source for non-x86 targets
• arm/raspi/netflix.patch: Custom patch enabling Netflix/DRM content on Raspberry Pi by patching Widevine integration
• arm/third_party/widevine/cdm/linux/arm64/libwidevinecdm.so: Precompiled Widevine CDM binary for ARM64, enabling protected content playback on Pi/ARM devices
• README.md: Documents SIMD variants (SSE3/SSE4/AVX/AVX2), release strategy, and links to platform-specific forks (Win/Mac/Android/Pi repos)
• .github/ISSUE_TEMPLATE/: Bug report, feature request, and feedback templates indicating project's issue triage process

To add patches: place .patch files in arm/{platform}/ and reference in build scripts (e.g., netflix.patch, widevine patches in arm/raspi/). To tweak optimizations: edit args.gn or platform-specific .gni files (arm/mac_arm.gni, arm/raspi/raspi_args.gn) with compiler flags. To add new platforms: create arm/{newplatform}/ mirroring arm/raspi structure with custom args.gn and setup_arm.sh equivalent.

Chromium's depot_tools and full build toolchain (Clang, ninja, GN) must be installed and in PATH; no setup.sh handles this. Large disk space required (Chromium checkout ~20GB+). PGO builds require profile data collection (LLVM instrumentation pass); args.gn enables this but adds build time. Widevine CDM is pre-built binary only—recompilation not supported due to licensing. Cross-platform repos (Win/Mac/Android/Pi) are separate forks, not submodules, creating version sync overhead. No CI/CD visible in main repo; platform-specific builds rely on separate GitHub repos.

• Link Time Optimization (LTO) — Thorium's primary performance lever—LTO enables cross-file inlining and dead code elimination at link stage, critical for a 3.5M LOC C++ codebase; understanding LTO trade-offs (build time vs. runtime speed) is essential for tuning args.gn
• Profile-Guided Optimization (PGO) — Thorium uses LLVM PGO to retarget code generation based on real-world usage profiles; requires two-pass build (instrumentation + optimization) but yields significant speed gains on hot paths like HTML parsing
• SIMD (SSE3/SSE4/AVX/AVX2) — Thorium's release strategy of CPU-variant builds exploits vector instruction sets for media codec performance; knowing target CPU SIMD capabilities determines which binary to download and compile flags to use
• Widevine Content Decryption Module (CDM) — Thorium vendors Widevine binaries (arm/third_party/widevine/) for DRM-protected content; Netflix/Disney+ playback depends on CDM patching and licensing, making it a non-negotiable complexity for multi-platform support
• GN Build System — Chromium's meta-build language (args.gn, .gni files); mastering GN variable scoping and conditional imports is mandatory for adjusting Thorium's optimization flags per platform (raspi_args.gn vs. android args)
• Cross-compilation Targeting — Thorium's arm/ directory structure (raspi, android, generic ARM) requires setting target_cpu, target_os, and ARM-specific CPU tuning; critical for embedded/non-x86 builds where native compilation is infeasible
• Patch-based Fork Management — Thorium uses .patch files (netflix.patch, widevine-other-locations.patch) applied on top of Chromium source; understanding patch application order and conflict resolution is essential for rebasing to new Chromium LTS versions without losing customizations

• Alex313031/Thorium-Win — Official Windows build fork of Thorium using identical patches and optimizations but targeting Win7/10/11
• Alex313031/Thorium-Mac — Official macOS fork of Thorium with M1/ARM64 and x86-64 variants matching the main repository's optimization philosophy
• Alex313031/Thorium-Android — Official Android port of Thorium with arm32/arm64 builds using the same build configuration structure as arm/android/
• Alex313031/Thorium-Raspi — Dedicated Raspberry Pi release distribution mirroring the arm/raspi/ config from main repo with precompiled binaries
• chromiumos/chromium — Upstream Chromium project that Thorium tracks for LTS versions and core security patches

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.

Create unified build configuration documentation for arm/ and platform-specific args.gn files

The repo has scattered build configuration files across arm/android/, arm/raspi/, and root level (args.gn, arm/mac_arm.gni, arm/win_ARM_args.gn, arm/woa_arm.gni) with no central documentation explaining which args.gn to use for each platform or what each critical flag does. A new contributor cannot easily understand the build matrix. Creating a BUILD_CONFIG.md would document the purpose of each args file and provide decision tree for platform selection.

• [ ] Create BUILD_CONFIG.md at repo root documenting all args.gn variants (root args.gn, arm/raspi/raspi_args.gn, arm/android/*.gn, arm/mac_arm.gni, arm/win_ARM_args.gn, arm/woa_arm.gni)
• [ ] Add a decision matrix table showing which config file to use for each target platform (Linux x64, RasPi, Android arm32/arm64/x86, macOS ARM, Windows ARM)
• [ ] Document 5-10 most critical flags across configs (e.g., is_official_build, remove_webrtc_padding, enable_widevine) and their platform-specific values

Add GitHub Actions workflow for validating build configuration files (args.gn syntax)

With 8+ args.gn files scattered across arm/android/, arm/raspi/, and platform-specific locations, there's no CI validation that these GN configuration files are syntactically correct or that required variables are set. A failed build due to a typo in a rarely-tested config (e.g., arm/raspi/raspi_args.gn) might go undetected. Add a GitHub Action to validate GN syntax and cross-reference required variables.

• [ ] Create .github/workflows/validate-gn-configs.yml to run on PR when any *.gn or *.gni files change
• [ ] Use gn validate or gn format --dry-run against all args.gn files (root, arm/android/*, arm/raspi/raspi_args.gn, arm/mac_arm.gni, arm/win_ARM_args.gn)
• [ ] Add checks to ensure platform-specific required variables (e.g., is_debug in debug_args.gn) are defined, preventing silent build failures

Document and create test/validation scripts for third-party Widevine patches (arm/raspi/ and arm/android/)

The repo includes critical patches for Widevine DRM (arm/raspi/netflix.patch, arm/raspi/widevine_fixup.py, arm/raspi/widevine-other-locations.patch, and arm/third_party/widevine/) but has no documented validation process. Contributors cannot verify if patches still apply cleanly after Chromium upgrades or if Netflix/streaming playback regressions are patch-related. Create a validation script and document the Widevine patching workflow.

• [ ] Create arm/scripts/validate_widevine_patches.sh to check if netflix.patch and widevine-other-locations.patch apply cleanly against current Chromium third_party/widevine code
• [ ] Document in arm/README.md the Widevine patching workflow: when patches are applied, what they fix (Netflix/streaming), and how to test them
• [ ] Add a GitHub Action (.github/workflows/widevine-patch-validation.yml) that runs the validation script on PR when arm/third_party/widevine/ or arm/raspi/*.patch files change

• Add test coverage for patch application: arm/raspi/netflix.patch and arm/raspi/widevine-other-locations.patch lack verification scripts; create a shell test that validates patches apply cleanly and widevine_fixup.py output is correct.
• Document SIMD variant build instructions: README.md references SSE3/SSE4/AVX/AVX2 builds in Releases but the args.gn flags to enable each variant are not explicitly documented; add a docs/BUILD_VARIANTS.md with exact gn gen commands for each CPU feature level.
• Create ARM cross-compile Makefile: arm/setup_arm.sh is bash-only; add a Makefile target or standardized build wrapper in arm/ to reduce friction for contributors building for multiple ARM variants (raspi, android, generic arm64).

The Thorium Chromium fork demonstrates reasonable security practices by maintaining a SECURITY.md policy and tracking upstream CVE fixes. However, several concerns exist: (1) exposure of a personal email for security reports creates targeting risk, (2) inclusion of precompiled binaries without source auditability presents supply chain risks, (3) modifications to Widevine DRM may have legal implications, and (4) limited visibility into dependency management and build script safety. The project maintains good CVE tracking and upstream vulnerability awareness, which is a positive security indicator. Recommended actions focus on improving secure reporting channels, removing or properly sourcing precompiled binaries, and enhancing dependency transparency.

• Medium · Hardcoded Email in Security Policy — SECURITY.md. The SECURITY.md file contains a personal email address (Alex313031@gmail.com) for reporting zero-day vulnerabilities. This could lead to spam, phishing attempts, or social engineering attacks targeting the maintainer. Fix: Use a dedicated security reporting email address (e.g., security@thorium-project.org) or implement a vulnerability disclosure platform (e.g., Bugcrowd, HackerOne) instead of exposing a personal email address.
• Medium · Precompiled Binary Included — arm/raspi/libwidevinecdm_patched.so. The repository includes a precompiled binary file 'arm/raspi/libwidevinecdm_patched.so' which poses supply chain security risks. Binary files cannot be easily audited for malicious code, and their origins/integrity are difficult to verify. Fix: Remove precompiled binaries from the repository. Instead, provide build scripts to compile from source, or use official Widevine CDM distributions from Google with signature verification.
• Low · Widevine CDM Library Modifications — arm/raspi/. Multiple patches are applied to Widevine CDM libraries (widevine-other-locations.patch, netflix.patch, widevine_fixup.py), suggesting modifications to DRM-protected content. This may violate licensing agreements or DMCA provisions. Fix: Ensure all Widevine CDM modifications comply with Google's licensing terms and applicable copyright/DRM laws. Document the necessity and legality of these patches clearly.
• Low · Weak Dependency Management Visibility — .gitmodules, depot_tools/. The repository uses git submodules (visible in .gitmodules) for third-party dependencies, but no dependency lock file or version pinning manifest is visible in the provided structure. This could lead to unexpected upstream changes. Fix: Implement a software bill of materials (SBOM), maintain a DEPENDENCIES.md file, and regularly audit third-party dependencies for known vulnerabilities using tools like Dependabot or Snyk.
• Low · Build Scripts Without Input Validation — autobuild.sh, build.sh, build_android.sh, build_mac.sh, build_win.sh, clean.sh. Multiple shell scripts (build.sh, autobuild.sh, clean.sh, etc.) are present but cannot be fully analyzed. Build scripts often handle user input or environment variables that could be exploited. Fix: Audit all shell scripts for: (1) Unquoted variables that could cause injection, (2) Unsafe use of eval() or similar functions, (3) Proper input validation, (4) Use of set -euo pipefail flags.

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.