ZeroOS Launcher

ZeroOS is a minimalist Android home screen: plain text in black and white, with no icons, badges or feeds. It shows the time, the date and the few apps you choose, and has optional screen-time limits, a Focus mode, a short-video blocker and a screen-time lock that keeps only your essential apps after a daily cap. It is made by one person for personal use and is not on any app store.

Before you install — read this

• Read this README, the LICENSE and the third-party notices first. Installing ZeroOS means you have read and understood them and agree to them. ZeroOS asks you to confirm this when it first starts, and again if a later version changes these documents.
• Use at your own risk. ZeroOS replaces your home screen and may cause problems (the phone hard to use, missed calls, notifications or alarms, lost settings, battery drain, conflicts with your phone's software), including problems not listed here or not known when it was released. You install it on your own judgement; the author and owner of this repository is not responsible for any damage or loss.
• Personal use only. Don't upload or share the APKs anywhere. To tell someone about ZeroOS, point them to this repository.

Install

1. Use a phone with Android 8.0 or newer.
2. On the phone, download zeroos-<version>-release.apk from this repository's GitHub Releases page and open it. Allow your browser or file manager to install apps if Android asks. Play Protect may warn about an app from outside the store.
3. Press Home and choose ZeroOS, or set it in Settings → Apps → Default apps → Home app.

Updating: export your settings first (ZeroOS Settings → Backup → Export settings), then install the new APK over the old one.

Known issues

• The short-video blocker (YouTube Shorts, Instagram Reels) doesn't always detect or block them correctly. It's being worked on; until then, don't rely on it.

Go back to your old launcher

Choose your old launcher in Settings → Apps → Default apps → Home app. Keep it installed: it's your fallback if anything goes wrong. If ZeroOS keeps crashing, it starts in a simple safe mode with a button for this.

What ZeroOS can access

• No internet. ZeroOS has no internet permission, no ads, no analytics and no accounts; everything stays on your phone.
• Optional, off until you turn on the feature that needs it: Usage access (screen time, limits and the screen-time lock), Accessibility (limits, breaks and the screen-time lock outside ZeroOS, the short-video blocker, double-tap to lock), and Do Not Disturb access (Focus). Each one is explained before Android asks.
• Also used: setting the wallpaper, opening alarms, asking to keep running in the background, and opening Android's uninstall dialog for an app you choose.

For developers

Document	What it covers
REQUIREMENTS.md	What to build (feature and requirement IDs, defaults in Appendix A)
IMPLEMENTATION_PLAN.md	Build order, testing policy, Definition of Done
AGENTS.md	Rules for anyone (human or AI) changing this repo
TRACEABILITY.md	Which tests cover each requirement
docs/DECISIONS.md	Decisions already made
docs/wireframes.md	Approved screen layouts
CHANGELOG.md	Changes per installed version

Setup (command line, no Android Studio)

• JDK 21 in ~/.local/jdk-21 (builds Java 17 bytecode; Java 21 is needed by Robolectric for API 37)
• Android SDK in ~/Android/Sdk (cmdline-tools, platform-tools, platforms;android-37.0, build-tools;37.0.0)
• ~/.bashrc sets JAVA_HOME, ANDROID_HOME and PATH

Gradle memory is capped in gradle.properties for an 8 GB machine.

Everyday commands

Command	What it does
./gradlew check	Everything that must pass before a commit: build, Android Lint, detekt (incl. ZeroOS rules), ktlint, all JVM tests, screenshot comparison, coverage ≥ 80%
./gradlew ktlintFormat	Auto-fix formatting
./gradlew recordRoborazziDebug	Re-record reference screenshots after an approved UI change
./gradlew koverHtmlReportAggregate	Coverage report in build/reports/kover/htmlAggregate/
./gradlew assembleDebug	Debug APK in app/build/outputs/apk/debug/
python3 scripts/build-site.py	Website into build/site/ (site/README.md)

Project layout

app/              entry point, Hilt setup, diagnostics wiring
core/model        data models
core/ui           theme tokens and shared composables
core/resources    all user-facing text (strings.xml, plurals.xml)
core/logging      F17 diagnostics: Logger, log files, crash reports, exit reasons
core/data         repositories and storage
core/testing      test helpers (e.g. MutableClock)
feature/home      home screen
feature/applist   app list
build-logic/      Gradle convention plugins (shared module settings)
scripts/          helper scripts (add-wallpapers.py, build-site.py)
site/             the GitHub Pages website (see site/README.md)
detekt-rules/     custom detekt rules (hardcoded text/values, direct logging)
config/           detekt config, permission allowlists, Robolectric settings

Wallpapers (F6.8, D-038)

The built-in wallpaper gallery (Settings → Appearance → Phone wallpaper) always has Pure black and Pure white. The other wallpapers are images that are not in git: anyone building ZeroOS makes them with an image-generator AI.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗