DEV Community: ReClaim

Racing AlarmManager with a coroutine: app reminder timers on Android

ReClaim — Thu, 15 Oct 2026 15:20:28 +0000

An app timer on Android sounds simple: pick a number of minutes, wait, then interrupt. In practice three clocks have to agree: the one the user sees, the one that survives your process being killed, and the one that fires on time while they're still in the app.

We're building ReClaim, a minimalist Android launcher with intentional-use reminders. When you open a reminded app, ReClaim asks how long you mean to stay. When that commitment runs out, it either shows a "time's up" screen or sends you Home. This post is the plumbing behind that timer: why it skips exact alarms, how an in-process countdown races AlarmManager, and how the ongoing notification shows a live countdown without us re-posting it every second.

Stack: Kotlin, Hilt, Room, DataStore, coroutines, minSdk 26, targetSdk 36. Snippets are trimmed from the real code; // ... marks cuts.

1. One commitment, two timers

Exact alarms (setExact, setExactAndAllowWhileIdle) are the obvious tool, but apps targeting Android 12+ need the SCHEDULE_EXACT_ALARM permission for them (unless they're exempt from battery restrictions), and the docs reserve them for user-facing features with a strong need for exact timing, like an alarm clock. ReClaim schedules an inexact wake-up that's still allowed to run in Doze:

suspend fun schedule(packageName: String, appLabel: String, minutes: Int) {
    if (minutes <= 0) return
    val triggerAt = System.currentTimeMillis() + minutes * 60_000L
    val pendingIntent = alarmPendingIntent(packageName, appLabel, minutes)
    // Inexact-but-idle-friendly: no special exact-alarm permission required. The OS is free to
    // defer this by minutes (observed on-device), so it's a reliability backstop, not the primary
    // enforcement — see BlockAccessibilityService's precise in-process countdown for that.
    alarmManager.setAndAllowWhileIdle(AlarmManager.RTC_WAKEUP, triggerAt, pendingIntent)
    // So the prompt doesn't ask again — from any trigger path — while this commitment is live.
    sessionStore.startSession(packageName, triggerAt, minutes, appLabel)
    // The visible, always-checkable answer to "is my timer still running?" — survives the
    // target app (or ReClaim itself) being backgrounded, closed from Recents, or killed.
    ReminderTimerNotification.show(context, packageName, appLabel, triggerAt)
}

Per the AlarmManager reference, setAndAllowWhileIdle always allows batching. Android won't dispatch these alarms more than about once a minute under normal operation, and in low-power idle that gap "may be significantly longer, such as 15 minutes." That's fine for a backstop that has to survive process death. It's not fine as the moment the user feels.

So the precise path lives in the accessibility service ReClaim already uses to watch which app is in front. While that service is alive, a coroutine waits out the remaining wall-clock time and calls the same expiry function the alarm uses:

private suspend fun scheduleReminderCloseJob(pkg: String, activeUntil: Long) {
    reminderCloseJobs.remove(pkg)?.cancel()
    val remaining = activeUntil - System.currentTimeMillis()
    if (remaining <= 0) return
    reminderCloseJobs[pkg] = scope.launch {
        // No safety buffer here on purpose — the countdown notification's chronometer keeps
        // ticking (into visibly-wrong negative time) for as long as this takes to fire.
        delay(remaining)
        // Re-verify against a fresh read — the session may have been extended, or already handled
        // by the alarm winning the race — before doing anything visible.
        val stillActive = reminderSessionStore.activeUntil(pkg)
        if (stillActive != null && stillActive > System.currentTimeMillis()) return@launch
        val label = reminderSessionStore.label(pkg) ?: labelOf(pkg)
        val minutes = reminderSessionStore.minutes(pkg) ?: 0
        reminderScheduler.fireExpiry(pkg, label, minutes)
    }
}

One detail that's easy to get wrong: ReClaim's App Limit timer is cancelled when the app leaves the foreground, because limit usage only builds up while you're looking at the app. The reminder job is deliberately not cancelled. The field's comment calls a reminder "a wall-clock commitment that keeps counting down in the background, by design." Ten minutes means ten minutes, even if you hop over to Maps halfway through.

2. Persist the session, not just the alarm

The "how long?" prompt mustn't ask again every time Recents brings the app back. The end time, the minutes and the label go into DataStore, keyed by package name:

/**
 * Tracks, per app, when its current "how long" commitment runs out — so the reminder prompt only
 * asks again once that time has actually elapsed, no matter how the app was reopened (ReClaim's own
 * UI, Recent Apps, a notification, another launcher, …). Kept in DataStore rather than memory so it
 * survives the accessibility service's process being killed mid-session.
 */
@Singleton
class ReminderSessionStore @Inject constructor(
    @ApplicationContext private val context: Context,
) {
    // ...
    suspend fun startSession(packageName: String, untilMillis: Long, minutes: Int, label: String) {
        store.edit {
            it[key(packageName)] = untilMillis
            it[minutesKey(packageName)] = minutes
            it[labelKey(packageName)] = label
        }
    }
}

When a reminded app comes to the front, the service either re-arms the countdown for whatever time is left, or shows the prompt:

private fun evaluateReminderIfNeeded(pkg: String) {
    if (pkg !in reminderPackages) return
    scope.launch {
        val activeUntil = reminderSessionStore.activeUntil(pkg)
        if (activeUntil != null && activeUntil > System.currentTimeMillis()) {
            scheduleReminderCloseJob(pkg, activeUntil)
            return@launch
        }
        val intent = ReminderPromptActivity.intent(this@BlockAccessibilityService, pkg)
            .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
        withContext(Dispatchers.Main) { runCatching { startActivity(intent) } }
    }
}

Re-arming on every switch means the countdown always reflects the current commitment, including one just extended with "add time." Every confirm path calls schedule() again. The broadcast PendingIntent is built with request code packageName.hashCode() and FLAG_UPDATE_CURRENT, so a new schedule for the same app replaces its old alarm instead of adding a second one.

3. Let the OS draw the countdown

Users need a way to check the timer is still running. ReClaim posts an ongoing notification and lets the system render the clock:

val notification = NotificationCompat.Builder(context, CHANNEL_ID)
    .setSmallIcon(R.drawable.ic_notification)
    .setContentTitle(label)
    .setContentText("Reminder running — closes automatically when time's up")
    .setOngoing(true)
    .setOnlyAlertOnce(true)
    .setSilent(true)
    .setPriority(NotificationCompat.PRIORITY_LOW)
    .setCategory(NotificationCompat.CATEGORY_PROGRESS)
    .setUsesChronometer(true)
    .setChronometerCountDown(true)
    .setWhen(expiresAt)
    .setShowWhen(true)
    // Belt-and-suspenders against the chronometer ever visibly counting into negative time:
    // the OS clears this on its own right at expiry even if nothing in-app gets a chance to
    // run (process killed, service off) — see ReminderScheduler.fireExpiry for the normal path.
    .setTimeoutAfter(expiresAt - System.currentTimeMillis())
    .apply { if (contentIntent != null) setContentIntent(contentIntent) }
    .build()

setUsesChronometer(true) shows the when field as an automatically updating timer, and setChronometerCountDown(true) (API 24+) makes it count down toward setWhen(expiresAt). Nothing in our process ticks. setTimeoutAfter (API 26+, which matches our minSdk) cancels the notification at the deadline even if ReClaim never gets to run again.

The notification goes on a low-importance channel created in Application.onCreate(), described as "Ongoing countdown while an App Reminder session is running, and a quiet note when it ends."

4. One expiry function, two callers

The alarm lands in a Hilt-injected receiver, which hands off immediately:

@AndroidEntryPoint
class ReminderReceiver : BroadcastReceiver() {

    @Inject lateinit var reminderScheduler: ReminderScheduler

    override fun onReceive(context: Context, intent: Intent) {
        val packageName = intent.getStringExtra(EXTRA_PACKAGE) ?: return
        val label = intent.getStringExtra(EXTRA_LABEL) ?: "your app"
        val minutes = intent.getIntExtra(EXTRA_MINUTES, 0)
        reminderScheduler.fireExpiry(packageName, label, minutes)
    }
    // ...
}

fireExpiry is where the race gets settled. Its KDoc says it's "safe to run twice in the rare case both fire close together":

fun fireExpiry(packageName: String, label: String, minutes: Int) {
    cancelAlarm(packageName)
    ReminderTimerNotification.cancel(context, packageName)
    reminderRepository.notifyExpired(packageName, label, minutes)

    appScope.launch {
        val host = hostFromSiteKey(packageName)
        val action = if (host != null) {
            websiteReminderRepository.expireAction(host)
        } else {
            reminderRepository.expireAction(packageName)
        }
        if (action == ReminderExpireAction.CLOSE) return@launch
        postExpiredNotification(packageName, label, minutes)
    }
}

The order matters:

Cancel the alarm first. If the coroutine won, the broadcast never arrives.
Cancel the countdown notification.
Emit an ExpiredReminder on a MutableSharedFlow(extraBufferCapacity = 4) so the accessibility service can react. tryEmit never suspends, so the receiver path stays short.
Post a silent "Time's up on …" notification that opens the takeover screen, but only for the default Prompt action. For Close it's skipped on purpose. The comment explains that tapping it "would otherwise reopen the very 'add time?' prompt CLOSE exists to skip, through a back door."

The hostFromSiteKey branch exists because website reminders reuse this path under a site: key (see our website-blocking post).

5. Don't yank the user out of something else

Expiry doesn't always mean "takeover right now." The service collects reminderRepository.expired and checks what's in front:

if (expired.packageName == lastForegroundPackage) {
    // Still on the reminded app right now — this is exactly the moment its
    // configured action (takeover, or straight home) is expected to happen.
    withContext(Dispatchers.Main) { runCatching { handleExpiredReminder(expired) } }
} else {
    // The user already moved on to something else — a full-screen takeover now would
    // interrupt unrelated work. Enforce it instead the moment they switch back into
    // this app (see onAccessibilityEvent), so a minimized/backgrounded reminder app
    // still can't just be silently resumed later with no consequence.
    markPendingExpired(expired)
}

A deferred expiry gets handled the next time that package comes to the front, unless a new session is already active. That check came from a real bug. Reopening through ReClaim's own UI asks "how long?" without looking at the deferred queue, so the old expiry would fire right after the new commitment. In the code's words, that "showed up as 'how long?' and 'your time is up' appearing back to back."

The second trap was System UI. The notification shade, quick settings and volume panel briefly take window focus without the user leaving their app. Counting that as a switch meant a reminder that expired while the shade was open got deferred, and the takeover only showed up at the next real app switch, "well after its own 'time's up' notification." Now window events from com.android.systemui are ignored before lastForegroundPackage is updated.

6. Prompt or close

What happens at expiry is a per-app setting, stored as a nullable string in Room and resolved to a small enum. null means the default:

enum class ReminderExpireAction(val label: String, val description: String) {
    PROMPT(
        "Prompt",
        "The reminder screen pops up instead of Home — leave, or add more time.",
    ),
    CLOSE(
        "Close",
        "Closes the app and takes you straight to the Home screen.",
    ),
}

Only the accessibility service acts on it, because it's the one place that already knows what's in front:

private fun handleExpiredReminder(expired: ExpiredReminder) {
    when (reminderExpireActions[expired.packageName] ?: ReminderExpireAction.PROMPT) {
        ReminderExpireAction.PROMPT -> showExpiredTakeover(expired)
        ReminderExpireAction.CLOSE -> closeToHome(expired.packageName)
    }
}

"Close" doesn't kill anything, since Android gives third-party apps no API to force-stop another app. closeToHome sends a media pause key (KEYCODE_MEDIA_PAUSE, not the play/pause toggle, which could start playback), briefly arms a picture-in-picture dismiss for that one package, and starts the Home intent. The takeover path does the same pause and PiP step before showing its screen.

7. Trade-offs

Late without the service. If the accessibility service isn't running, expiry depends on the inexact alarm alone and can arrive minutes late. That's the cost of not asking for exact-alarm access.
A brief negative countdown. The countdown has no safety buffer, so if it fires a little after expiresAt, the chronometer can briefly show negative time. Cancelling in fireExpiry plus setTimeoutAfter keeps that window short.
Two clocks, one decision. delay() measures elapsed time, while the session's end is wall-clock millis. The close job resolves that by re-reading DataStore and comparing against System.currentTimeMillis() before acting.

Wrapping up

Use an inexact, Doze-friendly alarm as the backstop for process death, not as the clock the user feels.
Race it with a precise in-process delay() while your long-lived service is running, and make expiry idempotent: cancel the alarm first.
Persist the commitment so Recents and notifications don't re-prompt mid-session.
Let NotificationCompat's chronometer draw the countdown.
Defer the takeover when the user is somewhere else, and don't count System UI as an app switch.

For the product side of timers versus blocks versus limits, we wrote up app limits vs. blocking vs. reminders. ReClaim isn't on Google Play yet; it's waitlist-only for now at tryreclaim.io.

Have you shipped a user-facing timer without exact alarms, or found a cleaner way to keep a countdown honest across process death? Tell us in the comments.

This article was drafted with AI assistance and reviewed by the ReClaim team.

Why I Built an Android Launcher That Makes My Phone Harder to Use

ReClaim — Tue, 13 Oct 2026 15:43:56 +0000

Most software I've worked on had the same goal: remove friction. Fewer taps, faster load, smoother onboarding. So it felt strange to start a project whose whole point is to add friction, deliberately, in exactly the right places.

That project is ReClaim, a minimalist Android launcher for people who want to use their phone on purpose. This post is about why I built it as a launcher instead of yet another blocker app, the design decisions that shaped it, and what I learned about building software that wants you to use it less.

The problem: the friction is backwards

Here's the observation that started it. On a typical phone, the most distracting apps are the easiest to reach. They sit on the home screen with bright icons and notification badges, one thumb-tap away. Meanwhile the genuinely useful stuff — your notes, your calendar, your banking app — ends up buried in a folder on page three.

Nobody designed that layout to hurt you. It just accumulates. But the result is that the path of least resistance almost always leads to a feed.

I didn't want to rely on willpower to fix that. Willpower is a finite resource and it's usually lowest exactly when you reach for your phone: tired, bored, waiting in line. What I wanted was to change which actions are easy. Keep productive apps one tap away. Make everything else require a moment of intention first.

Why a launcher, not a blocker

There are plenty of app blockers on Android. I've used several. The recurring problem I ran into is that they sit beside your home screen rather than being it. You still see the icons. You still get the pull. The blocker only steps in after you've already tapped.

A launcher is different. It's the first thing you see every time you unlock your phone. If the home screen itself is calm, a lot of the problem disappears before any blocking kicks in. And because a launcher is your home screen, the rules apply system-wide — set them once, and they're enforced without you having to remember to open another app.

So ReClaim's home screen is intentionally boring: a clock, the favorites you choose, and a plain, icon-free alphabetical app list. No colourful grid, no badges competing for attention. Finding an app means reading its name, which turns out to be a tiny but meaningful speed bump.

Designing the levels of friction

The hardest design question was: how much friction is the right amount? Too little and it's pointless. Too much and people uninstall it in a frustrated moment. I ended up with several tools, each suited to a different relationship with an app.

1. Hard blocks with a timer

Sometimes you just want an app gone. In ReClaim you pick an app and a duration — anywhere from 5 minutes up to a year — and it's unavailable until the timer runs out. There are 18 preset durations, because I found that making people type a custom number was itself a decision point where they'd talk themselves out of it.

One small detail I like: when you block an app, ReClaim suggests other apps you'll probably want to block alongside it. If you block one social app, you're likely to just drift to the next one otherwise.

2. Daily and weekly limits

Not every app deserves a full block. Maybe 20 minutes of a given app per day is fine. With limits, once your time is used up, ReClaim closes the app automatically. No "five more minutes" prompt to negotiate with. And if you genuinely decide you need more, raising the limit lifts the block immediately — the control stays with you, it just requires a conscious choice.

3. Intention reminders

This one is my favourite because it's the gentlest. Before you open an app with a reminder set, ReClaim asks: "How long do you intend to use this?" Then it nudges you when that time is up.

It's a check-in, not a lockout. In my experience, just being asked that question is often enough to change what happens next. Sometimes the honest answer is "I don't actually need to open this."

4. Scheduled blocking

Work hours, bedtime, weekends — recurring windows where specific apps simply aren't available. This removes the daily decision entirely. You decide once, on a calm Sunday afternoon, and future-you doesn't have to fight about it at 11:40 PM.

5. Three levels of hidden apps

Some apps you want to keep installed but out of sight. ReClaim has three levels of hiding friction: hidden behind nothing (just out of the list), hidden behind a puzzle, or hidden behind a real deterrent. The idea is to match the friction to how strong the habit is.

Guardrails I refused to compromise on

Building something that restricts access to a phone comes with responsibility. A few rules I set early:

Emergency apps are never blocked by default. A focus tool should never get between you and a call you actually need to make.
Your other apps work normally. ReClaim changes how you reach apps, not how they behave once open.
No ads, ever. It would be absurd to build a tool against attention-harvesting and then monetise attention.
No account required. You shouldn't need to sign up for anything to have a calmer home screen.

That last two shaped a lot of decisions. If there's nothing to gain from keeping people on-screen, you stop designing for engagement and start designing for the moment someone puts the phone down.

What I learned about "anti-engagement" design

A few lessons that I think apply beyond launchers:

Friction is a design material. We usually treat it as a bug. But a well-placed pause is one of the most respectful things software can offer. The trick is placing it where the user would want it, if they were thinking clearly.

Choices beat walls. The features people (including me) stick with are the ones that preserve agency. A reminder that asks a question respects you more than a lock that assumes you can't be trusted.

Defaults matter more than features. The plain, text-only app list does more quiet work than any individual blocking feature, simply because it's what you see every single time.

Make the escape hatch honest. If raising a limit is possible, make it clear and immediate. Hidden escape hatches feel manipulative; honest ones build trust.

Where it's at

ReClaim is free, and you can follow along or join the waitlist at tryreclaim.io. If you've built anything in the digital wellbeing space, or have strong opinions about how much friction is too much, I'd genuinely love to hear them in the comments — this is the part of the design I'm still learning the most about.

The question I keep coming back to is the one the whole launcher is built around: does this make it easier to use my phone on purpose, or easier to lose an hour to it? It turns out that's a pretty good question for most software.