DEV Community: Tal Aizikov

Gemini picks the stretch IDs. TypeScript fills the minutes.

Tal Aizikov — Sat, 03 Oct 2026 15:17:23 +0000

Large language models are great at choosing what belongs in a workout. They are unreliable at how long that workout should last.

When we shipped AI sessions for MotionLab — personalized stretching routines built around how your body feels today — we deliberately split those two jobs. Gemini picks stretch IDs from a fixed catalogue. Our Next.js route validates those IDs and fills or trims the list until the session lands near the duration the user asked for. The model never invents an exercise, and it never owns the clock.

This post walks through the real pipeline in our MotionLab-Web repo: the catalogue we send the model, the JSON contract, the local duration loop, and how that fits next to the deterministic generator we already used for non-AI routines. Snippets are trimmed from production TypeScript.

Stack, for context: Next.js 16.2, React 19, Supabase, Firebase, Stripe, and Zustand. The AI route calls Gemini 2.5 Flash.

Why not ask the model for a full routine?

An early temptation with any fitness AI is: send the user prompt, get back names, durations, cues, and ordering. That fails in three boring ways.

Hallucinated exercises. A model will happily invent a stretch that is not in your library, misspell an ID, or mix two moves into one name.
Duration drift. "About 15 minutes" in natural language does not map cleanly to a sum of per-exercise seconds, especially when some moves are side-specific and count twice.
Content you already wrote. We already store instructions, breathing cues, equipment, and target areas per exercise. Regenerating that text per request would be slower, less consistent, and harder to review.

So the model is a selector, not an author. It returns a short JSON object: a session name, a session type, and an array of IDs that must already exist in ALL_EXERCISES.

The catalogue the model actually sees

Every exercise in the library is compacted into one line before it goes into the system prompt: id|targetAreas|stretchType. No long descriptions. No video URLs. Just enough for the model to match "tight hips after desk work" to the right IDs.

const CATALOGUE = ALL_EXERCISES
  .map((e) => `${e.id}|${e.targetAreas.join(",")}|${e.stretchType}`)
  .join("\n");

const SYSTEM = `You are a mobility coach. Given user input and the exercise list, select 4-8 exercises.
Reply ONLY with valid JSON (no markdown, no code fences):
{"name":"<short session name>","type":"DAILY_MAINTENANCE|PRE_WORKOUT|POST_WORKOUT","ids":["id1","id2",...]}
Rules: no duplicate ids, ids must be from the list, prioritize areas user mentions, avoid redundant overlaps.

Exercises (id|targetAreas|stretchType):
${CATALOGUE}`;

That keeps the prompt dense. The catalogue currently has on the order of seventy-five stretches and growing; sending full copy for each would burn tokens for little gain. The client only needs to send a free-text prompt and an optional durationMinutes (we default to 15).

Calling Gemini with thinking turned off

The route is a standard App Router POST handler. We require a non-empty prompt and a configured GEMINI_API_KEY, then hit Gemini 2.5 Flash with a low temperature and a hard cap on output tokens. For this classification-style job we also set thinkingBudget: 0 so the model does not spend tokens on an internal chain-of-thought we will throw away.

const geminiRes = await fetch(
  `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${key}`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      contents: [{ role: "user", parts: [{ text: `${SYSTEM}\n\nUser: ${prompt}` }] }],
      generationConfig: {
        temperature: 0.3,
        maxOutputTokens: 512,
        thinkingConfig: {
          thinkingBudget: 0, // disable thinking — not needed for simple classification
        },
      },
    }),
  }
);

After the response comes back we strip accidental markdown fences, JSON.parse the text, and map IDs through a real lookup table. Anything not in ALL_EXERCISES is dropped. If nothing valid remains, we return 422 instead of improvising.

const exerciseMap = Object.fromEntries(ALL_EXERCISES.map((e) => [e.id, e]));
let exercises = (parsed.ids ?? [])
  .filter((id) => exerciseMap[id])
  .map((id) => exerciseMap[id]);

if (!exercises.length) {
  return NextResponse.json({ error: "No valid exercises returned" }, { status: 422 });
}

That single filter is the safety rail. The model can only point at rows we already ship.

Filling and trimming to the user's clock

Gemini is asked for 4–8 IDs. That set is rarely the exact length of a 7-, 15-, or 25-minute session. Side-specific stretches also double their durationSeconds because each side gets its own hold. So duration is computed locally:

const targetSeconds = durationMinutes * 60;

const calcDur = (e: (typeof ALL_EXERCISES)[0]) =>
  e.isSideSpecific ? e.durationSeconds * 2 : e.durationSeconds;

let filledSeconds = exercises.reduce((s, e) => s + calcDur(e), 0);

if (filledSeconds < targetSeconds - 60) {
  const aiIds = new Set(exercises.map((e) => e.id));
  const tightAreas = new Set(exercises.flatMap((e) => e.targetAreas));
  const supplementPool = shuffle(
    ALL_EXERCISES.filter(
      (e) => !aiIds.has(e.id) && e.targetAreas.some((a) => tightAreas.has(a))
    )
  );
  for (const ex of supplementPool) {
    if (filledSeconds >= targetSeconds - 60) break;
    exercises.push(ex);
    filledSeconds += calcDur(ex);
  }
}

If the AI list is short, we supplement from exercises that share the same target areas the model already chose. That keeps the session thematically coherent without a second model call. Then we trim so the accumulated length does not overrun the target by more than a minute:

const finalExercises: typeof exercises = [];
let accSeconds = 0;
for (const ex of exercises) {
  const dur = calcDur(ex);
  if (accSeconds + dur <= targetSeconds + 60) {
    finalExercises.push(ex);
    accSeconds += dur;
  }
}

The ±60 second buffer matches how people experience a timed session: one stretch longer or shorter than the label is fine; three minutes over is not. Session type is validated against a small allowlist (DAILY_MAINTENANCE, PRE_WORKOUT, POST_WORKOUT) with a safe default if the model returns something else.

The response is a normal Routine object: ID, name, duration, type, full exercise records, and a short description that quotes the user's prompt. The client already knows how to render guided timers from that shape.

The deterministic twin: non-AI generation

AI sessions are not the only path. Most daily routines still go through generateRoutine in src/lib/routine/generator.ts — no LLM involved. That function takes a fixed duration of 7, 15, or 25 minutes, a routine type, optional sport keys, optional tight areas, and optional exclusions. It mirrors the weighting logic we use on Android.

Sport keys expand into priority target areas (running → hamstrings, calves, ankles, hip flexors; swimming → shoulders, upper back, neck, chest; and so on). Tight areas are merged first, then sport areas. The pool is filtered to matching exercises when possible. Sport-related exercises are double-weighted in a candidate list, the list is shuffled, and we walk it until the second budget is filled — again with no repeats and the same side-specific duration math.

export function generateRoutine(options: {
  durationMinutes: 7 | 15 | 25;
  type: RoutineType;
  sport?: string | null;
  tightAreas?: TargetArea[];
  excludeIds?: string[];
  focusId?: string;
}): Routine {
  // ... build focusAreas from tightAreas + sport maps ...
  // weight sport-specific exercises 2x, shuffle, fill without repeats
}

For 15- and 25-minute sessions we sometimes extend a non-sided stretch to 120 seconds so longer blocks do not need twice as many distinct moves. Daily focus IDs (desk job, wake-up, lower body, and so on) can further restrict the pool when the catalogue has enough tagged exercises.

The important design point: AI and non-AI paths share one exercise catalogue and one duration model. Gemini only replaces the "which IDs first" step. Everything else — validation, timing, UI — stays identical. That made shipping AI sessions a route and a prompt, not a second product surface.

Practical lessons

Keep the model inside a closed set. If your product has a curated library, send IDs (or compact rows) and reject anything else. Do not ask the model to invent catalogue entries.

Own duration in application code. Summing typed fields you control is cheaper and more predictable than asking an LLM to hit a minute target.

Reuse the domain object. Returning the same Routine shape as the deterministic generator meant the player, history, and analytics did not need an AI-specific branch.

Turn off features you do not need. For ID selection, low temperature and thinkingBudget: 0 cut latency and cost without hurting quality.

Supplement thematically, do not random-pad. When we need more minutes, we pull from the same target areas the model already emphasized. Padding with unrelated stretches would feel like a broken personalization promise.

Where this sits in the product

Users can still pick a classic session type and duration and get a weighted routine with no model call. When they want to describe a situation in plain language — post–leg day, pre-run warm-up, shoulders locked up from swimming — AI sessions take that sentence, pick IDs, and hand the same timer experience. We wrote more about the product framing on the MotionLab blog; the implementation above is what sits behind the generate button.

If you are wiring Gemini (or any LLM) into a domain with a real inventory — recipes, workouts, lesson plans, spare parts — the same split applies: let the model choose from your SKUs, and let your code enforce quantities, prices, and clocks.

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

Building a minimal Android launcher in Kotlin: lessons from ReClaim

Tal Aizikov — Thu, 01 Oct 2026 14:40:59 +0000

A launcher sounds like a big piece of software. It's the first thing you see when you unlock your phone and the thing you return to every time you press Home. But on Android, a launcher is "just" an app with one particular intent filter, plus a lot of small decisions about what to show and when.

We're building ReClaim, a minimalist Android launcher meant to make productive apps instant and distracting apps intentional. This post walks through the platform pieces it uses: how an app becomes the Home screen, how it lists and launches other apps, how it reads usage data, and how it enforces app blocks outside its own UI. Along the way we cover a few Android quirks we ran into.

For context, the app is written in Kotlin with Jetpack Compose and Material 3. It uses an MVVM structure with Hilt for dependency injection, Room for blocks and schedules, and DataStore for preferences. It targets minSdk 26 and targetSdk 36. The snippets below are trimmed versions of the real code.

1. Becoming a Home app

Android picks a Home screen by resolving an intent with ACTION_MAIN and CATEGORY_HOME. Any activity that declares that category is a candidate:

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTask"
    android:clearTaskOnLaunch="true"
    android:stateNotNeeded="true"
    android:excludeFromRecents="true"
    android:windowSoftInputMode="adjustNothing">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.HOME" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

The attributes matter as much as the filter:

singleTask means there is only ever one instance of the Home activity. Pressing Home while you're already on it doesn't create a new one.
clearTaskOnLaunch and stateNotNeeded tell the system the Home task can be reset and doesn't need saved state restored. That suits a screen users expect to look the same every time.
excludeFromRecents keeps the launcher out of the Recents list.
adjustNothing stops the keyboard from resizing the layout when search opens.

Because the activity is singleTask, pressing Home while ReClaim is already in front delivers the intent to onNewIntent() instead of recreating the activity. That's the hook for "go back to the main page and close whatever overlay is open":

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
    rootViewModel.onHomePressed() // emits on a SharedFlow the Compose UI collects
}

See Tasks and the back stack for how these launch modes behave.

2. Asking to be the default (and checking you really are)

Declaring the filter only makes you eligible. The user still has to choose you. On API 29+ the cleanest way to ask is RoleManager with ROLE_HOME, which shows a native system dialog. Below that, or when no dialog would appear, you fall back to the system Home-app picker via Settings.ACTION_HOME_SETTINGS:

fun requestRoleIntent(context: Context): Intent? {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q) return null
    val rm = context.getSystemService(RoleManager::class.java) ?: return null
    if (!rm.isRoleAvailable(RoleManager.ROLE_HOME)) return null
    if (rm.isRoleHeld(RoleManager.ROLE_HOME)) return null // system would finish instantly, no dialog
    return rm.createRequestRoleIntent(RoleManager.ROLE_HOME)
}

fun homeSettingsIntent(): Intent =
    Intent(Settings.ACTION_HOME_SETTINGS).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)

Here's the quirk. Android records the default launcher in two places: the ROLE_HOME holder and the PackageManager's preferred-activity entry for the Home intent. They can disagree. We hit a state where the preferred-activity entry had been dropped while the role stayed put. Home then resolved to the system chooser, and the user saw "Select a Home app" after a reboot or a low-memory kill, even though isRoleHeld() still returned true.

So to answer "does pressing Home actually open us?", we resolve the real Home intent instead of trusting the role:

fun isDefaultLauncher(context: Context): Boolean {
    val intent = Intent(Intent.ACTION_MAIN).addCategory(Intent.CATEGORY_HOME)
    val resolved = context.packageManager
        .resolveActivity(intent, PackageManager.MATCH_DEFAULT_ONLY)
    return resolved?.activityInfo?.packageName == context.packageName
}

fun isHomeRoleStale(context: Context) =
    holdsHomeRole(context) && !isDefaultLauncher(context)

When the state is stale, the role request finishes without showing anything, because the role is already held. What did repair it was re-selecting the launcher in the system Home-app picker, so the setup screen explains that step instead of showing a dead "Enable" button.

3. Listing and launching apps with LauncherApps

You can query PackageManager for CATEGORY_LAUNCHER activities. But LauncherApps is the API built for launchers. It returns launchable activities for a user profile and gives you callbacks when packages are added, removed or changed. Wrapping that in a callbackFlow gives the rest of the app a reactive list:

private val launcherApps = context.getSystemService(LauncherApps::class.java)
private val myUser = Process.myUserHandle()

fun currentApps(): List<RawApp> =
    launcherApps.getActivityList(null, myUser).map {
        RawApp(it.componentName.packageName, it.componentName.className, it.label.toString())
    }

fun observeApps(): Flow<List<RawApp>> = callbackFlow {
    val callback = object : LauncherApps.Callback() {
        override fun onPackageAdded(pkg: String?, user: UserHandle?) { trySend(currentApps()) }
        override fun onPackageRemoved(pkg: String?, user: UserHandle?) { trySend(currentApps()) }
        override fun onPackageChanged(pkg: String?, user: UserHandle?) { trySend(currentApps()) }
        override fun onPackagesAvailable(p: Array<out String>?, u: UserHandle?, r: Boolean) { trySend(currentApps()) }
        override fun onPackagesUnavailable(p: Array<out String>?, u: UserHandle?, r: Boolean) { trySend(currentApps()) }
    }
    launcherApps.registerCallback(callback, Handler(Looper.getMainLooper()))
    trySend(currentApps())
    awaitClose { launcherApps.unregisterCallback(callback) }
}.flowOn(Dispatchers.Default)

Launching goes through launcherApps.startMainActivity(component, user, null, null). If that fails, it falls back to PackageManager.getLaunchIntentForPackage().

Two notes:

Package visibility. Since Android 11, apps only see a filtered set of other packages (package visibility). A launcher has to list everything, so ReClaim declares QUERY_ALL_PACKAGES. That's a core-functionality use under Google Play's permission policy, but it's a policy-reviewed permission, so only declare it if your app really is a launcher.
Uninstalling. The context menu starts Intent.ACTION_DELETE with a package: URI. On newer PackageInstaller UIs the confirmation dialog didn't appear at all unless the app also declared REQUEST_DELETE_PACKAGES. We also check FLAG_SYSTEM and FLAG_UPDATED_SYSTEM_APP first, so tapping Uninstall on a built-in app explains why it can't be removed instead of silently doing nothing.

A design decision worth mentioning: the Home screen shows a small set of user-chosen favorites with full-color icons. The full app drawer is a text-only alphabetical list with search and an A–Z index bar. The goal, straight from our product spec, is access to every installed app "without making distracting apps visually appealing." Leaving icons out of the drawer is the simplest friction we could add.

4. Reading usage data without fooling yourself

ReClaim uses UsageStatsManager for two things. One is suggesting apps to block together, based on the most-used apps over the last seven days. The other is showing per-app usage on its time-limit and reminder screens. It needs the special PACKAGE_USAGE_STATS access, which the user grants in Settings (Settings.ACTION_USAGE_ACCESS_SETTINGS). You check it through AppOpsManager, not the normal runtime-permission APIs:

fun hasUsageAccess(): Boolean {
    val mode = appOps.unsafeCheckOpNoThrow( // checkOpNoThrow below API 29
        AppOpsManager.OPSTR_GET_USAGE_STATS, Process.myUid(), context.packageName
    )
    return mode == AppOpsManager.MODE_ALLOWED
}

For the "most used this week" list, queryUsageStats(INTERVAL_DAILY, start, end) summed by package is good enough.

For "how long have I used this app today", it wasn't. The aggregated stats are bucketed by day internally. A query that starts at local midnight could still include part of the previous day's bucket until it rolled over, which quietly breaks anything that resets at midnight. The fix was to replay the raw event stream from queryEvents() and sum foreground segments ourselves:

private fun foregroundMillis(pkg: String, start: Long, end: Long): Long {
    val events = usageStatsManager.queryEvents(start, end)
    val e = UsageEvents.Event()
    var active = 0; var segmentStart = -1L; var total = 0L
    while (events.hasNextEvent()) {
        events.getNextEvent(e)
        if (e.packageName != pkg) continue
        when (e.eventType) {
            UsageEvents.Event.MOVE_TO_FOREGROUND -> {
                if (active == 0) segmentStart = e.timeStamp.coerceIn(start, end)
                active++
            }
            UsageEvents.Event.MOVE_TO_BACKGROUND -> if (active > 0 && --active == 0) {
                total += e.timeStamp.coerceIn(start, end) - segmentStart
            }
        }
    }
    if (active > 0) total += end - segmentStart // still in the foreground
    return total
}

The counter, instead of naive foreground/background pairing, handles an app briefly switching between its own activities without double-counting.

One more trap: the usage data only reliably reflects a session once it has ended. For live checks while an app is still open, ReClaim tracks the current session's start with SystemClock.elapsedRealtime() and adds it on top of the historical total.

5. Enforcing blocks outside the launcher

Blocking inside your own UI is easy: before launching, check whether the package is blocked and show a block screen instead. But users don't only open apps from the launcher. They also use Recents, notifications, links and other apps. For system-wide enforcement, ReClaim offers an optional AccessibilityService that watches which app comes to the foreground.

The service config subscribes to window events only:

<accessibility-service
    android:accessibilityEventTypes="typeWindowStateChanged|typeWindowsChanged"
    android:accessibilityFeedbackType="feedbackGeneric"
    android:notificationTimeout="100"
    ... />

The core of the handler is short:

override fun onAccessibilityEvent(event: AccessibilityEvent?) {
    val e = event ?: return
    if (e.eventType != AccessibilityEvent.TYPE_WINDOW_STATE_CHANGED) return
    val pkg = e.packageName?.toString() ?: return
    if (pkg == "com.android.systemui" || pkg == packageName) return // shade, QS, our own UI
    if (pkg !in blockedPackages) { lastPackage = pkg; return }

    // Debounce so one app switch doesn't stack several block screens.
    val now = SystemClock.elapsedRealtime()
    if (pkg == lastPackage && now - lastRedirectAt < 1_000L) return
    lastPackage = pkg; lastRedirectAt = now

    startActivity(Intent(this, BlockedActivity::class.java).apply {
        addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK)
        putExtra(BlockedActivity.EXTRA_PACKAGE, pkg)
    })
}

A few lessons from building this:

Ignore System UI. The notification shade, quick settings and the volume panel briefly take window focus without the user leaving their app. Treating them as an app switch caused wrong behavior downstream, so com.android.systemui is skipped entirely.
You can't kill another app. Android gives third-party apps no API to force-stop another app's process. Sending the user to a full-screen block (or Home) is the permitted way to do it.
Keep the blocked set in memory. blockedPackages comes from a Flow that merges temporary blocks from Room with scheduled blocks. It's re-evaluated whenever a block changes and once a minute so schedules switch on and off on time. The event handler only does a set lookup.
Blocks don't have an "undo". The repository deliberately has no public unblock(). A block simply expires. That's a product decision, not a technical one, but it shapes the data layer: expired rows are pruned lazily and the DAO's delete method exists only for cleanup.
Stay alive. Setup offers the one-tap REQUEST_IGNORE_BATTERY_OPTIMIZATIONS dialog so Doze/App Standby is less likely to restrict blocking in the background.

Accessibility APIs are sensitive, and Google Play treats non-accessibility uses of them as a policy-reviewed case. ReClaim shows its own disclosure dialog before sending the user to Accessibility settings. It says plainly that ReClaim isn't an accessibility tool, that only the foreground app's identity is checked, and that screen content is never read or sent off the device. The single exception is reading a picture-in-picture window's on-screen bounds so a video left playing after a block can be swiped away. If you build something similar, write that disclosure first. It forces you to keep the service small.

6. Small things nobody tells you

Pulling down notifications from a gesture has no public API. Launchers commonly call the hidden StatusBarManager.expandNotificationsPanel() via reflection, which needs the EXPAND_STATUS_BAR permission. Wrap it in runCatching. It's not guaranteed to exist.
Default shortcuts (Phone, Photos) are resolved from the system: ACTION_DIAL and CATEGORY_APP_GALLERY. Ignore results whose package is "android", because that's the resolver/chooser, not a real default.
Web search fires ACTION_WEB_SEARCH and falls back to a browser URL, so it still works on devices without a search app.

Wrapping up

The interesting part of a launcher isn't the grid of icons. It's the platform plumbing underneath: the HOME intent and its launch modes, the gap between ROLE_HOME and what Home actually resolves to, LauncherApps for the app list, usage events you have to replay yourself, and an accessibility service kept as small as possible.

ReClaim isn't on Google Play yet. If you want to try it when it launches, there's a waitlist at tryreclaim.io. If you're more interested in the user side of this, here's how we think about a minimal Android home screen setup.

Questions about any of the Android APIs above, or a launcher quirk you've hit yourself? Drop them in the comments.

This post was drafted with AI assistance and reviewed by the ReClaim team. Code excerpts are from the ReClaim app.