AmniShield is a 100% free and open-source, privacy-first digital wellness and distraction blocker for Android. Engineered with Kotlin and Jetpack Compose, it empowers users to reclaim focus by intercepting addictive short-form video reels, scheduled app blocking, keyword filtering, and strict anti-bypass modes without transmitting any screen data or telemetry to remote servers.
- Google Play Pre-Registration & Open Testing: Join the Beta on Google Play | Play Store Listing
- Direct APK Downloads: Available on GitHub Releases (
universalfor standard Google Play Services devices,fdroidfor de-Googled ROMs). - Bug Reports & Issues: Found a bug or want to suggest an improvement? Submit an issue using our GitHub Issue Tracker.
- Short Video & Reel Blocker: Surface-level interception of infinite-scroll feeds (YouTube Shorts, Instagram Reels, TikTok).
- Flexible App & URL Blocking: Block selected apps, categories, or specific domains with custom schedules and launch limits.
- Keyword Filtering: Real-time accessibility text scanning that clears distracting or inappropriate search terms.
- Zero-Knowledge Privacy: 100% on-device operation. No user tracking, no third-party analytics SDKs, no cloud logging.
- Offline Cryptographic Licensing: Optional Supporter Pass activated completely offline via NIST P-256 ECDSA public key verification.
- Zero-Knowledge Architecture: 100% on-device SharedPreferences persistence (zero Room/DataStore) and isolated EncryptedSharedPreferences.
- Requirements
- Building the App
- Product Flavors
- Architecture & Storage Overview
- Android Studio Setup
- If the Build Shows Old UI
- Release Builds
- Contributing & Bug Reports
- Project Documentation
| Tool | Version |
|---|---|
| Android Studio | Meerkat or newer |
| Gradle | 9.5+ (managed by wrapper) |
| Android SDK compile target | API 36 |
| Min Android version | API 26 (Android 8.0) |
| JDK | 17 |
[IMPORTANT] Product Flavors: AmniShield uses three product flavors (
playstore,fdroid,universal). The plainassembleDebugGradle task is no longer valid. Always use a flavor-qualified task. Running bareassembleDebugwill silently serve a stale cached APK with old UI and themes.
# Build all three flavors at once (recommended)
.\gradlew assemblePlaystoreDebug assembleFdroidDebug assembleUniversalDebug
# Or build individually
.\gradlew assemblePlaystoreDebug # Google Play Store flavor
.\gradlew assembleFdroidDebug # F-Droid / offline license flavor
.\gradlew assembleUniversalDebug # Universal / sideload flavorAPK output paths:
| Flavor | APK Location |
|---|---|
| playstore | app/build/outputs/apk/playstore/debug/app-playstore-debug.apk |
| fdroid | app/build/outputs/apk/fdroid/debug/app-fdroid-debug.apk |
| universal | app/build/outputs/apk/universal/debug/app-universal-debug.apk |
| Flavor | Description | Google Services | Billing |
|---|---|---|---|
playstore |
Google Play Store distribution | Included: Firebase, Play Billing | Play Billing |
universal |
Sideload / alternative stores | Included: Firebase | Play Billing |
fdroid |
F-Droid / fully open source | None: Pure FOSS | Offline ECDSA license |
Each flavor has its own source set under app/src/<flavor>/java/ for swapping
billing and sign-in implementations without #ifdef-style hacks.
AmniShield uses a decoupled Dual-Host presentation architecture bridging AndroidX Activities with Jetpack Compose Material 3:
MainActivity.kt: Hosts the primary 4 bottom navigation tabs (Stats,Blocks,Focus,Advanced) and providesmountAdaptiveComposeShell()to activate the pure-Compose adaptive layout (AmniShieldAdaptiveApp.kt).FragmentActivity.kt: Acts as a secondary router dispatching 18 functional sub-screens and configuration dialogs via the type-safeFragmentDestination.ktsealed route contract. Each configuration fragment inheritsBaseFeatureFragmentand returnsComposeViewembedding Material 3 Compose screens (AppBlockerConfigScreen,ReelBlockerConfigScreen, etc.).AmniShieldAdaptiveApp.kt: Pure ComposeNavigationSuiteScaffoldshell supporting adaptive mobile, tablet, and foldable form factors, wired toAmniShieldViewModel.
- Relational SQLite Database (
AmniShieldRuleDatabase.kt): Structured relational persistence for app blocking rules and screen-time launch limits supporting V1 to V2 schema migrations and reactiveStateFlowstreams. - Reactive Preferences DataStore (
AmniShieldDataStore.kt): Jetpack Preferences DataStore layer streaming core feature toggles, onboarding consent, active theme, and PIN security state. SavedPreferencesLoader.kt: Orchestrates 30 specialized SharedPreferences XML files with thread-safe in-memory schedule caching (@Volatile+ static companion mutex locksrulesLockandstatsLock).SecureKeyStore.kt:EncryptedSharedPreferencesstrictly isolated to Supabase cloud sync authentication tokens with an automatic plain XML fallback (amnishield_sync_secrets_fallback).
Executed in AmniShieldAccessibilityService.kt:
- Priority 0:
AntiUninstallDetector(Line 300) - Intercepts settings, device admin, and store tampering; dispatches Home. - Priority 1:
FocusModeBlocker(Line 321) - Enforces focus sessions; dispatchesAmniSpaceActivity(Focus Launcher) orpressHome(). - Priority 2:
WebsiteBlockerDetector(Line 367) - Evaluates browser URL bars across 15+ browsers (linear scan over 1-20 active schedule targets;adult_domains.txtandharam_domains.txtare dead assets). - Priority 3:
AppBlocker(Line 434) - Evaluates launch limits, usage quotas, and app block schedules. - Priority 4:
KeywordBlocker&ReelBlocker(Lines 473, 507-598) - Deferred via conflated coroutine channel (Channel.CONFLATED).
- Free FOSS Core (
UserType.FREE): Base app, website, reel blockers, and keyword filters are 100% free and open-source forever. - Supporter Passes:
UserType.PREMIUM,UserType.FOUNDER(90-day early supporter pass), andUserType.COMPASSIONATE(Al-Haq community access). - Gated Features: Rule PIN / Password Security Locking (
RuleProBadge), Master PIN, App Lock, Bypass PIN Lock, and Supabase cloud policy sync. - Billing Implementation:
playstoreuses Google PlayBillingClientWrapper.kt;fdroiduses 100% offline NIST P-256 ECDSA public key verification (SHA256withECDSAinLicenseValidator.kt) with optional Stripe Direct checkout;universalprovides hybrid capabilities.
- Open the project root in Android Studio.
- Open the Build Variants panel (
View -> Tool Windows -> Build Variants). - Set the Active Build Variant for
:appto one of:playstoreDebugfdroidDebuguniversalDebug
- Hit Run as normal.
If the Build Variants panel shows just
debug(no flavor prefix), the IDE has not yet synced the new flavor configuration. Run File -> Sync Project with Gradle Files to fix it.
If you see the legacy purple gradient background, old DeenShield icons, or the old Settings bottom-nav tab instead of the new Blocks tab, the Gradle build cache is serving a stale APK. Fix it by doing a clean build:
# Step 1: Wipe all build outputs and cached intermediates
.\gradlew clean --no-daemon
# Step 2: Rebuild fresh (--no-daemon forces a new JVM, bypassing any stale cached daemon)
.\gradlew assemblePlaystoreDebug assembleFdroidDebug assembleUniversalDebug --no-daemonThe --no-daemon flag is the key - without it, Gradle may reuse an old daemon process
pinned to a previous Gradle version that has incorrect cached fingerprints.
| Flavor | Published to | Audience |
|---|---|---|
universal |
GitHub Releases | Standard Android - sideloading with Google Play Services |
fdroid |
GitHub Releases | De-Googled phones (GrapheneOS, CalyxOS, LineageOS without GMS) |
playstore |
Play Console only | Google Play Store users - never published to GitHub |
universalandfdroidare not interchangeable. Theuniversalflavor depends on Google Play Services for billing and sign-in. Users on de-Googled ROMs must use thefdroidAPK, which has zero Google dependencies and uses offline ECDSA licensing instead.
The release.yml workflow fires automatically when you push a version tag. It builds, signs, and publishes both APKs to GitHub Releases:
# Tag a release (triggers the workflow)
git tag v1.2.3
git push origin v1.2.3For Self Build:
# GitHub Releases (the two public APKs)
.\gradlew assembleUniversalRelease
.\gradlew assembleFdroidRelease
# Play Store (submitted via Play Console, not GitHub)
.\gradlew assemblePlaystoreReleaseNever commit
keystore.propertiesor.jksfiles to version control. These are already listed in.gitignore.
Contributions, bug reports, and feedback are warmly welcomed!
- Report a Bug: If you notice unexpected behavior, crashes, or unblocked surfaces, please open a Bug Report.
- Request a Feature: Have an idea for a new filter, accessibility improvement, or custom rule? Submit a Feature Request.
- Google Play Beta Feedback: You can also submit private beta feedback directly through Google Play: Join Open Testing.
- Email Support: Reach our engineering team directly at
support@alhaq.uk.
| File | Description |
|---|---|
| ARCHITECTURE.md | System architecture, blocker pipeline & logging invariants |
| ROADMAP.md | Feature roadmap and recent changelog |
| TESTING_GUIDE.md | Full manual test scenarios for all features |
| PRIVACY_POLICY.md | App privacy policy |
| TERMS_OF_SERVICE.md | Terms of service |
| FDROID_PUBLISHING_GUIDE.md | Steps to publish on F-Droid |
For historical reasons (AmniShield was rebranded from DeenShield), there is a mismatch in the project identifiers:
applicationId:com.alhaq.deenshieldnamespace:com.alhaq.amnishield
Because the Google Play Store registry binds permanently to the applicationId, changing it would require publishing a completely new listing. Consequently, we maintain the legacy applicationId (com.alhaq.deenshield) to avoid disrupting existing users, while codebase packages and code structures use the modern namespace com.alhaq.amnishield. Do not change the applicationId when making code updates.
- Curbox by Nethical (GPL-3.0-or-later): Reel & short-form video surface detection patterns and floating WindowManager overlay mechanics are inspired by Curbox.
This project is licensed under the GNU General Public License v3.0. See LICENSE for the full text.