WAIT — Mixed signals — read the receipts

• Last commit today
• 4 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 51% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Helium is a privacy-first Chromium-based web browser built on the ungoogled-chromium foundation with heavy modifications for performance and ad-blocking. It strips Google integrations, adds honest ad-blocking via a forked uBlock Origin, and ships across macOS, Linux, and Windows through separate platform-specific repositories while maintaining a unified C++ codebase (2.5M LOC) for the core browser engine. Multi-repo monolith: this repo (imputnet/helium) contains the unified C++ Chromium fork with patches organized by vendor (patches/ directory), Python dev utilities (devutils/ with i18n, linting, patch validation), and CI configuration. Platform packaging (macOS/Linux/Windows) and services (uBlock fork, onboarding site) live in separate repos linked in docs, not here.

Privacy-conscious end-users seeking a Chromium browser without Google telemetry, and open-source contributors who want to modify a real browser codebase without Google's bloat. Also relevant for developers packaging Chromium for specific platforms (macOS, Linux, Windows) as reference implementations.

Currently in beta (stated in README), indicating active development but not production-stable. The project has CI/CD setup (.cirrus.yml, GitHub Actions workflows for linting and releases), uses Chromium version pinning (chromium_version.txt), and maintains dev tooling (devutils/ with pytest, yapf, pylint). Verdict: actively developed but pre-release—expect breaking changes and use at own risk.

High complexity due to upstream Chromium dependency tracking (chromium_version.txt suggests frequent rebasing), patch-heavy architecture (patches/ directory indicates 100+ custom patches across vendors), and distributed maintenance across 4 platform repos (helium-macos, helium-linux, helium-windows, helium-services). Single-org ownership (imputnet) means repo survivability depends on org commitment; beta status signals incomplete stability.

Actively building toward stable release (beta status). Recent work includes i18n infrastructure (i18n.py, i18n_generate.py, i18n_translate.py in devutils/), CI improvements (.github/workflows/ with cirrus, linting, release automation), and patch management tooling (check_patch_files.py, check_gn_flags.py). GitHub Actions workflows show lint and release-and-tag automation running regularly.

See helium-macos development docs (macOS recommended per README). For this repo specifically: git clone https://github.com/imputnet/helium.git && cd helium, then check .cirrus.yml and .cirrus_Dockerfile for build requirements (Python dependencies in .cirrus_requirements.txt). Linux mirrors the macOS guide; consult helium-linux repo.

Daily commands: Not a runnable CLI/server repo—it's a browser source tree. Build via platform repos: macOS: ./scripts/build.sh (see helium-macos), Linux: similar script (see helium-linux). This repo alone requires Chromium build toolchain (not trivial). Run CI locally: bash devutils/run_devutils_tests.sh and bash devutils/check_all_code.sh for linting.

• README.md — Entry point explaining Helium as a Chromium-based privacy-first browser; defines project scope and download locations.
• flags.gn — GN build configuration flags for Chromium compilation; essential for understanding browser feature toggles and security settings.
• chromium_version.txt — Tracks the Chromium base version used; critical for understanding compatibility and security patch alignment.
• downloads.ini — Dependency manifest specifying third-party components, patches, and assets needed for building the browser.
• domain_substitution.list — Domain rewriting rules for privacy; defines how URLs are substituted to remove tracking and analytics domains.
• devutils/validate_patches.py — Validates all patch files applied to Chromium; ensures patches are consistent and apply cleanly.
• .cirrus.yml — CI/CD orchestration for multi-platform builds; defines build and test workflows for macOS, Linux, and Windows.

Add a new privacy domain substitution rule

1. Add the domain pattern to domain_substitution.list (for simple domain rewrites) or domain_regex.list (for regex patterns) (domain_substitution.list)
2. Validate the syntax by running the devutils configuration checker (devutils/validate_config.py)
3. Test that the domain is correctly rewritten in the browser by rebuilding with flags.gn applied (flags.gn)

Add a new Chromium patch

1. Create the patch file in the appropriate platform directory (referenced in downloads.ini) (downloads.ini)
2. Add patch metadata and source information to downloads.ini (downloads.ini)
3. Validate patch integrity with the patch validation utility (devutils/validate_patches.py)
4. Ensure patch applies cleanly by running the check script (devutils/check_patch_files.py)

Add support for a new language translation

1. Define the new language in the languages.json configuration (i18n/languages.json)
2. Create a translation file in i18n/translations/ following the pattern of existing translations (i18n/translations/en-GB.json)
3. Add language owner/maintainer info to i18n/owners.yml (i18n/owners.yml)
4. Validate translation completeness with the i18n linter (devutils/i18n_lint.py)

Add a new build configuration flag

1. Add the GN flag definition to flags.gn with its intended purpose and value (flags.gn)
2. Verify the flag is valid by running the GN flag checker (devutils/check_gn_flags.py)
3. Update build documentation if the flag affects public/notable behavior (CONTRIBUTING.md)

• Chromium base — Industry-standard rendering engine with mature security infrastructure; enables browser functionality while allowing fine-grained customization through patches and GN flags.
• GN build system — Chromium's native build system; allows declarative feature toggling (flags.gn) without forking the entire engine.
• Patch-based customization — Enables privacy/security enhancements while maintaining synchronization with upstream Chromium releases; tracks changes through downloads.ini.
• Cirrus CI for multi-platform builds — Native container support for macOS, Linux, and Windows; scales concurrent platform builds without manual configuration per OS.
• Domain substitution lists — Lightweight, human-readable mechanism for removing tracking domains without modifying core Chromium code; enables rapid privacy rule updates.

• Use patches instead of a full Chromium fork

  • Why: Reduces maintenance burden and complexity when upstream Chromium updates are released.
  • Consequence: Patch conflicts may occur during version upgrades; requires patch validation tooling (validate_patches.py).

• Declarative GN flags over runtime feature toggles

  • Why: Compile-time customization reduces binary size and attack surface by eliminating unused code.
  • Consequence: Feature changes require full browser rebuild; cannot toggle features at runtime.

• Multi-platform builds with separate repos (macOS, Linux, Windows)

  • Why: Allows platform-specific optimization and packaging without cross-platform bloat.
  • Consequence: Increased coordination overhead; changes must be synchronized across three separate repositories.

• Open-source patches and configuration (domain_substitution.list, flags.gn)

  • Why: Transparency aligns with privacy-first positioning; users can audit what is removed/changed.
  • Consequence: Competitors can easily copy privacy improvements; no proprietary advantage.

• Real-time, cloud-based sync across devices
• Integration with proprietary telemetry or advertising platforms
• Support for older Chromium versions; targets only current stable release track
• In-browser AI features (no LLM integration)
• Custom content rendering engines beyond Chromium's Blink

Chromium version coupling: patches are tightly bound to chromium_version.txt; upgrading Chromium often requires rebasing all patches in patches/ (non-trivial). Distributed builds: you cannot fully build Helium from this repo alone—platform-specific repos (helium-macos, helium-linux, helium-windows) contain platform packaging logic. Patch conflicts: multiple vendor patches (Brave, Debian, Bromite, etc.) may conflict; check patch ordering and test before committing. Build toolchain: requires Chromium's gn build system, not Make/CMake; see .cirrus_Dockerfile for exact deps. i18n assets: devutils/i18n_*.py scripts assume specific translation file structure—missing or malformed strings cause CI failures. Python version: devutils requires specific Python version (check .cirrus_requirements.txt, likely 3.8+). Cirrus config secrets: .cirrus.yml may reference encrypted env vars for release signing (inaccessible in forks).

• Patch-based Chromium forking — Helium maintains 100+ patches across vendors (patches/ directory) rather than forking Chromium monolithically—understanding patch ordering, rebase conflicts, and vendor compatibility is essential for any major Chromium upgrade
• GN build system — Chromium uses GN (not Make/CMake); devutils/check_gn_flags.py validates build flags, and contributors must understand .gn and BUILD.gn syntax to modify browser features
• Chromium version pinning and rebasing — chromium_version.txt locks a specific Chromium revision; upgrading forces rebasing all patches in patches/, a multi-day process—critical for understanding release delays and stability windows
• Internationalization (i18n) pipeline — devutils/i18n_*.py scripts manage multi-language browser UI strings; understanding .json/.txt string files and translation workflows is needed to add new UI or modify existing strings
• Vendor-organized patch hygiene — Patches are grouped by source (Brave, Debian, Bromite, Inox, Iridium) in patches/{vendor}/ for conflict isolation and credit; maintaining this organization prevents merge chaos during upstream rebases
• CI/CD for multi-platform browser builds — Helium uses Cirrus CI (.cirrus.yml) and GitHub Actions (.github/workflows/) to build on macOS, Linux, Windows simultaneously; understanding containerization (Dockerfile) and cross-platform secrets is needed for release automation
• ungoogled-chromium config inheritance — Helium inherits ungoogled-chromium's deps.ini and configuration system; understanding what ungoogled-chromium disables (Google API keys, crash reporting, etc.) helps avoid re-enabling tracked features

• ungoogled-software/ungoogled-chromium — Direct upstream base: Helium forks ungoogled-chromium's Chromium modifications and build system before adding privacy and ad-blocking features on top
• imputnet/uBlock — Helium's integrated ad-blocker—a fork of uBlock Origin customized specifically for Helium's privacy model and included in the browser
• imputnet/helium-macos — Platform packaging and tooling for Helium on macOS; contains development setup docs and app signing logic referenced in this repo's README
• imputnet/helium-linux — Platform packaging and build scripts for Linux; mirrors macOS dev setup for non-macOS contributors
• imputnet/helium-services — Helium's web services (sync, onboarding, telemetry endpoints); integrates with the browser built by this repo

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 comprehensive unit tests for devutils patch validation pipeline

The devutils directory contains critical patch validation logic (validate_patches.py, check_patch_files.py) with existing tests in devutils/tests/, but coverage appears incomplete. The test_validate_patches.py and test_check_patch_files.py files are minimal stubs. Given that this repo manages Chromium patches (evident from chromium_version.txt and patch workflows), robust patch validation is essential to prevent build failures. Adding comprehensive test cases would catch regressions early.

• [ ] Expand devutils/tests/test_validate_patches.py with test cases for: malformed patches, missing file references, invalid hunk headers, and edge cases in patch application
• [ ] Expand devutils/tests/test_check_patch_files.py with tests for file existence validation, path traversal attempts, and integration with check_gn_flags.py
• [ ] Add pytest fixtures in devutils/tests/init.py for generating temporary patch files and mock Chromium source structures
• [ ] Update .github/workflows/lint.yml to run devutils tests as a required CI check (currently only runs lint)

Add GitHub Actions workflow for validating i18n changes

The repo has sophisticated i18n tooling (devutils/i18n.py, i18n_translate.py, i18n_lint.py) and a .github/workflows/i18n-notify.yml that sends notifications, but no CI workflow validates i18n changes before merge. The CONTRIBUTING.md likely references i18n practices but they're not enforced. This prevents contributors from catching translation syntax errors, missing keys, or invalid locale formats early.

• [ ] Create .github/workflows/i18n-validate.yml that runs on PRs modifying files in localization directories
• [ ] Add workflow steps: run devutils/i18n_lint.py to validate translation file syntax, run devutils/validate_config.py for locale metadata, and check that new keys are properly documented
• [ ] Add step to verify no hardcoded strings appear in core source files using a simple grep pattern
• [ ] Configure workflow to comment on PRs with specific i18n linting failures (e.g., 'Missing translation for key X in locale Y')

Create integration test suite for platform-specific patch application

The repo uses update_platform_patches.py to manage platform-specific patches (referenced in .github/actions/bump-platform/), and .cirrus.yml indicates multi-platform testing, but there's no explicit integration test validating that patches apply cleanly across platforms. The Cirrus CI setup exists but patch application success isn't formally tested. This is critical since misapplied patches can cause silent build failures on specific platforms.

• [ ] Create devutils/tests/test_platform_patches.py with integration tests that: validate each platform's patches in deps.ini can be parsed, check that platform-specific patch sets don't conflict with base patches, and simulate patch application against a minimal Chromium source stub
• [ ] Add test coverage for edge cases: patches with DOS line endings, patches targeting different Chromium versions (tracked in chromium_version.txt), and cross-platform line-ending issues
• [ ] Update .github/workflows/lint.yml to run these tests, or create a new .github/workflows/patch-validation.yml that runs on changes to devutils/update_platform_patches.py, deps.ini, or .cirrus.yml
• [ ] Document test setup in devutils/README.md with instructions for running platform patch tests locally

• Add unit tests for devutils/check_gn_flags.py validation logic—currently no test coverage visible in devutils/pytest.ini despite GN flag validation being safety-critical for builds.
• Expand devutils/i18n_lint.py to validate translation completeness across all locales listed in i18n output—currently only syntax-checks, no coverage reporting per language.
• Create a devutils/patch_graph.py script to visualize patch dependencies and conflicts (which vendor patches touch which Chromium files)—helpful for understanding patch interactions and reducing merge conflicts during Chromium upgrades.

• Medium · Potential Hardcoded Credentials in CI/CD Configuration — .cirrus.yml, .cirrus_Dockerfile, .cirrus_requirements.txt. The presence of .cirrus.yml and .cirrus_Dockerfile suggests CI/CD pipeline configuration. Cirrus CI configurations may contain sensitive environment variables, credentials, or secrets that could be exposed if not properly managed. The .cirrus_requirements.txt file may also contain pinned dependencies with known vulnerabilities. Fix: Ensure all secrets are stored in Cirrus CI's encrypted secrets management system. Never commit credentials, API keys, or tokens to the repository. Audit CI/CD configuration files for any hardcoded sensitive data. Use secret rotation policies.
• Medium · Dependency Management Risks in Python Utilities — devutils/, devutils/third_party/unidiff, .cirrus_requirements.txt. The devutils directory contains multiple Python scripts that process patches, configurations, and build artifacts. Without visibility into requirements files or dependency pinning, these scripts may be vulnerable to supply chain attacks or known vulnerabilities in transitive dependencies. The third_party/unidiff module is included but may not receive security updates. Fix: Implement strict dependency pinning with hash verification. Regularly audit dependencies using tools like safety, pip-audit, or similar. Consider vendoring critical third-party code with security review. Document all third-party dependencies and their purposes.
• Medium · Internationalization (i18n) Data Integrity Risks — i18n/, devutils/i18n_generate.py, devutils/i18n_translate.py. The i18n/translations/ directory contains numerous JSON translation files that are auto-generated. If the i18n generation process (devutils/i18n_generate.py, devutils/i18n_translate.py) is not properly validated, it could introduce XSS vulnerabilities or malicious content through translated strings that are later rendered in the browser UI without proper sanitization. Fix: Implement strict validation of i18n translation files before merging. Sanitize all translated strings before rendering in UI. Use Content Security Policy (CSP) headers. Implement automated tests to verify no script injection in translations. Review i18n contribution workflows for access controls.
• Medium · Patch File Processing Without Strict Validation — devutils/validate_patches.py, devutils/check_patch_files.py, devutils/update_platform_patches.py, devutils/tests/test_validate_patches.py. Multiple devutils scripts process patch files (validate_patches.py, check_patch_files.py, update_platform_patches.py). If these validators don't properly sanitize or validate patch content, malicious patches could be applied to the Chromium codebase, potentially introducing vulnerabilities at the source level. Fix: Ensure patch validation includes checks for: path traversal attacks, suspicious modifications to security-critical files, and code injection vectors. Implement cryptographic signing and verification of patches. Add integration tests that verify patch safety. Require code review for all patch modifications.
• Low · Domain Substitution List Processing — domain_substitution.list, domain_regex.list. The domain_substitution.list and domain_regex.list files are used for DNS/domain handling. If not properly validated, these could be manipulated to redirect traffic or create security policy bypasses, particularly in a privacy-focused browser. Fix: Implement strict validation for domain list entries to prevent regex injection. Use a whitelist-based approach rather than blacklist. Add tests to verify the regex patterns are syntactically correct and don't cause denial of service. Consider signing these lists with cryptographic keys.
• Low · Missing Security.md or Vulnerability Disclosure Policy — Repository root. No visible security policy or responsible disclosure guidelines found in the repository structure. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file documenting the vulnerability disclosure process. Include contact information, expected response times, and whether bounties are offered. Consider using GitHub's security advisory features.
• Low · Stale Issue Management Without Security Consideration — .github/workflows/stale.yml. The .github/workflows/stale.yml workflow automatically closes stale issues, which could inadvertently close security-related issues if not properly tagged or monitored. Fix: Ensure security-related issues are labeled with an exemption tag (e.g., 'security',

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

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

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/imputnet/helium 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.

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

What it runs against: a local clone of imputnet/helium — 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 imputnet/helium | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.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 ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of imputnet/helium. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/imputnet/helium.git
#   cd helium
#
# 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 imputnet/helium and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.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 "flags.gn" \\
  && ok "flags.gn" \\
  || miss "missing critical file: flags.gn"
test -f "chromium_version.txt" \\
  && ok "chromium_version.txt" \\
  || miss "missing critical file: chromium_version.txt"
test -f "downloads.ini" \\
  && ok "downloads.ini" \\
  || miss "missing critical file: downloads.ini"
test -f "domain_substitution.list" \\
  && ok "domain_substitution.list" \\
  || miss "missing critical file: domain_substitution.list"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/imputnet/helium"
  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).

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