The first iOS browser to bring ScriptCat-class power to userscripts — background execution, @crontab scheduling, and a sandboxed GM API — and run real Chrome Web Store extensions, all wrapped in a Chromium-inspired interface.

Features · Why BrownBear · How It Compares · Architecture · Contributing

iOS has never had a true power userscript runtime. Safari extensions like Userscripts and Stay brought Greasemonkey-style injection to mobile, and Gear Browser proved a dedicated userscript browser can ship on the App Store. But none of them deliver the one thing ScriptCat gives desktop users:

Scripts that keep working in the background — on a schedule — without a tab open.

BrownBear is that missing piece. A standalone browser that pairs a clean, Chromium-style interface with a sandboxed engine that runs @background userscripts driven by @crontab, all within the constraints Apple's WebKit and background-execution model allow — honestly and transparently, with every scheduled job visible and stoppable.

⚠️ iOS background execution is budgeted and best-effort by design — @crontab is a target schedule, not a hard real-time guarantee. BrownBear surfaces this honestly in the UI.

BrownBear is one app composed of four runtime planes — a foreground browser, a pure-logic engine, a security bridge, and a background scheduler:

            ┌────────────────────────── Foreground ──────────────────────────┐
 user ──▶ Omnibox ──▶ BrowserVC ──▶ WKWebView(tab) ──▶ injected runtime ──┐   │
            ▲              │                                               │   │
         TabGrid ◀─────────┘                                          GM calls │
            └─────────────────────── Bridge (WKScriptMessageHandler) ─────┘   │
                                            │                                  │
   Engine: ScriptMetadata · URLMatcher · InjectionPlanner  ◀── decides injection
                                            │                                  │
   Native GM services: Network(URLSession) · GMValueStore · Clipboard · Tabs   │
                                            │                                  │
            ┌──────────────────────── Background ─────────────────────────────┘
            BGTaskScheduler ──▶ CrontabEvaluator ──▶ headless JSContext ──▶ Logs
                                            │
   Storage: Core Data (Script, Schedule, LogEntry) + UserDefaults (GM values, namespaced)

📐 Full technical blueprint: ARCHITECTURE.md

🚧 Pre-alpha — actively being built. All six modules have landed — the Chromium-style browser, the userscript engine + sandbox, the @crontab background runner, the dashboard/editor, and the Chrome Web Store extension runtime (Module 6) — and the focus now is real-world hardening against shipping extensions (ScriptCat, uBlock Origin Lite, Violentmonkey, Grammarly, …). The engineering bar is App-Store-shippable code: no stubs, no mocks, no truncation (see CLAUDE.md and AGENTS.md). Where WebKit's extension-less model forces a limit, we degrade honestly and document it.

Requirements: Xcode 15+ · iOS/iPadOS 16.4+ deployment target · an Apple Developer account for on-device background-task testing.

Recommended: let GitHub Actions build it. CI on free macOS runners is the canonical build path — open a PR and it's built + tested automatically. To build locally, the Xcode project is generated from project.yml with XcodeGen:

git clone https://github.com/DudeAint/brownbear.git
cd brownbear
brew install xcodegen          # one-time
xcodegen generate              # creates BrownBear.xcodeproj from project.yml
open BrownBear.xcodeproj

Full instructions (CI, local, tests, lint): docs/BUILDING.md.

Reference repositories are documented in References/REFERENCES.md. We study their architecture; we never vendor their (GPL/AGPL) source.

We use Conventional Commits, feature branches, and green-main discipline. AI agents working in this repo must follow CLAUDE.md and AGENTS.md. Start with CONTRIBUTING.md.

This app executes untrusted JavaScript. Found a vulnerability? Follow the responsible-disclosure process in SECURITY.md — please don't open a public issue.

Every PR, script, and bug report makes BrownBear better. Thank you.

_{Avatar wall auto-generated by contrib.rocks — new contributors appear here after their first merged PR.}

If BrownBear is useful to you, a star helps others find it.

MIT © BrownBear contributors. BrownBear is an independent implementation; it learns architectural patterns from the projects in References/REFERENCES.md but contains no copied source from GPL/AGPL-licensed projects.

Inspired by ScriptCat · Userscripts · Stay · Gear Browser · and the iOS layer of Chromium.