clockula/README.md

<div align="center">

<img src="fastlane/metadata/android/en-US/images/icon.png" width="112" alt="Clockula icon">

<h1>Clockula</h1>

<p><strong>A Material 3 Expressive clock app for Android.</strong><br>
Alarms, timers, stopwatch and world clock. No account and no network access.</p>

<p>
<a href="https://codeberg.org/jlmakiola/clockula/actions"><img src="https://codeberg.org/jlmakiola/clockula/actions/workflows/ci.yaml/badge.svg?branch=main" alt="CI"></a>
<img src="https://img.shields.io/badge/Android-10%2B-3DDC84?logo=android&logoColor=white" alt="Android 10+">
<img src="https://img.shields.io/badge/Kotlin-Compose-7F52FF?logo=kotlin&logoColor=white" alt="Kotlin + Compose">
<img src="https://img.shields.io/badge/Material%203-Expressive-4285F4" alt="Material 3 Expressive">
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="MIT License"></a>
</p>

<p>
<a href="https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://codeberg.org/jlmakiola/clockula"><img src="https://github.com/ImranR98/Obtainium/blob/main/assets/graphics/badge_obtainium.png?raw=true" alt="Get it on Obtainium" height="56"></a>
&nbsp;
<a href="https://ko-fi.com/jeanlucmakiola"><img src="https://storage.ko-fi.com/cdn/brandasset/v2/support_me_on_kofi_badge_beige.png" alt="Support me on Ko-fi" height="56"></a>
</p>

</div>

Clockula is the clock sibling to [Calendula](https://codeberg.org/jlmakiola/calendula)
(calendar) and [Agendula](https://codeberg.org/jlmakiola/agendula) (tasks). The
name follows theirs: *clock* with Calendula's `-ula` ending. A Calendula flower
head is botanically a cluster of many small *florets*, so the three apps are
florets of one bloom. They share one library,
[floret-kit](https://codeberg.org/jlmakiola/floret-kit).

1.0.0 is in its last betas before the stable release.

## Features

### Alarms

- Repeat schedules, snooze, your own ringtones and per-alarm settings
- Scheduled as real alarm clocks: exempt from Doze, and shown on the lock
  screen and in the status bar
- Re-resolved against your current time zone whenever it changes, so DST and
  travel don't shift them
- A self-check screen that reads your device's actual settings. If one of them
  would stop an alarm ringing, Clockula names it and opens that settings page,
  instead of failing quietly at 7am.

### Timers, stopwatch and world clock

- Several timers at once, controllable from the notification shade
- A stopwatch with laps
- World clocks from the IANA time-zone database built into Android, so the
  city list doesn't go stale
- A running timer or stopwatch stays reachable from every tab

### Widgets

- Three home-screen widgets: next alarm, timer and clock
- Each widget picks its own theme, or takes its colours from your wallpaper

### Works with other apps

- Clockula implements Android's standard `AlarmClock` intents in full. Your
  voice assistant and automation apps can set alarms and timers in it the same
  way they would in the stock clock.
- Alarms, timers, world clocks and settings export to a JSON file whose format
  is documented in [`docs/BACKUP.md`](docs/BACKUP.md), and import back from it.

### Design and privacy

- Material 3 Expressive throughout, with dynamic colour on Android 12+, light
  and dark themes, and expressive motion and shapes
- A per-app language setting. Clockula ships in English for now;
  [help translate](#translations).
- No telemetry, no analytics and no internet permission

## Where your data lives

Calendula works on top of Android's `CalendarContract`, and Agendula can work on
top of the dmfs `TaskContract`. Both put an interface on a standard someone else
maintains. Clocks have no such provider, so Clockula keeps alarms, timers and
laps in its own database, the first app in the family to do so. The first
section of [`docs/PLAN.md`](docs/PLAN.md) explains how it makes up for the
missing standard: the `AlarmClock` intents, IANA time zones and the documented
backup format listed above.

## Install

| Channel | Available | Notes |
| --- | --- | --- |
| [Codeberg release / Obtainium](#codeberg-release--obtainium) | Now, as betas | Plain APK download, or automatic with Obtainium |
| [Self-hosted F-Droid repo](#self-hosted-f-droid-repo) | From 1.0.0 | Add the repo once |
| [Build from source](#build-from-source) | Now | Full control |

### Codeberg release / Obtainium

Every release is on
[Codeberg](https://codeberg.org/jlmakiola/clockula/releases) with the signed
APK and a `.sha256` checksum. Betas are published as pre-releases. Download the
APK and install it directly.

For automatic updates, use [Obtainium](https://github.com/ImranR98/Obtainium).
On your phone,
[add Clockula in one tap](https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://codeberg.org/jlmakiola/clockula),
or add it by hand: *Add App*, paste `https://codeberg.org/jlmakiola/clockula`,
then *Add*. While Clockula is in beta, switch on *Include prereleases* for it,
or Obtainium won't find anything. A beta updates in place to later betas and to
the stable release.

### Self-hosted F-Droid repo

From the stable 1.0.0 on, every release is also published to the self-hosted
F-Droid repository that serves Calendula and Agendula. If you already have it,
Clockula will show up there. Otherwise add it once:

1. In your F-Droid client, open *Settings → Repositories → Add* (or open the
   link below on your phone):

   ```
   https://apps.dev.jeanlucmakiola.de/dev/fdroid/repo?fingerprint=C2C0640402BF458FC0ED957AF0B37AA4C14022E72F89CE90B5965B458CF73425
   ```

   <sub>Repo: `https://apps.dev.jeanlucmakiola.de/dev/fdroid/repo` ·
   fingerprint (SHA-256):
   `C2C0 6404 02BF 458F C0ED 957A F0B3 7AA4 C140 22E7 2F89 CE90 B596 5B45 8CF7 3425`</sub>

2. Refresh, search for Clockula and install it.

### Build from source

```sh
git clone --recurse-submodules https://codeberg.org/jlmakiola/clockula.git
cd clockula
./gradlew assembleDebug
```

floret-kit is a submodule built from source as a Gradle composite build, so
`--recurse-submodules` is required. The included build has to find the Android
SDK on its own: either export `ANDROID_HOME`, or put a `sdk.dir=…` line in a
(gitignored) `floret-kit/local.properties`. [CONTRIBUTING.md](CONTRIBUTING.md)
covers tests and lint.

<sub>The F-Droid repo and the Codeberg releases share the same signing key, so
you can switch between them without reinstalling.</sub>

## Documentation

- [Contributing](CONTRIBUTING.md): the workflow, the build and the
  architectural rule changes are reviewed against
- [Plan](docs/PLAN.md): the spec and the reasoning behind it
- [Roadmap](docs/ROADMAP.md): what has shipped and what's next
- [Architecture](docs/ARCHITECTURE.md): how the code is put together
- [Backup format](docs/BACKUP.md): the JSON export schema
- [Releasing](docs/RELEASING.md): the release runbook
- [Privacy policy](docs/PRIVACY.md): the source of the page at
  [jeanlucmakiola.de/clockula/privacy](https://jeanlucmakiola.de/clockula/privacy)

## Contributing

Bug reports, ideas and patches are welcome on
[Codeberg](https://codeberg.org/jlmakiola/clockula/issues). Translations go
through [Weblate](#translations), not pull requests. Read
[CONTRIBUTING.md](CONTRIBUTING.md) before writing code.

## Translations

Clockula is written in English. Translations are managed on a self-hosted
Weblate, and partial ones are fine: untranslated strings fall back to English.

[Help translate Clockula](https://weblate.dev.jeanlucmakiola.de/engage/clockula/)

You don't need to code. Register on the Weblate server, pick a language (or
request one) and translate in your browser.

## Privacy

Clockula has no analytics, tracking, ads, crash-reporting SDK or third-party
services. It doesn't have the internet permission, so it can't send anything
anywhere. Your alarms, timers and world clocks stay in the app's private
storage on your device.

[Privacy policy](https://jeanlucmakiola.de/clockula/privacy), written in
[`docs/PRIVACY.md`](docs/PRIVACY.md), which is what that page renders.

## Licence

[MIT](LICENSE), Jean-Luc Makiola, 2026