{"id":50845288,"url":"https://github.com/sysadmindoc/openlumen","last_synced_at":"2026-06-14T09:01:07.185Z","repository":{"id":358272025,"uuid":"1240734356","full_name":"SysAdminDoc/OpenLumen","owner":"SysAdminDoc","description":"Open-source CF.Lumen successor — root-grade display color filter for Android with rootless fallback. Kotlin/Compose, GPL-3.0.","archived":false,"fork":false,"pushed_at":"2026-06-13T16:06:51.000Z","size":1554,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T17:26:54.380Z","etag":null,"topics":["android","kotlin"],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SysAdminDoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-16T13:58:14.000Z","updated_at":"2026-06-13T16:06:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SysAdminDoc/OpenLumen","commit_stats":null,"previous_names":["sysadmindoc/openlumen"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/SysAdminDoc/OpenLumen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SysAdminDoc%2FOpenLumen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SysAdminDoc%2FOpenLumen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SysAdminDoc%2FOpenLumen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SysAdminDoc%2FOpenLumen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SysAdminDoc","download_url":"https://codeload.github.com/SysAdminDoc/OpenLumen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SysAdminDoc%2FOpenLumen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34315075,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","kotlin"],"created_at":"2026-06-14T09:01:04.077Z","updated_at":"2026-06-14T09:01:07.162Z","avatar_url":"https://github.com/SysAdminDoc.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenLumen\n\n[![Version](https://img.shields.io/badge/version-0.6.0-cba6f7?style=flat-square)](https://github.com/SysAdminDoc/OpenLumen/releases)\n[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0--or--later-a6e3a1?style=flat-square)](LICENSE)\n[![Platform: Android](https://img.shields.io/badge/platform-Android%208.0%2B-89b4fa?style=flat-square)](#requirements)\n[![Min SDK](https://img.shields.io/badge/minSdk-26-f9e2af?style=flat-square)](app/build.gradle.kts)\n[![No INTERNET](https://img.shields.io/badge/INTERNET-not%20requested-94e2d5?style=flat-square)](#privacy)\n\n\u003e **Open-source spiritual successor to Chainfire's CF.Lumen.** Brings root-grade\n\u003e display color shifting and overlay-based fallback to modern Android, with the AOSP\n\u003e ColorDisplayManager path that CF.Lumen never had.\n\nCF.Lumen has been dormant since December 2020. Red Moon, the main open-source\noverlay-only competitor, has been unmaintained since August 2022. OpenLumen exists\nto fill that gap on Android 14 / 15 with a clean Compose UI, no telemetry, and four\nruntime-selectable display drivers.\n\n---\n\n## Why OpenLumen?\n\n- **Four display drivers, runtime-detected** — Auto uses a root driver when root is available; non-root devices use Overlay.\n- **No INTERNET permission, ever.** Fully offline, F-Droid-clean.\n- **Catppuccin Mocha + AMOLED true-black** Compose UI. Dark by default.\n- **Quick Settings tile** for one-tap toggling. CF.Lumen never shipped a tile.\n- **GPL-3.0-or-later**, aligned with Red Moon's lineage.\n- **Modern Android targets** — minSdk 26, targetSdk 35 (Android 15).\n- **Stack:** Kotlin · Jetpack Compose · Material 3 · Hilt · DataStore · kotlinx.serialization.\n\n## Display drivers\n\nOpenLumen ships four `ColorEngine` implementations and probes each at first launch:\n\n| Driver | Root? | SoC | Quality | Notes |\n|--------|------|-----|---------|-------|\n| `ColorDisplayManager` | No¹ | Any (AOSP-derived) | Framebuffer | Same path the system Night Light uses. API 28+. |\n| `SurfaceFlinger` | Yes | Any | Framebuffer | `service call SurfaceFlinger` color-transform. Works on Tensor/Exynos/MediaTek too. |\n| `KCAL` | Yes | Qualcomm | Panel driver | Requires custom kernel exposing `/sys/devices/platform/kcal_ctrl.0/kcal*`. |\n| `Overlay` | No | Any | Compositor blend | Universal fallback. Capped at ~80% opacity by Android 12+ rules. |\n\n¹ Some builds require granting `WRITE_SECURE_SETTINGS` via:\n`adb shell pm grant com.openlumen android.permission.WRITE_SECURE_SETTINGS`\n\nThe app falls back gracefully — Auto prefers the best available root path\n(`SurfaceFlinger`, then `KCAL`). Non-root devices use Overlay by default. If\nyou want a specific driver such as `ColorDisplayManager`, Settings → Driver\nlets you pin one; if that pinned driver later probes as unavailable, OpenLumen\nresets to Auto instead of leaving the filter enabled with no visible effect.\n\n## Features (v0.6.0)\n\n**Color**\n\n- Named presets: Night · Amber · Red · Salmon · Sepia · Grayscale · Deep Sleep · Protan · Deutan · Tritan\n- Custom R/G/B picker on Home with live color preview\n- Kelvin color-temperature slider (1000–10 000 K) with Tanner Helland conversion\n- Per-channel gamma sliders (γR / γG / γB, range 0.5–2.5)\n- Intensity slider (0–100% lerp toward identity) and dim slider (0–95%)\n- Contrast multiplier (0.5–2.0×)\n- AMOLED true-black clamp (opt-in; snaps very dim subpixels to fully off)\n- Blue-channel reduction indicator (physical measurement; not a sleep claim)\n\n**Scheduling**\n\n- Solar-position schedule (NOAA algorithm, hand-rolled, no external library)\n- Sunset / sunrise offset sliders (±180 minutes)\n- Fixed-time schedule with Material 3 24-hour time pickers\n- \"Until my next alarm\" mode driven by the system alarm clock\n- Manual location entry with bundled offline city picker (~95 cities, no Play Services)\n- No runtime location permission; solar scheduling uses coordinates the user enters\n- Ambient-light-sensor trigger (lux below threshold engages filter; OR with schedule)\n- Live lux readout + \"calibrate: use current reading\" button\n- Smooth fade-in / fade-out transitions (Instant / 30 s / 5 min / 15 min / 30 min)\n- Schedule timezone hint so fixed-time windows are unambiguous after travel\n\n**Command surfaces**\n\n- Quick Settings tile (subtitle shows active preset; long-press opens the app)\n- 1 × 1 toggle widget\n- 4 × 1 favorites widget (tap a chip to switch presets)\n- Foreground-service notification with Turn-off and Next-preset actions\n- Documented Tasker / Termux / ADB intent surface (`docs/automation.md`)\n\n**Persistence + reliability**\n\n- Foreground service with `specialUse` type (Android 14+ compliant)\n- AlarmManager-driven schedule transitions (`setExactAndAllowWhileIdle`, Doze-resilient)\n- Boot persistence with crash-window safety net (no auto-restart after a recent crash)\n- Profile export / import as JSON via Storage Access Framework, with diff preview\n- Named profile library — save current configuration, load it back later\n- Previous-preset restore (one-tap undo of a preset change)\n- Local-only crash log + structured diagnostics log (`filesDir/`, viewable in-app)\n- Versioned preference schema with explicit migrations\n\n**Trust + privacy**\n\n- No INTERNET permission, ever (CI rejects builds that contain one)\n- No Play Services / Firebase / Google APIs (CI rejects builds that pull them in)\n- No accessibility service, no usage-stats permission, no foreground-app detection\n- Permission rationale card for SYSTEM_ALERT_WINDOW (overlay driver)\n- In-app driver report (Copy or Share) with zero PII — captures device, build,\n  granted permissions, every engine's probe result\n\n## Privacy\n\nOpenLumen requests **zero** network permissions. No telemetry, no crash reporting,\nno remote config. Verify with:\n\n```bash\naapt dump permissions OpenLumen-release.apk | grep INTERNET\n# (no output)\n```\n\n## Requirements\n\n- Android 8.0 (API 26) or higher\n- For best results: root with Magisk-managed `su`, OR a Pixel / Android-One device\n  whose system Night Light is functional (the AOSP driver piggy-backs on it).\n\n## Build\n\n```bash\ngit clone https://github.com/SysAdminDoc/OpenLumen.git\ncd OpenLumen\n./gradlew assembleRelease\n```\n\nSigned release builds require:\n\n```bash\nexport OPENLUMEN_KEYSTORE=/path/to/release.jks\nexport OPENLUMEN_KEYSTORE_PASSWORD=...\nexport OPENLUMEN_KEY_ALIAS=openlumen\nexport OPENLUMEN_KEY_PASSWORD=...\n./gradlew assembleRelease\n```\n\n## Module layout\n\n```\nOpenLumen/\n├── app/             — Compose UI, foreground service, tile, boot receiver\n├── core-engine/     — ColorEngine abstraction + 4 driver impls + DriverProbe\n├── core-schedule/   — NOAA solar calculator, schedule modes, light sensor adapter\n└── core-prefs/      — DataStore-backed prefs, JSON serialization\n```\n\n## Documentation\n\n### For users\n\n- [Troubleshooting](docs/troubleshooting.md) — common driver and overlay problems, recovery from stuck states\n- [Compatibility table](docs/compatibility-table.md) — which engines work on which hardware\n- [Root mode safety and recovery](docs/root-safety.md) — what can go wrong with root drivers, and how to recover\n- [Automation](docs/automation.md) — Tasker / Termux / ADB intent reference\n- [Health and evidence notes](docs/health-evidence.md) — what we will and will not claim\n\n### For contributors\n\n- [Architecture overview](docs/ARCHITECTURE.md) — modules, runtime flow, engine contract\n- [Contributing](CONTRIBUTING.md) — style, tests, driver-work expectations\n- [Translations and localization](docs/translations.md) — how to contribute a translation\n- [Device validation matrix](docs/device-matrix.md) — per-engine smoke flow, current device coverage\n- [Profile import lineage formats](docs/profile-import-formats.md) — notes for future Red Moon / CF.Lumen importers\n\n### For distributors and packagers\n\n- [Release checklist](docs/release-checklist.md) — pre-flight, verification, no-INTERNET assertion\n- [Reproducible build notes](docs/reproducible-build.md) — environment pinning, verification procedure\n- [Play FGS evidence pack](docs/play-fgs-evidence.md) — Play `specialUse` justification\n\n### Security and supply chain\n\n- [Threat model](docs/threat-model.md) — MASVS-lite categories with mitigations\n- [SBOM and advisory scan](docs/sbom-and-advisories.md) — CI workflow and triage policy\n- [Dependency verification](docs/dependency-verification.md) — Gradle metadata procedure (opt-in)\n- [Wake / alarm / battery audit](docs/wake-and-vitals.md) — what wakes the device and why\n\n### Roadmap and design\n\n- [Roadmap](ROADMAP.md) — source-backed release plan with the candidate inventory\n- [Overlay safety and per-app design notes](docs/overlay-and-per-app-design.md) — why per-app behavior is deferred until the trust posture is sorted\n- [Deferred roadmap candidates](docs/deferred-candidates.md) — design sketches for Wear OS / Android TV / etc.\n- [Android 17 readiness](docs/android-17-readiness.md) — forward-looking Android-version migration notes (renamed from `api-36-readiness.md` in rev 4)\n- [Research watchlist](docs/research-watchlist.md) — sources we monitor before release planning\n\n## Emergency off\n\nIf a release goes wrong and the overlay or root driver leaves your screen\nin a bad state, the canonical escape hatch is:\n\n```bash\nadb shell am broadcast -a com.openlumen.action.TURN_OFF \\\n    -n com.openlumen/.service.AutomationReceiver\n```\n\nSee [docs/root-safety.md](docs/root-safety.md) for more recovery paths.\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md) for the source-backed release plan and the\ncandidate inventory. The `Now: v0.5.0` section is largely shipped; the\ndeferred items have design sketches in\n[docs/deferred-candidates.md](docs/deferred-candidates.md) and\n[docs/overlay-and-per-app-design.md](docs/overlay-and-per-app-design.md).\n\nPost-v0.5.0 work clusters around:\n\n- A Shizuku-backed privileged path for per-app behavior (C06)\n- Broader screenshot screen coverage beyond the initial Compose Preview /\n  Roborazzi theme-token fixtures (C83)\n- Wear OS companion as a separate F-Droid package (C21)\n- Real-device validation rows in `docs/device-matrix.md` (C01)\n\n## License\n\nGPL-3.0-or-later. See [LICENSE](LICENSE).\n\n## Acknowledgements\n\n- **Chainfire (Jorrit Jongma)** for the original CF.Lumen and for documenting the\n  driver-backend approach so thoroughly that this project could be built without\n  the original source.\n- **LibreShift/red-moon** for proving open-source overlay shifting works on Android.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsysadmindoc%2Fopenlumen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsysadmindoc%2Fopenlumen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsysadmindoc%2Fopenlumen/lists"}