Wake with the sun, the moon, and your own clock.
AstroAlarm is a FOSS Android astronomical alarm clock. It calculates sunrise, sunset, twilight, golden hour, moonrise, moon phases, solstices, and equinoxes on the device with Apache-2.0 commons-suncalc (sun and moon) and NOAA apparent longitude for seasons — no cloud, no Play Services, no trackers.
Set alarms for a solar or lunar event, offset them before or after, or pick a custom time on tactile hour and minute wheels. When the alarm rings it can speak the event, vibrate, and require a math puzzle before you can stop it.
In-app 2D and 3D clocks show the solar disk, Earth globe, and transit rings. Home widgets rotate through day and night. Location comes from an offline city list or the system location provider. MIT licensed. GitHub Releases only.
App icon and launch splash
- On-device suncalc sun/moon ephemeris — no network required for calculations
- Eighteen solar events and eleven lunar events, plus custom clock alarms
- 2D 24-hour solar disk and 3D Earth-globe transit clocks (in-app and widgets)
- Lockscreen snooze and stop with an optional math unlock challenge
- Material You wheels for time and event offsets, with Spanish and French translations
- 100% FOSS: no Google Play Services, Firebase, or proprietary telemetry
- Install the APK from GitHub Releases (not listed on Play Store).
- Set a city from the offline list or tap Locate so sun and moon events can fire.
- Add a solar, lunar, or custom clock alarm. Choose tone, TTS, vibrate, math unlock, and snooze.
- Optional: pin the 2D clock, 3D globe, or upcoming-alarms widget to the home screen.
Start with this README, then CONTRIBUTING.md and docs/BEST_PRACTICES.md. The first-month playbook is docs/FIRST_30_DAYS.md.
Read docs/START_HERE.md and AGENTS.md. In Cursor type /tour or /bootstrap. Any other IDE: ask the agent to read docs/help/TOUR.md. /coach is the next recommended action.
flowchart TD
Readme[README] --> Humans[CONTRIBUTING]
Readme --> Agents[START_HERE]
Agents --> Tour["/tour or TOUR.md"]
Tour --> Coach["/coach"]
Users: install the APK from GitHub Releases. Developers: JDK 17 and Android SDK (compile/target 37, min 26). Clone the repo, open examples/android/, and run ./gradlew assembleDebug (or gradlew.bat on Windows). No Play Services.
Open AstroAlarm, set a location, then add alarms under Solar, Lunar, or Custom Clock. Exact alarms use AlarmManager.setAlarmClock and survive reboot. Contributors work from BUILD_PLAN.md and docs/START_HERE.md.
Copy .env.example to .env for local secrets (never commit .env). Stack-specific config lives in the active examples/ or app root after prune.
See CONTRIBUTING.md. Prefer small PRs; follow Conventional Commits and the BUILD_PLAN labels (AGENT / HUMAN / ADB / AUTO). Status markers: 🔲 open · ✅ done · ❌ blocked.
See SECURITY.md. Enable Dependabot alerts and follow docs/SECURITY_TRIAGE.md for weekly CVE triage.
MIT License — see the license file for terms.
Scaffolded with agent-project-bootstrap. Brand assets: branding/BRANDING.md. Design system: docs/DESIGN_GUIDE.md.