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/mozilla-mobile/firefox-ios 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 today
• 27+ active contributors
• Distributed ownership (top contributor 15% of recent commits)
• MPL-2.0 licensed
• CI configured
• ⚠ No test directory 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 mozilla-mobile/firefox-ios repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mozilla-mobile/firefox-ios.

What it runs against: a local clone of mozilla-mobile/firefox-ios — 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 mozilla-mobile/firefox-ios | 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 ≤ 30 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mozilla-mobile/firefox-ios(\\.git)?\\b" \\
  && ok "origin remote is mozilla-mobile/firefox-ios" \\
  || miss "origin remote is not mozilla-mobile/firefox-ios (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 "BrowserKit/Package.swift" \\
  && ok "BrowserKit/Package.swift" \\
  || miss "missing critical file: BrowserKit/Package.swift"
test -f "BrowserKit/Sources/Common/DependencyInjection/AppContainer.swift" \\
  && ok "BrowserKit/Sources/Common/DependencyInjection/AppContainer.swift" \\
  || miss "missing critical file: BrowserKit/Sources/Common/DependencyInjection/AppContainer.swift"
test -f "BrowserKit/Sources/Common/Constants/AppConstants.swift" \\
  && ok "BrowserKit/Sources/Common/Constants/AppConstants.swift" \\
  || miss "missing critical file: BrowserKit/Sources/Common/Constants/AppConstants.swift"
test -f ".fxios.yaml" \\
  && ok ".fxios.yaml" \\
  || miss "missing critical file: .fxios.yaml"
test -f ".github/workflows/firefox-ios-ui-tests.yml" \\
  && ok ".github/workflows/firefox-ios-ui-tests.yml" \\
  || miss "missing critical file: .github/workflows/firefox-ios-ui-tests.yml"

# 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/mozilla-mobile/firefox-ios"
  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).

Firefox for iOS and Focus for iOS are two production iOS browsers maintained by Mozilla. Firefox iOS is a full-featured browser with sync, autofill, and privacy features, while Focus iOS is a privacy-focused variant. Both are written in Swift 6.2, targeting iOS 15.0+, and share a monolithic codebase where they can diverge functionality while reusing core components. Monolithic repository with two separate Xcode projects: firefox-ios/Client.xcodeproj (Fennec scheme) for Firefox and firefox-ios/Blockzilla.xcodeproj for Focus. Both share underlying Swift libraries via SPM (.swiftpm/xcode/). Configuration is centralized (.fxios.yaml, .swiftlint.yml), with automation hooks (.githooks/pre-push) and localization managed through .github/l10n/.

iOS developers and contributors who want to build or contribute to a production-grade mobile browser, privacy engineers who need to understand how Firefox implements privacy features on iOS, and QA/test engineers working on UI and integration testing for mobile browsers.

Highly mature and production-ready. The project has extensive CI/CD pipelines (.github/workflows/ contains 30+ workflow files), uses SwiftLint for code quality, supports multiple Xcode versions (26.3), and is actively maintained as evidenced by the bootstrap tooling (fxios-ctl) and frequent automation updates. This is a shipped, App Store-distributed product with established release processes.

Low risk from abandonment, but moderate complexity risk: the monorepo structure (housing both Firefox and Focus) increases surface area for breaking changes. Dependencies on Mozilla's remote settings, Nimbus experiments, and Rust components (via AppServices) mean external service failures can block builds. The codebase is large (17.6MB Swift), but well-governed (CODEOWNERS file present, contribution guardrails in workflows).

Active automation expansion and dependency management: recent workflows handle Kingfisher dependency checking, Rust component updates, Nimbus experiment syncing, autofill Playwright tests, and credential provider scripts. Localization is actively managed (l10n-linter, import-strings workflows). The repo uses Mergify for PR automation (.mergify.yml) and Taskcluster integration (.taskcluster.yml).

Install the fxios tool, then: brew tap mozilla-mobile/fxios && brew install fxios && fxios setup --https. This clones the repo and bootstraps both Firefox and Focus projects. For Firefox: open firefox-ios/Client.xcodeproj and select the Fennec scheme. For Focus: open focus-ios/Blockzilla.xcodeproj. If SPM fails, run Xcode > File > Packages > Reset Package Caches.

Daily commands: Open Client.xcodeproj (Firefox) or Blockzilla.xcodeproj (Focus) in Xcode 26.3+, select the appropriate scheme (Fennec for Firefox, default for Focus), and press Run (⌘R). No standalone dev server; this is a native app that runs in the Simulator or on device. Local debugging uses Xcode's debugger and Console app.

• BrowserKit/Package.swift — Defines the BrowserKit Swift Package with all core modules (WebEngine, Redux, Common, etc.) that form the architectural foundation for both Firefox and Focus iOS apps
• BrowserKit/Sources/Common/DependencyInjection/AppContainer.swift — Central dependency injection container managing service lifecycles and app-wide component registration—essential for understanding how services are wired
• BrowserKit/Sources/Common/Constants/AppConstants.swift — Global constants and configuration flags controlling feature toggles, URLs, and behavior across the entire application
• .fxios.yaml — Project configuration file defining build variants, feature flags, and environment-specific settings for Firefox iOS and Focus iOS builds
• .github/workflows/firefox-ios-ui-tests.yml — Primary CI/CD pipeline orchestrating UI tests, builds, and release automation—critical for understanding the development workflow
• BrowserKit/Sources/Common/Extensions/URLExtension.swift — URL parsing and validation utilities heavily used throughout the codebase for handling navigation, deep links, and web requests
• BrowserKit/README.md — Documents BrowserKit module organization, component responsibilities, and integration patterns essential for onboarding

Add a new utility extension (e.g., for String or URL)

1. Create or edit a new extension file in BrowserKit/Sources/Common/Extensions/ (BrowserKit/Sources/Common/Extensions/NewTypeExtension.swift)
2. Define extension methods following the existing pattern (e.g., URLExtension.swift) (BrowserKit/Sources/Common/Extensions/NewTypeExtension.swift)
3. Add the extension file to Package.swift in the Common target's source files array (BrowserKit/Package.swift)
4. Run tests to ensure the extension integrates without breaking existing code (.github/workflows/firefox-ios-ui-tests.yml)

Add a new global constant or configuration option

1. Determine the appropriate Constants file: AppConstants.swift for general config, LaunchArguments.swift for testing, NotificationConstants.swift for notifications (BrowserKit/Sources/Common/Constants/AppConstants.swift)
2. Add the constant as a static let or var in the appropriate struct/enum (BrowserKit/Sources/Common/Constants/AppConstants.swift)
3. If adding a feature flag, update .fxios.yaml to configure it per build variant (.fxios.yaml)
4. Document the constant's purpose and expected values with inline comments (BrowserKit/Sources/Common/Constants/AppConstants.swift)

Register a new service in dependency injection

1. Define the service interface (protocol) in the appropriate kit module (e.g., WebEngine, Redux) (BrowserKit/Sources/Common/DependencyInjection/ServiceProvider.swift)
2. Register the service instance in AppContainer.swift's initialization, following the existing pattern (BrowserKit/Sources/Common/DependencyInjection/AppContainer.swift)
3. Inject the service into dependent components via constructor or AppContainer reference (BrowserKit/Sources/Common/DependencyInjection/AppContainer.swift)
4. Write unit tests injecting mock services via AppContainer to verify integration (.github/workflows/firefox-ios-ui-tests.yml)

Add a new build variant or feature flag

1. Edit .fxios.yaml and add the variant configuration with feature flags and parameters (.fxios.yaml)
2. Define corresponding build channel enum case in AppBuildChannel.swift (BrowserKit/Sources/Common/Constants/AppBuildChannel.swift)
3. Add feature flag constants to AppConstants.swift keyed by build channel (BrowserKit/Sources/Common/Constants/AppConstants.swift)
4. Update CI/CD workflows (.github/workflows/*.yml) to build and test the new variant (.github/workflows/firefox-ios-build-contributor-pr.yml)

• Swift 6.2 with structured concurrency — Modern concurrency model eliminates race conditions; required for iOS 15+ and provides type-safe async/await
• Swift Package Manager (BrowserKit) — Modular architecture enables code sharing between Firefox iOS and Focus iOS; improves build times and testability
• Redux state management pattern — Centralizes app state, simplifies debugging, and enforces predictable state transitions across the complex browser UI
• Dependency Injection container (AppContainer) — Decouples services from their implementations; facilitates testing with mock objects and reduces tight coupling
• GitHub Actions CI/CD with Xcode 26.3 — Automated testing and building on every PR ensures code quality; supports multiple iOS versions (15.0+) and build variants

• Single BrowserKit package shared by Firefox iOS and Focus iOS

  • Why: Reduces code duplication and maintenance burden; ensures consistency across apps
  • Consequence: Slower iteration for app-specific features; requires careful API design to avoid coupling; larger package size if features are tightly bound

• Swift 6.2 as minimum (dropping older Swift versions)

  • Why: Enables use of modern language features (structured concurrency, strict concurrency checking)
  • Consequence: Requires developers to stay current with Swift toolchain; some legacy patterns become unavailable

• iOS 15.0+ minimum deployment target

  • Why: Enables use of SwiftUI 3+, modern URLSession APIs, and structured concurrency primitives
  • Consequence: Excludes users on iOS 14 and earlier; reduces addressable market but simplifies codebase

• Centralized global constants (AppConstants.swift, LaunchArguments.swift, NotificationConstants.swift)

  • Why: Single source of truth for configuration; easier to audit feature flags and build variants
  • Consequence: Risk of god object; requires discipline to avoid putting unrelated constants together

• Does not support iOS versions below 15.0
• Does not provide cross-platform support (iOS-only via native Swift/SwiftUI)
• Does not implement custom rendering engine (relies on WebKit WKWebView)

SPM dependency resolution can fail silently; always reset package caches before troubleshooting build errors (Xcode > File > Packages > Reset Package Caches). The monorepo uses fxios-ctl tool for proper setup—manual git cloning will miss bootstrap scripts. Firefox and Focus share code via SPM but have divergent schemes; selecting the wrong scheme in Xcode will cause confusing build failures. Remote settings and Nimbus experiments are fetched at runtime; network access is required for full feature testing. Pre-push hooks exist (.githooks/pre-push); ensure your fork doesn't skip them accidentally.

• Monolithic Repository Pattern — Understanding how Firefox and Focus coexist in one repo while maintaining separate schemes and build targets is critical for making changes that don't break the variant you're not actively testing
• Swift Package Manager (SPM) Dependency Resolution — This repo heavily relies on SPM for sharing code between Firefox and Focus; cache corruption is a common blocker, and understanding workspace semantics prevents mysterious build failures
• Xcode Build Schemes vs. Targets — The Fennec scheme (Firefox) and Focus scheme diverge at runtime; confusing these causes contributors to test the wrong variant or ship unintended features
• GitHub Actions Workflow Orchestration — 30+ workflows manage CI/CD, localization, dependency updates, and test runs; understanding the workflow DAG is essential for debugging merge blocks and green builds
• Nimbus A/B Testing Framework — Experiments are synced via github-ios-update-nimbus-experiments.yml; features may behave differently based on experiments, requiring test awareness
• Glean Telemetry — Glean probe definitions drive telemetry collection; the glean-probe-scraper.yml workflow validates probes, and understanding metric types is needed for adding instrumentation
• Localization (L10n) Linting — The .github/l10n/ linters enforce string consistency across locales; violating these rules blocks merges, so understanding linter_config_ios.json is necessary for working with user-facing strings

• mozilla/firefox-android — Android equivalent of this project; shares design philosophy and feature parity goals, useful for understanding cross-platform browser architecture decisions
• mozilla-mobile/focus-android — Android privacy-focused browser parallel to Focus iOS; reference for privacy feature implementation patterns
• mozilla/application-services — Provides the Rust components (sync, crypto, storage) that both Firefox and Focus iOS depend on; upstream for AppServices updates
• mozilla-mobile/fxios-ctl — Official setup and management tool for this repo; essential companion for environment setup and local development
• mozilla/glean — Telemetry SDK used by this project (glean-probe-scraper.yml); defines how Firefox/Focus report analytics

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 unit tests for BrowserKit modules with low coverage

The BrowserKit directory contains multiple Swift packages (ActionExtensionKit, ComponentLibrary, ContentBlockingGenerator, JWTKit, Logger, MenuKit, OnboardingKit, QuickAnswersKit, Redux) but there's no evidence of comprehensive unit test suites. New contributors can add XCTest-based unit tests for individual modules, starting with the most critical ones like Redux and Logger that are foundational to the app architecture.

• [ ] Identify which BrowserKit modules lack unit test targets by checking BrowserKit/Package.swift and looking for missing .testTarget entries
• [ ] Start with Redux module (state management is critical) - add tests for action dispatching, reducer logic, and middleware
• [ ] Add unit tests for Logger module to cover different log levels and output formats
• [ ] Run tests locally with swift test in BrowserKit directory and ensure CI workflow in .github/workflows/ runs these tests

Enhance .github/workflows/contribution-guardrails.yml with SwiftLint enforcement

The repo has .swiftlint.yml configuration file but the contribution-guardrails CI workflow appears minimal. New contributors can expand this workflow to enforce SwiftLint rules on all PRs, catching style issues early and maintaining code quality consistency across the codebase.

• [ ] Review current .github/workflows/contribution-guardrails.yml to see what checks are implemented
• [ ] Add SwiftLint step that runs against changed Swift files in PRs, using configuration from .swiftlint.yml
• [ ] Configure the action to post inline comments on violations in the PR diff
• [ ] Test by running the workflow locally or on a test branch to ensure it catches violations

Add missing UI test coverage workflow for BrowserKit ComponentLibrary

The repo has extensive UI test workflows for firefox-ios and focus-ios (.github/workflows/firefox-ios-ui-tests.yml, focus-ios-ui-tests.yml) but BrowserKit's ComponentLibrary (which contains reusable UI components) lacks dedicated UI testing validation. New contributors can create a workflow to snapshot test or validate ComponentLibrary components on iOS 15.0+ to prevent visual regressions.

• [ ] Create new workflow file .github/workflows/browserkit-component-ui-tests.yml
• [ ] Add job to build and run UI tests specifically for ComponentLibrary module with snapshot or XCUITest assertions
• [ ] Configure matrix to test against multiple iOS versions matching the 15.0+ requirement in README
• [ ] Integrate with existing PR checks so ComponentLibrary changes are validated before merge

• Add SwiftUI previews for existing UIView-based components in firefox-ios/firefox-ios/ to improve developer experience; many production views lack preview support for rapid iteration
• Expand .github/l10n/ linter coverage: add JSON schema validation for newly added localization keys to catch typos earlier in CI
• Create a basic developer guide documenting the distinction between Fennec (Firefox) and Blockzilla (Focus) schemes in the monorepo; new contributors consistently confuse which Xcode project to open

The Firefox iOS codebase demonstrates a reasonably mature security posture with proper use of GitHub Actions CI/CD, code linting infrastructure, and git hooks. However, potential risks exist around configuration file management, GitHub Actions security, and the lack of explicit security documentation. The main concerns are ensuring that configuration files don't contain hardcoded secrets, that all GitHub Actions workflows follow security best practices with pinned versions, and that dependency management is regularly audited. The project should implement secret scanning in pre-commit hooks and establish clear vulnerability disclosure guidelines. Overall, this appears to be a well-maintained Mozilla project with reasonable security controls, but security-specific hardening in workflow configurations and documentation would improve the security posture.

• Medium · Swift/Xcode Version Management — README.md, .swiftpm configuration files. The project requires Xcode 26.3 and Swift 6.2, which are bleeding-edge versions. While using latest versions is generally good for security patches, this can create compatibility issues and increased maintenance burden. Ensure all dependencies are regularly audited for security vulnerabilities. Fix: Regularly audit Swift dependencies using swift package audit (when available). Document Swift/Xcode version requirements in security guidelines and establish a regular update schedule.
• Medium · Potential Hardcoded Configuration Exposure — Root directory configuration files (.fxios.yaml, .cron.yml, .taskcluster.yml, .mergify.yml). Multiple configuration files (.fxios.yaml, .cron.yml, .mergify.yml, .taskcluster.yml) are present in the repository root. These files may contain sensitive configuration, deployment details, or secrets that could be exposed if not properly managed. Fix: Audit all YAML configuration files to ensure no secrets, API keys, or sensitive URLs are hardcoded. Use GitHub Secrets for CI/CD sensitive data. Implement pre-commit hooks to scan for secrets (using tools like TruffleHog or detect-secrets).
• Medium · GitHub Workflow Security Concerns — .github/workflows/ directory. Numerous GitHub Actions workflows are present (.github/workflows/). These workflows have access to repository secrets and could be vectors for supply chain attacks if not properly secured. Several workflows interact with external services (Kingfisher dependency, Rust components, remote settings, credentials provider). Fix: Implement workflow security best practices: (1) Pin action versions to specific commits rather than branches, (2) Use CODEOWNERS for workflow approvals, (3) Regularly audit third-party actions for vulnerabilities, (4) Implement least-privilege access for workflow secrets, (5) Review and approve all dependency updates before merge.
• Low · Pre-push Hook Configuration — .githooks/pre-push. A pre-push git hook exists (.githooks/pre-push) but content is not visible in the file structure. If this hook is not properly implemented or enforced, it may not effectively prevent insecure commits. Fix: Verify that the pre-push hook enforces security checks such as: secret scanning, linting, and security analysis. Document the hook requirements and ensure all developers have it configured via git config core.hooksPath .githooks.
• Low · SwiftLint Configuration Review — .swiftlint.yml. SwiftLint configuration exists (.swiftlint.yml) which is good for code quality. However, security-specific linting rules should be explicitly configured to catch common Swift security issues. Fix: Review SwiftLint configuration to ensure security rules are enabled, such as: force_unwrap warnings, insecure random number generation detection, and hardcoded string literals in network calls.
• Low · Missing SECURITY.md — Repository root. No visible SECURITY.md file in the repository root. This file should document security policies, vulnerability disclosure procedures, and supported versions for security patches. Fix: Create a SECURITY.md file that includes: (1) Security contact information, (2) Vulnerability disclosure policy, (3) Supported versions eligible for security updates, (4) Instructions for reporting security issues, (5) Response timeline expectations.

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.