DEV Community: Thomas Künneth

Adaptable apps on ChromeOS: a post-mortem

Thomas Künneth — Sat, 23 May 2026 11:26:02 +0000

In my previous article Building a custom launcher for ChromeOS I described how Be nice runs on Chromebooks: not as a real default home app, because default home settings (Settings.ACTION_HOME_SETTINGS) usually are not available on ChromeOS, but as a normal Android app in an ARC window. I pretended the app is the launcher in code (detectIsHomeApp() returns true on ChromeOS), worked around split-screen bugs that leave the app a black rectangle, and gave up transparent wallpaper for an opaque scaffold because ARC does not show the ChromeOS desktop behind the window the way a phone shows its wallpaper.

What that article obviously could not cover is the fight that came right after. For about a week in May 2026 I tried to get rid of a system confirmation ChromeOS shows when users open the preset-size menu in the ARC window title bar and choose Resizable, at least on Play Store builds. During my experiments, manifest changes often looked fine from Android Studio; however, on Play, the dialog stayed. I tried adding XML, asking AI assistants, including Google’s own models, for the magic flag. Here’s what I learned along the way.

What users see

ChromeOS does not present Play Store Android apps the same way in every posture. On a convertible or clamshell Chromebook in laptop use, ARC usually places apps in individual windows (chromeos.dev). The title bar often labels the current layout (Phone, Tablet, or Resizable) and opens a menu to switch presets; choosing Resizable is what triggers the warning below, not dragging the window frame by itself (in fact, resizing the window by dragging one of the window edges does not work until it is allowed through the dialog). In tablet mode the picture is different: apps commonly launch and stay full screen, which matches how ChromeOS has long treated touch-first use on detachables (Chrome Unboxed on immersive mode). The resize presets and the warning below matter most when you are in a windowed, laptop-style layout, not when an app is already filling the screen in tablet mode.

From that menu, when you choose Resizable in a windowed, laptop-style layout, ChromeOS brings up a confirmation that has been written about since around 2021 (Chrome Unboxed, Chrome Nerd):

This app is designed for mobile and may not resize well. The app may experience issues or restart.

Some apps never offer Tablet or Resizable at all; they stay on Phone with “This app only supports this size”, which is the stricter case when developers set resizeableActivity="false" (About Chromebooks). Be nice was not locked like that; Tablet and Resizable appeared in the title-bar menu, but the mobile warning still appeared when I chose Resizable on Play installs.

What made debugging miserable was Studio versus Play. Local installs felt better; store builds did not. Play Help describes Phone, Tablet, and Resizable presets accessible directly from the window title bar, which matches how I used them on my Chromebook, though the exact entry point may differ by ChromeOS version. Play Help also says resize presets apply to newly downloaded apps, so I shipped many builds in quick succession. Fortunately there is an internal testing track. Never do this in production.

What I started with

The manifest did not spell out ChromeOS windowing. There was no explicit resizeableActivity, no ChromeOS window metadata, and no optional touchscreen or PC hardware features. On ordinary Android that omission was deliberate: for apps targeting API level 24 and higher, resizeableActivity defaults to "true" when you leave it out (<application>, <activity>). Be nice targets API 37 with minSdk 28, so phone and tablet builds were already resizable in multi-window terms; I had never needed the attribute in XML. What I lacked were the Chromebook-specific hints, not the baseline Android flag. The launcher already listened for size-related configChanges, including smallestScreenSize, but I had not told ChromeOS how I wanted freeform launch or Play classification on devices without touch. The working theory was simple: add the flags Google documents for Chromebooks, and the dialog would go away.

What I tried

Declare the app resizable. I set android:resizeableActivity="true" on the application and told Play users I had “improved detection of the app's resize capabilities on ChromeOS.” On Android I had mostly made explicit what the target SDK already implied; it did not unlock resize on phones or tablets that was missing before. It does not remove the “designed for mobile” prompt when someone picks Resizable on ChromeOS either. I had conflated “allowed to resize” with “ChromeOS will not warn.”

Tell the system I support size changes. I added android.supports_size_changes at the application level, later duplicated it on individual activities, and at one point switched from <meta-data> to <property>. The hope was that ChromeOS would treat the app as resize-aware and skip the warning. Nothing in the public docs ties that flag to suppressing the dialog; the warning outlived every variant.

Ask for a tablet-shaped launch. I set WindowManagerPreference:FreeformWindowSize to tablet on the home activity so the window would open in a tablet preset rather than phone-sized mobile. Changelog copy spoke of “default tablet window size.” That metadata only affects how the window opens in freeform mode (chromeos.dev), not whether the user sees the mobile warning when they switch to Resizable. I later removed the tablet preset while still chasing the same popup, so I had already abandoned my own hypothesis.

Pin static launch bounds. I added <layout> on the launcher (and eventually on other activities) with default width and height in dp; I tried 840×640 first, then larger bounds as the experiment went on. At the same time I still had, or had just had, tablet freeform metadata on the same activity. Documentation warns that static <layout> bounds and FreeformWindowSize can conflict; I ran both anyway. Without success, that is.

Declare Chromebook-friendly hardware. Following a suggestion from Gemini, I marked touchscreen, faketouch, and android.hardware.type.pc as not required, and added <supports-screens> with every size bucket enabled. The touchscreen and PC entries are appropriate for Play on Chromebooks (manifest compatibility), but they address installability and input, not the resize confirmation string.

Widen configChanges to avoid restarts. I started with a modest list, then expanded it, then trimmed it back down. At one point the manifest listed almost every flag I could find, including locale, font scale, and color mode, on the theory that activity restarts on resize triggered bad behavior or the warning. It became unreadable, and it did not help.

Activity embedding override. I even added PROPERTY_ACTIVITY_EMBEDDING_ALLOW_SYSTEM_OVERRIDE at the application level. That belongs to a different feature (embedding / multi-pane); it has no documented link to ChromeOS freeform resize warnings, and, to no one's surprise, it did not help.

Time to recap

Declaring resizeableActivity tells the system the app accepts window resize (rather than staying in a fixed compatibility viewport on large screens); it does not opt out of the Resizable confirmation. supports_size_changes and launch metadata do not either. Optional touchscreen declarations matter for Chromebook distribution; they were never documented as silencing “designed for mobile.” The dialog fits Google’s preset-size UX, which is a way for users to pick Phone or Tablet without every app being fully adaptive (Android Community). I had spent a week tuning manifest knobs for a message the OS shows on purpose when the user chooses Resizable, and for which I have not found an officially documented, bulletproof way out.

The biggest learning was not to underestimate what changes when the app comes from a Play install. Installing from Android Studio had led me to think the problem was solved; the store build told a different story. Play distribution, install context, and ChromeOS window presets are part of the behavior you are debugging, and they are not fully visible if you only deploy from the IDE.

Nothing in this effort demonstrated that the “designed for mobile” dialog can be removed from the manifest alone. I continue with a manifest that reflects adaptability on Android in general: resizeableActivity on the application, android.supports_size_changes on the home activity, optional touchscreen / type.pc hardware declarations for desktop-class devices, and size-related configChanges as chromeos.dev's second option for window reshape. The adaptive UI itself stays in Compose (WindowSizeClass and layouts that follow the window).

That is the story in prose; here is what it looks like in app/src/main/AndroidManifest.xml today:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:tools="http://schemas.android.com/tools"
    xmlns:android="http://schemas.android.com/apk/res/android">

    <queries>
        <intent>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent>
    </queries>

    <uses-feature
        android:name="android.hardware.touchscreen"
        android:required="false" />
    <uses-feature
        android:name="android.hardware.faketouch"
        android:required="false" />
    <uses-feature
        android:name="android.hardware.type.pc"
        android:required="false" />

    <application
        android:name=".BeNiceApplication"
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:enableOnBackInvokedCallback="true"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:resizeableActivity="true"
        android:supportsRtl="true"
        android:theme="@style/Theme.BeNice"
        tools:ignore="UnusedAttribute">

        <activity
            android:name=".AppChooserActivity"
            android:configChanges="orientation|screenLayout|screenSize|smallestScreenSize"
            android:exported="true"
            android:launchMode="singleTask"
            android:stateNotNeeded="true"
            android:windowSoftInputMode="adjustResize">
            <meta-data
                android:name="android.supports_size_changes"
                android:value="true" />
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.HOME" />
                <category android:name="android.intent.category.DEFAULT" />
            </intent-filter>
        </activity>

        <activity
            android:name=".ImageViewerActivity"
            android:configChanges="orientation|screenLayout|screenSize|smallestScreenSize"
            android:exported="false">
            <intent-filter>
                <action android:name="android.intent.action.QUICK_VIEW" />
            </intent-filter>
        </activity>

        <activity
            android:name=".BeNiceActivity"
            android:configChanges="orientation|screenLayout|screenSize|smallestScreenSize"
            android:excludeFromRecents="true"
            android:exported="true">
            <intent-filter>
                <action android:name="de.thomaskuenneth.benice.intent.action.ACTION_LAUNCH_APP" />
            </intent-filter>
            <intent-filter>
                <action android:name="de.thomaskuenneth.benice.intent.action.ACTION_LAUNCH_APP_PAIR" />
            </intent-filter>
        </activity>

        <service
            android:name=".BeNiceTileService"
            android:exported="true"
            android:icon="@drawable/tile_service_icon"
            android:label="@string/app_name"
            android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
            <intent-filter>
                <action android:name="android.service.quicksettings.action.QS_TILE" />
            </intent-filter>
        </service>

        <receiver
            android:name=".ShortcutPinnedReceiver"
            android:exported="false" />

    </application>

</manifest>

If you strip away the experiments, two resize declarations and one documented fallback are still worth keeping, and none of them is the magic flag that silences the dialog:

android:resizeableActivity="true" on <application>. Google expects apps that behave well when resized to declare resizeableActivity or supports_size_changes as enabled (device compatibility mode). At my target SDK the default is already true; I keep it explicit anyway.
<meta-data android:name="android.supports_size_changes" android:value="true" /> on AppChooserActivity. Same guidance: declare that the activity handles size changes without fighting compatibility mode. I put it on the home activity, not on every screen.
android:configChanges="orientation|screenLayout|screenSize|smallestScreenSize" on activities. chromeos.dev lists this as its second option for resize; the first is ViewModel plus saved state so activity recreation stays cheap. I use the flags to skip a full tear-down when the ARC window changes shape. Current adaptive app guidance puts currentWindowAdaptiveInfo() and responsive Compose layouts first; I do not override onConfigurationChanged, and I am not claiming this manifest line is the adaptability strategy. It is optional lifecycle plumbing on top of WindowSizeClass.

The arc is not a win. It means accepting that Google never documented a clean way out of the Resizable warning, that Play behavior on Chromebooks stays largely opaque until you ship and test there, and that ChromeOS itself feels like a platform Google is letting fade while Aluminium OS and unified Android desktop take the spotlight.

What's more, there is that feeling of being treated unfairly. Google pushes developers hard on making their apps behave well on as many device categories and form factors as possible, yet even first class citizens are stigmatised by this popup.

Has anyone found a workaround, or is this firmly an OS-level restriction? Let me know in the comments if you've felt this pain, too.

References

Building a custom launcher for ChromeOS

Thomas Künneth — Thu, 14 May 2026 11:11:33 +0000

In this article, I will share some of my experience of enhancing Be nice to be a launcher on ChromeOS. Now, why would I want to do that anyway? I use my ChromeOS detachable more like an Android tablet than a traditional laptop; therefore, I find myself deeply missing the Android goodness that Google's desktop OS tends to strip away. Chief among these missing features is support for app widgets. Be nice has app widget support, so it would be great to run my app on ChromeOS. On a standard Android phone or tablet you can simply swap the home app in settings.

fun changeDefaultHomeApp() {
  val intent = Intent(Settings.ACTION_HOME_SETTINGS).apply {
    addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
  }
  if (context.packageManager.resolveActivity(
      intent,
      PackageManager.MATCH_DEFAULT_ONLY
    ) != null
  ) {
    context.startActivity(intent)
  }
}

Unfortunately, ChromeOS forces you to use its native environment.

Consequently, the launcher will be treated just like any other Android app. What does this imply? While we can easily launch other apps, core launcher features like returning to the home screen via the system gesture or home button, acting as the dedicated home activity that fills the display with the normal Android home wallpaper visible behind transparent UI, and integration with the system-level overview or task switcher are not available. Instead, the launcher stays contained within its own window, meaning a swipe up or a press of the Everything Button will still take you back to the native ChromeOS shelf rather than your custom interface.

And there is another nasty issue. Before Be nice became a genuine launcher, its main goal was to run two apps side by side, utilizing the split-screen capabilities that are present in Android since 7.0 (Nougat). On ChromeOS, this behavior is consistently buggy. Specifically, when the launcher attempts to start another activity in the adjacent window for a side-by-side view, the originating app (Be nice itself) fails to redraw correctly and simply becomes a black, unresponsive rectangle. I have created an issue tracker item for this, as the black screen glitch makes automated multitasking nearly impossible on ChromeOS. The issue is, at the time of writing this article, marked as Assigned, though there has been no significant movement toward a fix. It is disheartening to see such a fundamental multitasking feature remain broken while Google continues to market these devices as serious productivity tools.

Let's return to Be nice. When the app is the default launcher, tapping an item in its Apps list launches the desired app just like any launcher would; however, when Be nice is not the default home app, it intentionally opens the tapped app in split-screen. While the default home app behavior is what we want on ChromeOS, on that platform we just can't become the launcher. To cater for this, I changed Be nice to do this:

private fun detectIsHomeApp(): Boolean {
  if (isRunningOnChromeOs()) {
    return true
  }
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
    val roleManager =
      context.getSystemService(RoleManager::class.java)
    return roleManager?.isRoleHeld(RoleManager.ROLE_HOME) == true
  } else {
    val intent = Intent(Intent.ACTION_MAIN).apply {
      addCategory(Intent.CATEGORY_HOME)
    }
    val resolveInfo =
      context.packageManager.resolveActivity(
        intent,
        PackageManager.MATCH_DEFAULT_ONLY
      )
    return resolveInfo?.activityInfo?.packageName == context.packageName
  }
}

But what does isRunningOnChromeOs() do?

fun isRunningOnChromeOs(): Boolean {
  val pm = context.packageManager
  return pm.hasSystemFeature(SYSTEM_FEATURE_TYPE_CHROMEBOOK) ||
    pm.hasSystemFeature(SYSTEM_FEATURE_ARC) ||
    pm.hasSystemFeature(SYSTEM_FEATURE_ARC_DEVICE_MANAGEMENT)
}

Because ChromeOS will not let Be nice hold the real home role, RoleManager would always report that we are not the default launcher. The early return true in detectIsHomeApp() is therefore a deliberate in‑app policy switch: on ChromeOS we pretend we are the home app so the rest of the codebase can follow the same paths it uses when Be nice truly is the launcher on phones and tablets, without claiming any privilege the OS refuses to grant.

isRunningOnChromeOs() exists because a single PackageManager feature is not reliable across ARC/ARCVM builds: android.hardware.type.chromebook was absent on my device, so relying on it alone left detection false and the old UX in place. org.chromium.arc (and the related org.chromium.arc.device_management flag) matches what Android’s own docs and compatibility tooling use for the ChromeOS Android runtime; we still OR in the chromebook feature string when the system exposes it. Together, that trio is a pragmatic runtime probe; not a perfect definition of ChromeOS everywhere, but a stable way to branch behavior where the platform already diverges from stock Android.

About wallpapers

On phones and tablets, Be nice is written like a classic launcher: the app theme turns on android:windowShowWallpaper and uses a transparent window background, and the main shell keeps the Material Scaffold surface transparent so the Android home wallpaper can show through wherever the UI does not paint an opaque layer. I do not sample the wallpaper with WallpaperManager and draw it myself; instead, I rely on the system to composite the wallpaper behind the window, which is simple and matches how many launchers behave.

<style name="Theme.BeNice" parent="Theme.AppCompat.DayNight.NoActionBar">
  <item name="android:windowShowWallpaper">true</item>
  <item name="android:windowBackground">@android:color/transparent</item>
</style>

The Compose tree leans into that model as well. For example, when Be nice believes it is acting as the default home app and the pager actually has transitions between widget-style home pages and other pages, the horizontal pager applies a fade on those transitions so the swipe does not feel like hard cuts over a solid sheet; visually that only works if there is something worth looking at behind the transparent regions.

val wallpaperFadeEdgeIndices = remember(pages) {
  computeWallpaperFadeEdgeIndices(pages)
}
val useHomeWallpaperPagerFade = state.isHomeApp && wallpaperFadeEdgeIndices.isNotEmpty()

ChromeOS breaks the mental model. The wallpaper you care about on a Chromebook is usually the ChromeOS desktop behind all windows, while Be nice runs inside the Android (ARC) window. windowShowWallpaper still asks the Android side to show its wallpaper layer, but that layer is often weak, empty, or simply not the same thing as the ChromeOS background you identify as my wallpaper. Transparent UI that looks intentional on a Pixel can read as muddy, flat, or accidental in a resizable Android window.

Scaffold(
  containerColor = if (defaultAppsManager.isRunningOnChromeOs()) {
    MaterialTheme.colorScheme.background
  } else {
    ComposeColor.Transparent
  },
  // ...

Even after switching the main Scaffold to an opaque background on ChromeOS, the pager’s cross-fade still runs only when the app considers itself the home app and the page list includes at least one transition between a widget-style home page and a non-widget page (the same situation useHomeWallpaperPagerFade encodes), so the animation eases between pages over the opaque shell, not over the live wallpaper, without pretending ARC gives you a phone-quality backdrop.

So the pragmatic fix is boring but honest: on ChromeOS, stop pretending the ARC wallpaper layer is a beautiful backdrop. In the main activity I branch Scaffold’s containerColor: opaque theme background on ChromeOS, transparent on everything else. That trades the phone-launcher aesthetic on ChromeOS for a predictable in-window surface, which matches how the platform actually presents Android apps.

Wrap-up

A pragmatic fix is also a boring one: a solid theme background is honest about ARC, but it is not necessarily nice. In a follow-up, I may explore what it would take to get an actually pleasant backdrop on ChromeOS, without lying to myself that windowShowWallpaper is doing the same job it does on a phone, whether that means sampling and drawing wallpaper myself, using a curated gradient or image asset, or finding a host-supported way to align with ChromeOS personalization. If you have solved this cleanly in a launcher-style app on ARC, I would love pointers.

Beyond wallpaper, the other open question is how to replace the system gestures you do not get on ChromeOS (home, recents, and that snap back to launcher feeling), without fighting the shell. I have started experimenting with notifications as a lightweight, always-reachable affordance: not as a fake home button, but as a predictable escape hatch back into Be nice when the OS route is wrong for how I actually use the device. I do not have a polished pattern yet. If you have tried notification-driven navigation (or a better substitute) for ARC-hosted almost launchers, kindly share what worked in the comments.

Bubble up - Android 17's new multitasking feature explained

Thomas Künneth — Mon, 11 May 2026 14:55:40 +0000

Only with the release of 12L, Google became serious about making Android a productivity powerhouse across screen sizes and form factors. While we had tablets much earlier, neither the OS nor Mountain View’s flagship apps took advantage. With 12L, we got the persistent taskbar, which made dragging and dropping apps into split-screen mode a natural gesture. Subsequent updates like Android 14 and 15 refined this by adding app pairs and improving how the system handles unoptimized apps in multi-window mode. Android 16 introduced the Desktop Mode that allows for freeform window resizing similar to a traditional PC. And yes, we had seen precursors of this much earlier. Android 7.0 Nougat shipped with a hidden freeform windows developer flag, though it languished for years without proper app support or official ecosystem commitment.

While ChromeOS can be considered a productivity hub, too (many devices are either detachables or convertibles, and some come with a stylus in the box), it's not Android. Although it runs Android apps (in a container called ArcVM), and even though the apps are shown in freely movable and resizable windows, apps run on an outdated Android version (depending on the device, Android 11, 13, or 15); what's more, the integration is plagued by a couple of annoying user-facing bugs that make the split-screen feature practically unusable.

(Chat) Bubbles

With chat bubbles, Google introduced an alternative to notifications, specifically targeting conversations. Introduced with Android 11, these floating windows aimed at making chats more accessible without switching apps by putting them on top of other content. The implementation always felt like an experiment. The Bubbles API is an extension of the ShortcutInfo and Notification APIs. To this day, the feature is tied to the MessagingStyle notification category. Consequently, developers can't just bubble any arbitrary app component, limiting a promising windowing concept to a niche utility for messengers like WhatsApp, Signal, or Telegram. Until Android 17, that is. This version can finally treat (almost) every app as a flexible, floating entity that can live on top of other apps.

Apps are bubbled up from their launcher icons. By long-pressing any app on the home screen, app drawer, or taskbar, you’ll find a new Bubble option in the context menu. Tapping it pops the app into a floating window that persists over the current activity. On larger screens, you can drag an app icon from the taskbar directly into a screen corner to trigger the transition. Once active, the bubbles can be moved freely, stacked with other apps, or minimized into a floating pill on the edge of the display.

Transforming an app into a floating bubble, fortunately, is far from requiring a total rewrite. But it does require moving away from a fixed-screen mindset towards adaptability. On Android 17, the system treats bubbles as a specialized windowing mode; therefore, the technical hurdles are now closely aligned with standard multi-window support. To ensure your app is ready to be bubbled, it must meet these core requirements:

Support Multi-Window Mode
Correctly handle configuration changes
Target API level 37
Optimize for Adaptive Layouts

A Glimpse Behind the Curtain

The new Bubbles feature required a fundamental reorganization of the system's task management. Android now leverages TaskView (the robust successor to the internal ActivityView) to reparent an entire app task into a specialized floating container. This architecture is a direct sibling to the new Desktop Mode, sharing the same underlying freeform windowing logic. Internally, this convergence is often referred to as Desktop Interactive PiP (iPiP), which leverages the USE_PINNED_WINDOWING_LAYER permission to manage these interactive, persistent layers.

When an app is bubbled, the WindowManagerService creates a virtual display environment, intercepting and translating touch events and window insets in real-time to ensure the app remains responsive in its new dimensions. To keep the transition fluid, the system utilizes Shell Transitions, performing an atomic handoff that moves the task from a full-screen state to a floating layer without a flicker. This process avoids the typical destroy-and-recreate lifecycle by heavily favoring onConfigurationChanged, preserving the user’s backstack and state perfectly.

Ultimately, what looks like a simple UI pop is a complex orchestration of task reparenting and display abstraction that brings Android closer to a true desktop-class windowing engine.

The Secondary Display Pitfall

Because the system creates a virtual display environment to host the bubbled task, your app is technically no longer running on the default display. This introduces an important requirement for context management:

Avoid Application Context: Always use the Activity context for UI-related tasks, such as inflating layouts or querying WindowManager. The Application context is tied to the primary display and will not reflect the bubble's unique window metrics, density, or insets.
Dynamic Layout Queries: Don't cache screen dimensions at startup. Since the bubble can be resized or moved between different display states (like folding/unfolding), your app must rely on WindowMetrics and the onConfigurationChanged callback to adapt to its floating container in real-time.
Resource Loading: Resources loaded via the Activity context will correctly resolve to the bubble's specialized configuration, whereas the Application context may return values intended for the full-screen state

Managing the Task Lifecycle

Beyond the UI, the transition to a bubble affects how Android manages your app's task- and backstack. To ensure a seamless pop, you need to keep a few details in mind. When an app is bubbled, the system re-parents the existing task. If your app relies on complex launch modes like singleInstance or singleTask, ensure that your intent handling doesn't inadvertently clear the backstack when the user toggles between full-screen and bubble mode. Also, because the system utilizes Shell Transitions for an atomic handoff, it preserves the user's state perfectly without a destroy-and-recreate cycle. However, if your app is killed in the background while minimized as a floating pill, it will restart into the bubble container. Finally, the Bubble up mechanism utilizes the ShortcutManager. If your app uses dynamic shortcuts, ensure the LocusId remains consistent so the system can correctly associate the floating window with the specific user context or conversation it originated from.

Wrap-up

From a user's perspective, the Bubble feature is activated from a simple context menu item. But code-wise? Google expanded the LauncherApps and ShortcutManager services to bridge the gap between the launcher and the window manager. There is a new system-level intent handling logic that allows the launcher to query an app's compatibility with the TaskView stack without the app ever needing to fire a notification. Essentially, the system now checks for android:resizeableActivity="true" and android:supportsPictureInPicture="true" (or the new android:allowUntrustedEmbedding) as a signal that the app can handle the floating lifecycle. This turns multitasking from something an app requests into something the user commands.

What about third-party launchers? Historically, whenever Google introduced a deep system-level multitasking change, third-party developers were left in the lurch, and Android 17 is no different. While the new Bubble feature is baked into the platform, the specific Bubble menu item and the drag-and-drop gestures are currently exclusive to the system’s own launcher. Third-party launchers can’t simply opt-in to this context menu (or provide their own) because the underlying intent handling and TaskView orchestration are tied to privileged system permissions that aren't exposed to the public SDK. At this stage, while third-party launchers can of course see your app, they lack the system-level handshake required to command the window manager to reparent your task into a bubble. Until Google decides to open up these specific LauncherApps flags to non-system callers, the Bubble up power remains a walled-garden feature for the default launcher experience.

Agentic interaction using AppFunctions

Thomas Künneth — Mon, 06 Apr 2026 06:49:26 +0000

Given the rise of agentic interaction on Android, we need a fast, reliable API to make app capabilities discoverable and executable by agents. Through the years, Google has introduced several native frameworks to bridge the gap between the operating system, its system-level assistants, and apps.

App Actions is the long-standing predecessor to AppFunctions. It uses shortcuts.xml and built-in intents to map specific user requests directly to app features. Android Slices were an attempt to surface interactive snippets of an app’s UI directly within the assistant or search interface; they have been effectively deprecated since 2021. Then there's the Direct Actions API, a framework introduced to allow voice assistants to query a foreground app for its specific capabilities in real-time. Gone too. Finally, the Assist API: the fundamental system-level hook that allows a native agent to read the screen context, providing the situational awareness necessary for agents to act on behalf of the user.

In retrospect, the failure of these predecessors likely wasn't due to a lack of vision, but rather a fundamental mismatch between static engineering and the needs of dynamic intelligence. App Actions relied on a rigid library of built-in intents. If an app feature didn't fit into one of Google’s binding categories, it effectively didn't exist to the assistant. Android Slices were killed by the UI maintenance trap. By forcing developers to build and maintain restricted, templated versions of their interface that often felt out of place, Google asked for too much effort for too little user engagement. The Direct Actions API failed because of its requirement that an app is actively running on the screen, which prevents the assistant from performing tasks autonomously. And while the Assist API provided the eyes for the system, it lacked the intelligence. It could scrape a messy tree of text and nodes from the screen, but it couldn't reliably parse that data into meaningful actions without massive compute power and significant privacy trade-offs. Ultimately, these frameworks offered narrow shortcuts when the ecosystem instead required a universal language.

AppFunctions

Unlike its predecessors, which tried to force apps into predefined boxes or complex UI mirrors, the AppFunctions model treats the app as a collection of capabilities to be indexed, rather than a destination to be visited. By shifting the focus from how the app looks to what the app can do, Google is moving toward a model where the agent doesn't just deep-link you into a screen, but picks up the tools to finish the job for you.

AppFunctions have been in the works since late 2024. Although the official android.app.appfunctions package didn't land in the core framework until API level 36, the missing link for developers was the appfunctions Jetpack library, which began its alpha rollout in May 2025. This library allowed early adopters to start wiring their apps for tool use before the corresponding platform APIs were finalized. At that stage, it was a framework waiting for a brain; Jetpack supplied the plumbing, but assistants such as Gemini were not consistently able to invoke those tools on every device or build. Android 16 adds the platform hooks for discovery and execution on supported hardware. As of today, Google still frames the overall agent push as early / beta and describes two parallel tracks:

AppFunctions as structured, self-describing entry points (what this article is about: discrete capabilities agents can call)
UI automation for longer flows when there is no tailored integration: previewed on devices such as the Galaxy S26 series and select Pixel 10 models, in limited verticals and regions, with multi-step delegation already part of that story

In Google’s February 2026 post on the intelligent OS, the Looking ahead section states that Android 17 is meant to broaden these same capabilities; that includes structured AppFunctions and the agentic UI automation previews already tied to hardware such as the Galaxy S26 series and select Pixel 10 models; the stated aim is to reach more users, more developers, and more device manufacturers.

Let's turn to the stack you can use today: Gradle, Kotlin, and the device-facing adb checks that validate a real APK against the current Jetpack and platform drops.

Implementing an AppFunction

To start implementing AppFunctions, your development environment might require a few specific upgrades. First, ensure you are running a recent version of Android Studio to access the latest Gemini-integrated testing tools. While the Jetpack library itself can target a lower minSdk where compatibility allows, you’ll want compileSdk 36 and typically targetSdk 36 so the Android 16 framework can index and run your AppFunctions on device. Next, declare the Jetpack coordinates in your version catalog, then wire plugins, SDK level, KSP, dependencies, and merge ordering in the app module.

Version catalog (`gradle/libs.versions.toml`)

[versions]
appFunctions = "1.0.0-alpha08"

[libraries]
androidx-appfunctions = {
 group = "androidx.appfunctions",
 name = "appfunctions",
 version.ref = "appFunctions"
}
androidx-appfunctions-service = {
 group = "androidx.appfunctions",
 name = "appfunctions-service",
 version.ref = "appFunctions" 
}
androidx-appfunctions-compiler = {
 group = "androidx.appfunctions",
 name = "appfunctions-compiler",
 version.ref = "appFunctions"
}

App module (`app/build.gradle.kts`)

plugins {
 alias(libs.plugins.android.application)
 alias(libs.plugins.kotlin.android)
 // Apply KSP to process the @AppFunction annotations
 alias(libs.plugins.google.devtools.ksp)
}

android {
 // compileSdk 36 aligns with Android 16, where platform AppFunctions APIs land
 compileSdk = 36    
 // ... rest of your config
}

ksp {
 arg("appfunctions:aggregateAppFunctions", "true")
}

dependencies {
 implementation(libs.androidx.appfunctions)
 implementation(libs.androidx.appfunctions.service)
 ksp(libs.androidx.appfunctions.compiler)
}

// Run each merge*Assets after its matching ksp*Kotlin so AppFunctions metadata is generated first
tasks.configureEach {
  if (!name.startsWith("merge") || !name.endsWith("Assets")) return@configureEach
  if (name.contains("ArtProfile")) return@configureEach
  val variant = name.removePrefix("merge").removeSuffix("Assets")
  val kspTask = "ksp${variant}Kotlin"
  if (tasks.names.contains(kspTask)) {
    dependsOn(kspTask)
  }
}

While the Jetpack library automates the plumbing (from generating schemas to registering them) the system fundamentally relies on AppSearch for on-device indexing. The beauty of the library is that it handles the AppSearch integration entirely behind the scenes; you don't need to manage sessions or write storage boilerplate yourself for your AppFunctions to become discoverable. With the environment ready, the next step is to spell out what distinguishes an AppFunction in source.

At its core, an AppFunction is a standard Kotlin function; but it carries a few specific decorations that turn it from a private app method into a public system tool:

The @AppFunction annotation signals to the compiler that a method should be exported as such a system-level tool. Use @AppFunction(isDescribedByKDoc = true) when you write a real KDoc block on that method; the compiler folds that documentation into the metadata agents and indexers consume, so parameter semantics (for example that app1 and app2 are package names) are not left implicit.
AppFunctionContext provides the function with essential situational awareness, such as information about the calling party or access to the app's own resources.
AppFunctionSerializable ensures your custom data classes are properly handled while they travel across process boundaries.

Let's see this in action in a real utility. In my app Be nice, a core feature is the ability to create app pairs (launching two apps in split-screen simultaneously). By exposing this as an AppFunction, we turn a sequence of UI interactions (opening a dialog, choosing apps, customizing parameters) into a single voice command. On eligible devices and assistant builds (as mentioned, Google’s rollout is still limited) you can ask Gemini to create an app pair for contacts and clock. The agent will call our AppFunction, passing the two apps’ package names as strings.

package de.thomaskuenneth.benice.appfunctions

import androidx.appfunctions.AppFunctionContext
import androidx.appfunctions.service.AppFunction
import de.thomaskuenneth.benice.R

class BeNiceFunctions {

  /**
   * Launches two installed apps together in split screen.
   *
   * @param context Execution context supplied by the AppFunctions runtime.
   * @param app1 Name of the first app in the pair.
   * @param app2 Name of the second app in the pair.
   * @return A localized message describing success or failure.
   */
  @AppFunction(isDescribedByKDoc = true)
  suspend fun createAppPair(
    context: AppFunctionContext,
    app1: String,
    app2: String
  ): String {
    val success = performPairing(app1, app2)
    return if (success) {
      context.context.getString(
        R.string.pair_created_success,
        app1, app2
      )
    } else {
      context.context.getString(
        R.string.pair_created_failure
      )
    }
  }

  private fun performPairing(a: String, b: String): Boolean {
    // Be Nice logic omitted for brevity
    return true
  }
}

I used suspend fun, like Google’s own AppFunctions examples do, so we can easily call other suspending APIs from the body whenever the implementation does real async work instead of returning immediately.

Writing a function with @AppFunction creates the capability. However, because AppFunctions are designed to be executed headlessly by the system (even if the app isn't in the foreground), the Android framework needs a static entry point to find and instantiate the code. Previous versions of the Jetpack library required quite a bit of additional boilerplate. Thankfully, most of that is now handled automatically through Manifest Merging and KSP: when you include the appfunctions-service dependency, a pre-built PlatformAppFunctionService is merged into your app's manifest, acting as the universal entry point for the system. The ksp { } block and tasks.configureEach section in the Gradle listing earlier connect your code to that service: appfunctions:aggregateAppFunctions tells the compiler to emit the aggregate inventory and related assets AppSearch reads, and the merge-after-KSP ordering ensures that output is packaged into the APK.

Testing AppFunctions

Next, let's check that your AppFunctions succeed on real setups.

adb shell cmd app_function list-app-functions | grep -F de.thomaskuenneth.benice

This command should print one or more lines that mention your package and expose each AppFunction’s stable id (often a ClassName#methodName form). This proves the OS indexer has picked up the app after install.

On some Android 16 emulator images that command may return No shell command implementation. In my case, updating the AVD to a system image at API level 36.1 brought the app_function shell path to life; Android Studio shows that revision when you choose the platform image, as in the screenshot below.

Executing an AppFunction on the command line can look frightening:

FID=$(adb shell cmd app_function list-app-functions | grep -F de.thomaskuenneth.benice | grep -oE '[A-Za-z0-9_.]+#[A-Za-z0-9_]+' | head -n1) && adb shell "cmd app_function execute-app-function --package de.thomaskuenneth.benice --function \"$FID\" --parameters '{\"app1\":[\"com.foo\"],\"app2\":[\"com.bar\"]}'"

This command prints a JSON payload: on success it is the AppFunction’s return value (here, the string that createAppPair builds); on failure you may see App function not found (wrong id) or a JSON parse error if --parameters does not use the same AppSearch-style encoding as the example; note how each string argument is passed as a one-element JSON array.

If listing or execution still fails, confirm the aggregate assets are actually packaged (for example unzip -l app/build/outputs/apk/debug/app-debug.apk | grep app_functions should list app_functions.xml and app_functions_v2.xml).

For automated tests, treat the layers separately: run the adb checks above on a device to verify that your metadata is packaged and the indexer has picked up your app. Jetpack’s AppFunctionTestRule is built for local JVM runs (the docs pair it with Robolectric-style environments) so you can exercise AppFunctionManager and your @AppFunction logic without a cable; Google explicitly says to prefer real system-level checks when you can. Add instrumented or integration coverage on an API 36+ image when you care about the full stack (AppSearch sync, shell availability, release vs debug). None of that replaces the device-facing section here; it complements it, and deserves its own write-up once you outgrow copy-paste snippets.

Wrap-up

To close this article, let's see the invocation of the Be nice AppFunction end to end:

AppFunctions sit at the intersection of Jetpack, KSP, manifest merging, and on-device indexing (messy in preview, powerful when the wiring is right). When you integrate them, you keep coming back to three things: platform context, a small Gradle and Kotlin surface that connects the aggregate compiler flag to PlatformAppFunctionService, and the device or APK checks that show whether packaging and indexing still line up.

On the official AppFunctions overview, Google only documents adb shell cmd app_function list-app-functions as a shell check; there is no second, documented adb path for the full schema text (including KDoc folded in via isDescribedByKDoc). For that, read assets/app_functions.xml / app_functions_v2.xml from the APK, or query metadata through AppFunctionManager-style APIs—the same place agents are expected to pull richer descriptions. Anything further that adb shell cmd app_function help shows on a given device is platform-specific and is not spelled out on that overview page.

One caveat worth carrying forward: in my project, making each merge*Assets task depend on the matching ksp*Kotlin task was necessary so KSP-generated AppFunctions assets were present before packaging. That ordering is not spelled out in every official sample, and it may stop being required as the Android Gradle Plugin, KSP, or the AppFunctions toolchain tightens its own task graph. Treat it as something to validate on your stack: if app_functions.xml / app_functions_v2.xml show up in the APK without the extra tasks.configureEach block, you can drop it; if they are missing at runtime, the dependency ordering is still a reliable fix.

If you ship with minify enabled (isMinifyEnabled / R8), the AppFunctions AndroidX artifacts ship consumer ProGuard rules that keep much of the generated and reflection-heavy surface for you. You should still smoke-test a release build on a device: if execution or discovery fails only after shrinking, inspect R8 output and add targeted -keep rules for your own @AppFunction classes or related types; start from what the library already merges rather than copying random snippets from older posts.

In this article, I showed you how to implement an AppFunction. As a publisher you expose AppFunctions in your APK and rely on indexing plus your own validation of arguments. Callers that discover or execute other apps’ functions go through AppFunctionManager-style APIs and sit behind platform rules; privileged assistants hold permissions such as EXECUTE_APP_FUNCTIONS that ordinary store apps do not get by declaring a line in the manifest. Google still describes much of the end-to-end agent path as experimental and capacity-limited, so assume your parameters can be reached only by trusted system-side callers today, and still treat them like untrusted input.

References

The Future of Android Apps with AppFunctions by fellow GDE Shreyas Patil goes deep on dependency injection with AppFunctionConfiguration, a note-taking sample, and adb-driven execution. Further reading beyond the links already woven through the article (overview, Jetpack release notes, platform android.app.appfunctions, intelligent-OS blog, Play listing, and AppFunctionTestRule):

AppFunction annotation (isDescribedByKDoc, compiler behavior, supported types)
AppFunctionManager (Jetpack discovery and execution APIs)
AppSearch (on-device indexing stack the runtime builds on)
Merge multiple manifest files (how library manifests contribute PlatformAppFunctionService and related entries)
EXECUTE_APP_FUNCTIONS (permission called out in the trust discussion)

From Vibe-Coding to Reality: Building MarvinSync

Thomas Künneth — Fri, 03 Apr 2026 13:17:03 +0000

If you saw my posts back in February on LinkedIn and Mastodon, you know I’ve been deep in a Cursor session. I promised to pull back the curtain on how MarvinSync—my new macOS utility for syncing local music to Android—came to life through the lens of AI-assisted development.

Before we get to the binaries (which are coming soon, I promise!), I want to share the vibe-coding post-mortem of how the first version actually took shape. If you want to follow along with the code as I describe it, the full project is already live on Codeberg.

What is MarvinSync? (And why Vibe-Code it?)

MarvinSync is a utility designed for a specific niche: people who still believe in local media ownership. It bridges the gap between a curated macOS music library and an Android device. No streaming, no cloud—just your folders, your metadata, and a clean sync via ADB (Android Debug Bridge).

But there’s a meta-story here. As an Android GDE, I spend my life deep in Kotlin, Compose, and Kotlin Multiplatform. Naturally, KMP would have been the logical choice for a cross-platform sync tool. However, I wanted to take this opportunity to go fully native on the Mac side using Swift and SwiftUI.

I’ll be the first to admit: I am no Swift expert. This is where vibe-coding comes in. I used Cursor to bridge the gap between my architectural knowledge and my lack of Swift syntax fluency. I provided the vibe—the logic, the structure, and the constraints—and the AI handled the boilerplate and the nuances of a language I’m still learning.

Trusting the folder, not the tag

One of the first big hurdles was handling music metadata. Initially, we tried the traditional route of scanning ID3 tags using standard APIs. The result was a mess of duplicates and wrong titles that didn't match how my files were actually organized.

The solution was to stop being smart with metadata and start being literal with the file system. We shifted to a strict folder-based hierarchy where the directory structure itself defines the library.

/// Inside `MusicFolderStore`. Structure: base / Artist / Album / tracks.
/// `extractArtworkFromFirstTrack` walks audio files and uses `AVMetadataItem` (identifier-based artwork only).
private func scanForAlbumsFolderBased(in baseURL: URL) -> [Album] {
    let artistURLs: [URL]
    do {
        let contents = try fileManager.contentsOfDirectory(
            at: baseURL,
            includingPropertiesForKeys: [.isDirectoryKey],
            options: [.skipsHiddenFiles]
        )
        artistURLs = contents.filter { url in
            (try? url.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) == true
        }
    } catch {
        NSLog("MusicFolderStore: failed to list base folder: \(error.localizedDescription)")
        return []
    }

    var result: [Album] = []

    for artistURL in artistURLs {
        let artistName = artistURL.lastPathComponent

        let albumURLs: [URL]
        do {
            let contents = try fileManager.contentsOfDirectory(
                at: artistURL,
                includingPropertiesForKeys: [.isDirectoryKey],
                options: [.skipsHiddenFiles]
            )
            albumURLs = contents.filter { url in
                (try? url.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) == true
            }
        } catch {
            continue
        }

        for albumURL in albumURLs {
            result.append(Album(
                title: albumURL.lastPathComponent,
                artist: artistName,
                artwork: extractArtworkFromFirstTrack(in: albumURL),
                albumURL: albumURL
            ))
        }
    }

    return result.sorted { ($0.artist, $0.title) < ($1.artist, $1.title) }
}

By using a non-recursive scan of the directory structure instead of metadata deep-dives, the app finally reflected the vibe of the actual library. It’s a reminder that sometimes the simplest architecture—the folder tree—is more robust than the most modern API.

Making Android Feel Native

A huge part of the session was dedicated to the handshake between macOS and Android. Making ADB feel like a native Mac service requires some plumbing. We built a ConnectedDeviceChecker that polls for devices every two seconds via ADB.

The checker publishes a @Published deviceStatus (ADBDeviceStatus) for the window’s status line; isDeviceConnected is simply deviceStatus == .oneDevice. The Sync button is context-aware: it only turns on when exactly one authorized device shows up in adb devices—because with two targets (say, a phone and an emulator), which device? is ambiguous until we teach the app to choose.

enum ADBDeviceStatus: Sendable {
    case adbNotSet
    case adbNotAccessible
    case noDevice
    case oneDevice
    case multipleDevices

    var statusMessage: String {
        switch self {
        case .adbNotSet: return "ADB not configured"
        case .adbNotAccessible: return "ADB not found or not accessible"
        case .noDevice: return "No device connected"
        case .oneDevice: return "One device connected"
        case .multipleDevices: return "More than one device connected"
        }
    }
}

/// Polls `adb devices` every 2s; updates `deviceStatus` from bookmarked `store.adbURL`.
final class ConnectedDeviceChecker: ObservableObject {
    @Published private(set) var deviceStatus: ADBDeviceStatus = .adbNotSet
    var isDeviceConnected: Bool { deviceStatus == .oneDevice }

    private weak var store: MusicFolderStore?
    private var timer: Timer?
    private let queue = DispatchQueue(label: "com.example.MarvinSync.adbCheck", qos: .utility)

    init(store: MusicFolderStore) {
        self.store = store
        timer = Timer.scheduledTimer(withTimeInterval: 2.0, repeats: true) { [weak self] _ in
            self?.check()
        }
        RunLoop.main.add(timer!, forMode: .common)
        check()
    }

    deinit { timer?.invalidate() }

    private func check() {
        guard let store = store else {
            DispatchQueue.main.async { [weak self] in self?.deviceStatus = .adbNotSet }
            return
        }
        guard let adbURL = store.adbURL else {
            DispatchQueue.main.async { [weak self] in self?.deviceStatus = .adbNotSet }
            return
        }
        queue.async { [weak self] in
            let status = Self.runADBDevices(executableURL: adbURL)
            DispatchQueue.main.async { self?.deviceStatus = status }
        }
    }

    private static func runADBDevices(executableURL: URL) -> ADBDeviceStatus {
        let process = Process()
        process.executableURL = executableURL
        process.arguments = ["devices"]
        let pipe = Pipe()
        process.standardOutput = pipe
        process.standardError = FileHandle.nullDevice
        do {
            try process.run()
            process.waitUntilExit()
        } catch {
            return .adbNotAccessible
        }
        let data = pipe.fileHandleForReading.readDataToEndOfFile()
        pipe.fileHandleForReading.closeFile()
        guard let output = String(data: data, encoding: .utf8) else { return .adbNotAccessible }
        let n = output.components(separatedBy: .newlines).filter { $0.contains("\tdevice") }.count
        switch n {
        case 0: return .noDevice
        case 1: return .oneDevice
        default: return .multipleDevices
        }
    }
}

Because MarvinSync is a well-behaved macOS citizen, it respects app sandboxing. However, a sandboxed app can't remember a file path after a reboot without help. To solve this, we implemented security-scoped bookmarks. This ensures that once you grant permission to access your Music folder (and separately the adb binary, often hiding under ~/Library), the app can resolve that permission on the next launch.

// Same pattern as `MusicFolderStore`: two bookmarks, two keys.
private enum Defaults {
    static let musicFolderBookmarkKey = "musicFolderBookmark"
    static let adbBookmarkKey = "adbBookmark"
}

private func saveBookmark(for url: URL) throws {
    let data = try url.bookmarkData(
        options: .withSecurityScope,
        includingResourceValuesForKeys: nil,
        relativeTo: nil
    )
    UserDefaults.standard.set(data, forKey: Defaults.musicFolderBookmarkKey)
}

private func saveADBBookmark(for url: URL) throws {
    let data = try url.bookmarkData(
        options: .withSecurityScope,
        includingResourceValuesForKeys: nil,
        relativeTo: nil
    )
    UserDefaults.standard.set(data, forKey: Defaults.adbBookmarkKey)
}

/// On startup: load `Data`, resolve, call `startAccessingSecurityScopedResource()`.
/// MarvinSync then checks `isStale` and, if needed, calls `saveBookmark` or `saveADBBookmark` again for that URL.
private func resolvedURL(bookmarkKey: String) -> URL? {
    guard let data = UserDefaults.standard.data(forKey: bookmarkKey) else { return nil }
    var isStale = false
    guard let url = try? URL(
        resolvingBookmarkData: data,
        options: .withSecurityScope,
        relativeTo: nil,
        bookmarkDataIsStale: &isStale
    ) else { return nil }
    guard url.startAccessingSecurityScopedResource() else { return nil }
    return url
}

Sync itself grew into a small pipeline: verify the Android base path, remove ignored albums on the device with carefully validated paths and shell-safe quoting (parentheses in folder names bite), then incremental adb push with size checks so we only transfer files that are missing or changed. All of that is more interesting in the repo than in a short essay—but it’s the kind of boring engineering AI accelerates when you already know what must be true.

What the code fences don’t show (but the session did)

The snippets above are the architectural spine. The rest of the Cursor log is mostly product and UX: a sectioned A–Z grid; tap an album to include or exclude it for sync, with a green checkmark when it will be copied and ignored paths persisted as relatives of the music folder. Sync opens a sheet with per-step spinners, checkmarks, and failures—errors stay on the row that broke, not in a separate alert. Removal runs only for ignored folders that still exist on the device; copy steps appear only when a size comparison shows something missing or stale, with human-readable labels (Album (Artist)) instead of raw paths. Cancel stops the pipeline; a Checking … line covers the otherwise silent do we need to copy? work. Fixing sheet height so the window stopped juddering as rows appeared took the same stubbornness as the Settings form. None of that required a fourth code listing for this post—the Codeberg tree is the ground truth—but it deserved ink here so the story matches the full chat, not only the plumbing.

The Friction of Vibe-Coding

People often ask if AI makes coding effortless. The chat log tells a different story. Cursor is excellent at bulk work and at iterating when you give crisp specs—but SwiftUI Form on macOS still caught me in a loop of almost-right layouts: labels, value columns, and path text fields that looked centered or pushed to the wrong edge no matter how many HIG-aligned refactors we tried.

At one point the chat reads like an argument, not a pull request. I wrote things I would not put in a colleague’s review—frustration that went personal (What is wrong with you?, and worse). The punchline is not that the model deserved it; it doesn’t have feelings or pride. The punchline is that I still needed to vent, then to stop accepting close enough. The fix, when it came, was almost embarrassingly small: in our case, making the Android base path TextField behave in the form the way Apple intends—.labelsHidden() so the field wasn’t fighting an implicit label column—and refusing another round of decorative layout hacks.

That friction is the human bit of AI-assisted development: not mistaking the chat for a person, but not mistaking plausible for shipped either. The best sessions, this one included, end with you back in control—exact snippet in hand, build green, behavior finally matching the picture in your head.

What’s Next?

The grid, sync sheet, and guardrails sketched above are in the repo; I even handcrafted the app icon myself (no AI involved there!).

As I mentioned in my February posts, the binaries are coming. But I wanted to document this journey first. Building MarvinSync hasn't just been about creating a tool I needed; it’s been an experiment in how a veteran Android dev can use AI to build natively for the Mac.

The source is open, the vibe is set, and soon, it'll be time to sync.

Refuelling your Jetpack

Thomas Künneth — Sun, 08 Mar 2026 11:36:03 +0000

If you are an Android developer, you know Jetpack. It changed how we build Android apps. But that was long ago. Today, the ecosystem is shifting again. We aren't just building for one platform anymore. We are building for the world. Let me show you how to take the Jetpack libraries you know and use them to fuel a new generation of applications that run everywhere.

From Jetpack to a unified architecture

First, let's ground ourselves. What exactly is Jetpack? It's more than just a bag of libraries. It is Google's opinionated answer to Android development. It unbundled features from the OS, so we could update our apps without waiting for Android system updates. It gave us backward compatibility. Most importantly, it gave us guidance. It stopped the wild west of Android development and brought us a standard way to build.

Before Jetpack, we lived in an era of fragmentation. New features were tied to the OS. If you wanted the latest UI on an older phone, you were out of luck. Eventually, Google introduced the Support Library to fix this. It sort of worked, but it was a mess. We had v4 support, v7 appcompat, v13... it was dependency hell. We needed a reboot.

That reboot came in two steps. In 2017, Google announced Android Architecture Components at I/O—ViewModel, Room, Lifecycle, LiveData—and they went 1.0 stable that November. That was the how to architect piece. Then, at I/O 2018, came Jetpack: the umbrella name and the migration to androidx.*. Eventually, everything moved to the new namespace. Libraries were strictly unbundled—own versions, own cycles, semantic versioning so we could reason about compatibility. So: Architecture Components in 2017, Jetpack and androidx in 2018.

Today, we have solved one problem but created another: The Jetpack Jungle. There are now over 130 artifacts in the suite. We have historical baggage. Deprecated libraries still sit next to modern ones—for example lifecycle-extensions, which Google deprecated and replaced with separate lifecycle-runtime, lifecycle-viewmodel, and so on, but it still turns up in old tutorials. Or security-crypto, deprecated with no clear official successor, but still in the docs. We have three different ways to do background work, two ways to do navigation, and endless UI helpers. The challenge is no longer how do I do this? but which of these 130 libraries should I actually use?

To survive the jungle, we need a map. A golden path, if you will. It's the curated, opinionated stack that Google actually recommends today. Stick to it and you avoid the jungle. UI: reactive, driven by state. Presentation: ViewModels that survive config changes. Navigation: a single graph defining your flow. Data: Room for database, DataStore for preferences. That stack is the gold standard for Android—but it no longer stops there. Everything on that list—Compose, ViewModels, Navigation, Room, DataStore—is available in Kotlin Multiplatform. You can keep the same architecture and the same APIs and compile them for iOS, Desktop, and the Web. One architecture, same code, everywhere.

That stack has a few key pieces. The UI layer is Compose Multiplatform. It is the exact same declarative, reactive paradigm you use on Android, just unbundled from the OS. You write composables, and they react to state. On Android, it's Jetpack Compose. On iOS and Desktop, it uses the Skia graphics engine to draw pixel-perfect UI while running natively on the hardware. This means you aren't learning three different UI frameworks. You aren't context-switching. You are taking your existing Android expertise and applying it to the entire world.

For state and lifecycle: Android didn't invent the ViewModel. Cross-platform frameworks like Xamarin were using the MVVM pattern to share logic between iOS and Android long before Jetpack existed. The good news is that Android and KMP have finally adapted this proven standard. You put your ViewModel in shared code. It survives configuration changes. It holds your state. It's the industry standard for a reason, and now it's the standard for our shared code, too.

Navigation is another piece. It used to be where cross-platform architectures fell apart. But not here. With Navigation Compose, your navigation graph travels with you. You declare your routes, your arguments, your back stack, and your deep links once in shared code. Type-safe. Whether it's an Android Activity, an iOS View Controller, or a Desktop Window, the platform code is just a thin container hosting your navigation. You aren't reimplementing routing logic three times. You define the flow once, and it drives the UI everywhere.

For local database storage, we use Room. If you haven't used it before, Room is a full Object-Relational Mapper (ORM) wrapping SQLite. It lets you define your data as simple Kotlin objects and maps them automatically to database tables. Its superpower is compile-time verification. Unlike many ORMs that fail at runtime, Room checks your SQL queries against your schema as you build. In this architecture, Room runs natively on iOS, Android, and Desktop, giving you a single, type-safe data layer with the performance of raw SQLite.

For configuration and preferences: every app needs to store something—whether it's a dark mode toggle, a session token, or feature flags. Usually, this means writing one implementation for iOS using UserDefaults and another for Android using SharedPreferences. With DataStore, we unify this. It is a modern, multiplatform key-value store built entirely on Kotlin coroutines. It is asynchronous by default, preventing UI freezes on any platform. You write your preference logic once in shared code, and it handles the native storage details for you.

How it fits together

So, how does this fit together? You have one shared core. This module contains almost everything: your Compose UI, your Navigation graph, your ViewModels, and your Database. Surrounding that, you have thin native shells. The Android app, the iOS app, and the Desktop app. They do little more than initialize the process and host the shared UI. They might add a splash screen or handle push notifications, but the actual application—the screens and the logic—is shared. This means no duplicate business logic and no synchronization issues between platforms.

The shared module is the structural center of your application. Inside commonMain, you place the core components we just went through. But when you need to interact with specific OS APIs—like file paths, Bluetooth, or system intents—you use the expect / actual pattern. You declare the interface in the shared code, and the platform module provides the implementation. This keeps your business logic pure and testable, ensuring platform details don't leak into your core architecture.

The platform modules are intentionally thin. On Android, you have a single Activity calling setContent. On iOS, you have a standard View Controller that hosts the shared Compose UI. On Desktop, it's just a main() function. Crucially, this is where you initialize your Dependency Injection—like Koin. You wire it up once at startup, and then the rest of the application logic is fully shared.

Dependency injection often raises a question: Isn't Hilt the recommended Jetpack DI? Yes, for Android it's fantastic. But Hilt relies heavily on Dagger and Java annotation processing, which simply does not work on iOS or Desktop. Critically, Google has not yet said anything about Hilt going multiplatform. There is no roadmap. So, to keep our shared code clean and compile-safe today, we use a pure Kotlin solution like Koin. You define your modules in shared code; each platform supplies the actuals (e.g. where's the data directory). One container, init once per platform. It effectively becomes the standard for this architecture by necessity.

To make this concrete: in CMP Unit Converter, the Koin module lives in commonMain. The database and ViewModels are provided there; the platform supplies the DB path via expect / actual:

// commonMain/.../di/AppModule.kt
val appModule = module {
    single<AppDatabase> { getRoomDatabase(getDatabaseBuilder()) }  // getDatabaseBuilder() is expect/actual
    viewModelOf(::AppViewModel)
    viewModelOf(::TemperatureViewModel)
    viewModelOf(::DistanceViewModel)
}

In practice: CMP Unit Converter

Enough theory—let's walk through the full picture. I built an app called CMP Unit Converter to prove this stack works. It converts temperatures and distances, stores your history, and remembers your preferences. It runs on Android, iOS, and Desktop, and it's built entirely on the stack we just went through: Compose for UI, ViewModels for state, Room for history, and Koin for injection. Let's tear it apart and see how it works.

When you open the project, you'll notice the structure right away. It follows the modern AGP 9 guidelines. Gradle 9.1 and AGP 9 are the baseline. In this repo the modules are: shared (the library), composeApp (the Android app), desktopApp, and iosApp is a separate Xcode project. Your Android app—here, composeApp—is its own module: just application code, no Kotlin Multiplatform plugin. The shared module uses the new com.android.kotlin.multiplatform.library plugin. In shared's build.gradle.kts you configure the Android target with androidLibrary { } inside the kotlin { } block, not the old top-level android { } block. The app module uses AGP's built-in Kotlin, so you don't apply the Kotlin Android plugin there. Android is just another target, like Desktop or iOS. This clean separation is key: the app is a thin shell, the library does the heavy lifting. It's a bit of a mental shift if you had one composeApp doing everything, but it pays off in clearer separation and faster builds.

In code it looks like this:

// shared/build.gradle.kts
plugins {
    alias(libs.plugins.androidKotlinMultiplatformLibrary)
    // ...
}
kotlin {
    androidLibrary { namespace = "..."; ... }
    // ...
}

// composeApp/build.gradle.kts
dependencies {
    implementation(project(":shared"))
    // ...
}

The shared UI lives in commonMain—for example, ConverterScreen.kt. That's the app's main screen: standard Compose code. But notice the resources—we don't have XML strings for Android and Localizable.strings for iOS. We put everything in the composeResources folder. We access them in Kotlin using the generated Res object—Res.string or Res.drawable. At compile time, CMP bundles these into the correct native format for each platform. You write the UI once, and it looks native everywhere.

// commonMain/.../ConverterScreen.kt
@Composable
fun ConverterScreen(
    navigationState: NavigationState,
    viewModel: AbstractConverterViewModel,
    scrollBehavior: TopAppBarScrollBehavior
) { ... }

// Res API (e.g. AppIcons.kt)
val Thermostat: DrawableResource get() = Res.drawable.ic_thermostat
// In composables: stringResource(Res.string.app_name)

The brain of the app is the converter ViewModels—we have TemperatureViewModel and DistanceViewModel, both in shared code and registered with Koin. When the UI loads, it asks for the ViewModel via koinViewModel(). It doesn't care if it's running on a Pixel or an iPhone. The ViewModels survive configuration changes on Android and manage state on iOS seamlessly. Same classes everywhere.

// commonMain/.../di/AppModule.kt
val appModule = module {
    single<AppDatabase> { getRoomDatabase(getDatabaseBuilder()) }
    viewModelOf(::TemperatureViewModel)
    viewModelOf(::DistanceViewModel)
}

// In a composable (e.g. App.kt)
viewModel = koinViewModel<TemperatureViewModel>()

For data, we use Room and DataStore. The app saves your conversion history in a SQLite database using Room. It remembers your last selected unit using DataStore. The only platform-specific code here is a tiny expect/actual function to tell the app where to save the file on disk (e.g. Application Support on iOS, getDatabasePath on Android). Everything else—the DAOs, the queries, the preference keys—is shared. We aren't fighting with CoreData or SharedPreferences.

// commonMain/Platform.kt
expect fun getDatabaseBuilder(): RoomDatabase.Builder<AppDatabase>

// androidMain: path from context.getDatabasePath("...")
actual fun getDatabaseBuilder() = Room.databaseBuilder<AppDatabase>(
    context = context,
    name = context.getDatabasePath("CMPUnitConverter.db").absolutePath
)
// iosMain: path from getDirectoryForType(DirectoryType.Database) → Application Support

The platform apps are just entry points. On Android, the Application class calls initKoin at startup (e.g. in CMPUnitConverterApp); MainActivity then calls setContent. On iOS, ComposeView inside a ViewController. On Desktop, main() launches the window. There's one little gotcha on iOS. When we export our Kotlin initKoin function to Swift, Kotlin/Native renames it to doInitKoin because it returns Unit. It's a small quirk, but knowing it saves you a "Method Not Found" error. Call doInitKoin in your Swift AppLifecycle and you're good to go.

In Kotlin we have:

// commonMain/.../di/KoinApp.kt
fun initKoin(config: KoinAppDeclaration? = null) {
    startKoin {
        includes(config)
        modules(appModule)
    }
}

On iOS, Swift sees the same function with the "do" prefix:

// iOS (Swift). Kotlin exports Unit-returning functions with "do" prefix:
KoinAppKt.doInitKoin()

Takeaways and resources

One of the most common pitfalls is version mismatch. Your shared module pulls in Compose Multiplatform and a specific Compose runtime. Your Android app uses activity-compose to call setContent. If activity-compose was built for a different Compose version, you get crashes like NoSuchMethodError at runtime. So align activity-compose with the Jetpack Compose version that Compose Multiplatform uses—there’s a compatibility table in the docs. Also keep the Compose Compiler plugin version in sync with your Kotlin Multiplatform plugin. When in doubt, check the Compose Multiplatform and AGP compatibility pages before you upgrade. That habit pays off.

A few other things help in practice. If you’re starting fresh, use the AGP 9 structure from day one. Migrating an old single-module app to the new structure works, but it’s more work. And expect / actual is your friend: put every platform quirk behind an expect declaration, implement it per platform, and document the odd ones—like doInitKoin on iOS—so your future self or your team don’t “fix” what isn’t broken. That keeps the shared code clean and the architecture solid.

To recap: the story—where Jetpack came from, the jungle of 130+ artifacts, the Golden Path map, and that it all runs beyond Android. The lineup—Compose Multiplatform, ViewModel, Navigation, Room, DataStore—all available in KMP. How it fits together: one shared module, thin platform shells, entry points, dependency injection. And the AGP 9 structure in a real project, CMP Unit Converter—one codebase, multiple binaries.

A few topics were left out of this overview. For example, testing: your shared module is highly testable. ViewModels, repositories, use cases—you can run them in commonTest or on the JVM. Room works with an in-memory database; same DAOs and entities. For expect/actual you supply test implementations. The Kotlin and Android docs and the CMP Unit Converter repo show how. Version alignment was mentioned above: when you upgrade, align activity-compose with the Compose version your shared module uses, and check the compatibility pages. And what's not in KMP yet: WorkManager, CameraX, a few others. For those you stay in the Android app module or look for community options. The stack we focused on is the part that's officially supported and where you'll spend most of your time.

Where is this going? Google and JetBrains are actively moving Jetpack beyond Android. We're not there yet for every library, but the trend is clear: the same APIs you use on Android are being made available in KMP. The Golden Path stack we've talked about is at the front of that wave. So investing in this architecture now—Compose, ViewModel, Navigation, Room, DataStore—is not a bet on a niche. It's aligning with where the ecosystem is headed. One architecture, many platforms.

For your own projects, here's a practical checklist. UI: Compose Multiplatform. State: ViewModel and Lifecycle Runtime in KMP. Navigation: Navigation Compose in KMP. Persistence: Room and DataStore in KMP. Structure: one shared module, thin Android, iOS, and Desktop apps—and if you're on Android, use the AGP 9 layout with the new KMP library plugin. Dependency injection: Koin or Hilt, init once at app startup on each platform. Stick to this stack and you avoid the jungle. You get one architecture that runs everywhere.

For more detail, the Kotlin and Compose Multiplatform docs on kotlinlang.org and jetbrains.com are the place to start. For the Android side—the new KMP library plugin, AGP 9, and the migration steps—developer.android.com has the official guides. The Compose Multiplatform compatibility page tells you which Jetpack Compose version lines up with which CMP version. When in doubt, check it before you upgrade—it saves head-scratching. And there are samples: CMP Unit Converter is one; the Kotlin and Android teams publish more. You're not on your own—the docs and the samples are there to back you up.

Setting up local Codeberg runners

Thomas Künneth — Mon, 02 Mar 2026 18:29:02 +0000

In my previous article, First steps towards Codeberg, we looked at how to get set up and comfortable on the platform. Now that your code has a new home, it’s time to level up your workflow with automation.

While Codeberg provides shared runners for CI/CD, there are plenty of reasons to run your own, among others,

performance
specific hardware requirements
avoiding queue times

In this guide , I'll show you how to use your local machine as a CI/CD runner for Codeberg. This works behind firewalls and home routers without needing to expose your IP address. Sounds cool, right?

Depending on your needs, you can choose between two setup methods: the containerized approach using Docker / OrbStack, or running the act_runner binary directly. Since I am on a Mac with Apple Silicon, the choice actually matters quite a bit. Docker on M-series chips runs Linux ARM64 images, and unfortunately, the standard Android build tools don't officially support that environment yet. If you are here for Android builds, you might want to look at the binary method; otherwise, Docker is a safe bet.

First, get your registration token.

On Codeberg, navigate to Settings > Actions > Runners
Click Create new runner
Copy the Registration Token

Next, prepare the workspace.

Docker / OrbStack

Open your terminal and create a folder to house the runner's identity and configuration.

mkdir codeberg-runner
cd codeberg-runner

After that, create the configuration by putting a file named docker-compose.yml in that folder:

code docker-compose.yml

Here's how that file should look like. Replace <TOKEN> and <name-of-your-runner> with your registration token and a name for your runner. <name-of-your-runner> will appear in the Codeberg dashboard.

services:
  runner:
    image: gitea/act_runner:latest
    container_name: codeberg_runner
    restart: always
    environment:
      - GITEA_INSTANCE_URL=https://codeberg.org
      - GITEA_RUNNER_REGISTRATION_TOKEN=<TOKEN>
      - GITEA_RUNNER_NAME=<name-of-your-runner>
      - ACT_RUNNER_DEFAULT_IMAGE=gitea/runner-images:ubuntu-22.04
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/data
    command: daemon

Now we can launch and register our runner. Run the following command from inside the codeberg-runner folder. This will pull the image, register the runner automatically, and start the background service.

docker compose up -d

To verify the connection you can check the logs to ensure the registration was successful.

docker logs codeberg_runner

You should see Starting runner daemon.

You'll also see your runner in the Codeberg settings.

Once the initial setup is complete, use these commands to control your runner:

Action	Command	Result
Go Offline	`docker compose stop`	Safely pauses the runner; it will show as "Offline" on Codeberg
Go Online	`docker compose start`	Reconnects to Codeberg; the runner will show as "Idle" (ready)
View Live Logs	`docker compose logs -f`	Streams the activity; you'll see jobs being picked up in real-time.
Check Identity	`ls -la ./data`	Verifies the `.runner` file exists (your runner's "ID card")

That's it. Your Docker-based runner is now active and polling for jobs. To use it, you simply need to update your workflow file (usually in .gitea/workflows/) to target this specific runner.

jobs:
  test:
    runs-on: blackmac-runner
    steps:
      - run: echo "Hello from my local runner!"

In the next section, I'll show you an alternative method. act_runner is the lightweight binary that powers the Docker image we just used. By configuring it with a host label, we can run jobs directly on your machine without a container layer. This allows the runner to access your local tools (for example, Xcode or the Android SDK) directly. As mentioned earlier, this is the preferred method if you need to break out of the container's isolation or are dealing with architecture-specific limitations on Apple Silicon.

act_runner

First, let's install act_runner. We will also install node, which is required to run standard actions (like actions/checkout) directly on the host machine.

brew install act_runner node

Next, generate the default configuration file so we can customize the runner settings.

mkdir -p ~/.config/act_runner
act_runner generate-config > ~/.config/act_runner/config.yaml

Open ~/.config/act_runner/config.yaml and locate the runner section. Add your custom label ending in :host to ensure jobs run directly on your machine:

 runner:
   labels:
     - "blackmac-runner:host"

Now we can register the runner. Replace YOUR_REGISTRATION_TOKEN with the one you obtained from the Codeberg settings earlier. This command links your local machine to the instance using the configuration and label we just defined.

act_runner register --no-interactive \
  --instance https://codeberg.org \
  --token YOUR_REGISTRATION_TOKEN \
  --name blackmac-runner \
  --labels blackmac-runner:host \
  --config ~/.config/act_runner/config.yaml

Finally, start the runner daemon. It will connect to Codeberg and immediately begin listening for incoming jobs.

act_runner daemon --config ~/.config/act_runner/config.yaml

And we are live! The daemon is now connected to Codeberg and listening for jobs. To use it, simply reference the label we just registered (blackmac-runner) in your workflow file, exactly as shown earlier. The key difference here is that your jobs will now execute directly on your Mac's host system, bypassing the container layer and giving you full access to local tools like Xcode or the Android SDK.

F-Droid on ChromeOS: trying to get behind the road blocks

Thomas Künneth — Fri, 09 Jan 2026 12:43:52 +0000

F-Droid has been a trusted source for high-quality open-source Android apps for many years. While ChromeOS devices come with Google Play (provided it is enabled in Settings), also having F-Droid available offers a gateway to a vast ecosystem of privacy-respecting software.

F-Droid is not available on Google Play. Instead, you usually download it directly from the official project homepage at f-droid.org.

Once the download is complete, your first instinct would likely be to open the APK file using the Files app:

Unfortunately this would give you just a message saying Turn on Chrome OS Developer mode to install apps from sources other than the Play Store.

That sounds scary, doesn't it? What's more, it's simply not true. You do not need to enable the full-fledged Developer Mode, which in itself may open up more severe security issues. Instead, you can simply enable ADB debugging. You’ll find this toggle in Settings under the Develop Android apps section.

Once ADB debugging is toggled and an APK has been downloaded, a simple adb install triggers the installation. Let's use the internal Linux container (Crostini) to do so.

First, open your Chrome OS Terminal and install a few required tools

sudo apt update && sudo apt install android-tools-adb curl -y

Next, connect the Linux container to the Android subsystem

adb connect 100.115.92.2:5555

After running the adb connect command, keep your eyes on the Chromebook screen. You may need to manually authorize the debugging link and confirm the installation.

Finally, use curl to grab the latest version of F-Droid and install it

curl -L https://f-droid.org/F-Droid.apk -o fdroid.apk && adb install fdroid.apk

Once we have opened F-Droid, we can browse the catalogue. However, trying to install an app, shows an error saying we need to enable Developer mode.

Wait a minute. There's something in Settings, right?

Yes, Install unknown apps.

Unfortunately, enabling this does not change anything. What's more, trying to grant the permission on the command line gives us a little bit of an explanation.

adb shell pm grant org.fdroid.fdroid android.permission.REQUEST_INSTALL_PACKAGES

Conclusion

So, what can we make out of this? Well, this article clarifies that you do not need to bring your ChromeOS device into Developer mode to install Android apps (I guess most of us knew that 😅); even though Google tries hard to persuade you otherwise.

Next. Switching on developer mode is usually a bad idea. So, why does Google stick to it? Well, while I can certainly only speculate, tying the users to Google Play is in the interest of Google, whereas allowing alternative app stores definitely is not. We see the hesitation on plain Android - it took law suits and a lot of developer backlash to force Google into making the installation of Play Store alternatives less painful. And it will take Android 17.

Regarding ChromeOS, having apps download and install other apps seems, at least for now, impossible to do for ordinary users.

One final thought. Since F-Droid has been the hook for this article, I feel the need to praise them to as much extent as I possibly can. They continue to be a landmark institution for Android open source software since many years. It's certainly not their fault that they can't easily be used on ChromeOS.

First steps towards Codeberg

Thomas Künneth — Wed, 31 Dec 2025 11:43:33 +0000

A lot of Europeans are currently talking about Europe having to become more independent from US-based big tech. Being a European myself, I feel the need for this, too. However, just talking won't make a difference. So, why not make this our New Year's resolution? Here's mine: I love open source. Given GitHub's recent trajectory toward centralisation, I feel there are better-suited homes for my repositories. That's why I will start migrating them to Codeberg.

What is Codeberg?

Codeberg is a community-driven non-profit platform for hosting software projects. Many consider it the leading independent alternative to commercial services like GitHub and Bitbucket. While it looks and feels very similar to GitHub, its underlying philosophy and legal structure are fundamentally different: unlike GitHub, which is owned by Microsoft, Codeberg is run by a German non-profit organisation called Codeberg e.V.. It is funded by donations rather than venture capital or ads. The platform runs on Forgejo, which is a community-governed fork of Gitea. Therefore, the very software used to run the site is itself open source and transparent. And it is privacy-focused. Since Codeberg is hosted in the European Union (Germany), it adheres to strict GDPR standards. It does not track users for advertising and avoids black box AI features like GitHub Copilot.

Does this sound appealing? To me it certainly did. That's why I decided to jump right in. In this introductory article, I'll show you my first baby steps, that is, registering and migrating the first GitHub repository.

Signing up

Registering is a very quick and pleasant experience. Visit https://codeberg.org, find and click the Register button.

Just enter a username, your email address, a password, and the randomly generated number or word.

Once you click on Register Account, you should receive an email with the inevitable confirmation link.

Click on the link to verify your email address. You will be directed to your personal Codeberg landing page.

Next, you may want to update some settings.

While I won't walk you through the settings, I would like to encourage you to show your Codeberg account on Mastodon. First, add Mastodon to Codeberg. Look for the Website field or the Social Accounts section (if available in the current UI). Paste your full Mastodon profile URL (for example, https://mastodon.social/@tkuenneth) and click Update Profile at the bottom. Codeberg automatically adds the rel="me" attribute to the website link in your profile, which is exactly what Mastodon needs to verify you.

Next, open your Mastodon instance and visit your Profile page. Click Edit profile and find the Extra fields in Basic information. This is where you add labels and links. In the label column, type something like Codeberg. In the content column, paste your Codeberg profile URL (e.g., https://codeberg.org/tkuenneth).

Click Save Changes. It may take a short while until Mastodon detects that it's you, but in the end, it should look like this:

Migrating your first repository

To start a migration, click on the + symbol on the top right, and select New migration.

The next step is to select the Git host you want to migrate from. The migration tool can migrate your repository data, as well as metadata like issues, labels, wiki, releases, and milestones.

The most important piece of information is, of course, the url of the repository you want to migrate. To be able to also migrate metadata, you need to provide an access token.

Once you have specified the owner, the repository name, and the visibility, you can start the migration by clicking on Migrate repository. The following screenshot shows a freshly migrated repo.

Finalising the migration

Once the new repository has been set up, you may want to update the README of the old repo by mentioning its new home and then archive the content (on GitHub, this makes it read-only).

I strongly advise against deleting the old repo. It’s tempting to want a clean break, but there are two big reasons to keep it:

Broken Links: There are inevitably links to your code scattered across the web—in blog posts, old commits, or bookmarks—which you would render useless.
Security (Namespace Hijacking): This is a risk many people overlook. If you delete a repository, that specific URL becomes available again. Someone else could potentially register that same name and host malicious code where your project used to be. By keeping your old repository as a placeholder or a tombstone, you ensure that you still control that space and can point your users safely to Codeberg.

So, the best move is to add a clear migration notice to the top of the README, set the repository to Archived, and let it serve as a signpost.

To learn more about migrations to Codeberg, read the official guide at https://docs.codeberg.org/advanced/migrating-repos/.

Some thoughts on keyboard shortcuts on Android

Thomas Künneth — Fri, 01 Aug 2025 12:30:23 +0000

When you think about which cool new feature you may want to add to your app, you probably won't immediately shout Hell yes, my app desperately needs keyboard shortcut support. I mean, how often do we use physical keyboards with our mobile devices anyway? The days of Android phones having a keyboard built in are long gone, aren't they?

Well, not really. Chromebooks run Android apps. Many Android tablets are sold with physical keyboards. And Android's desktop mode, which hopefully will gain some traction eventually, allows us to connect our smartphone to big screens. This setup only makes sense when you also pair a mouse and keyboard. So, keyboards most certainly are not a thing of the past. They may not have been very common on Android in recent years, but other platforms have always relied on them. And still do. Why? Because physical keyboards are productivity boosters.

That's where keyboard shortcuts come in. They allow us to trigger an action by simultaneously pressing a few keys. Prime examples are the clipboard-related commands Cut (Control-X), Copy (Control-C), and Paste (Control-V). And yes, it's Command on the Mac.

Have you noticed that I said command? Keyboard shortcuts allow us to trigger an action or command fast. That's why they are called shortcuts. The important point here is: there should always be another way of executing that command. Typically, this other way also advertises the corresponding keyboard shortcut. Take a look:

When we open a menu, we see the command and its associated shortcut, which helps us remember it (eventually). Actually using the shortcut helps us remember it even better, but that's another topic.

But Android doesn't have a menu bar

Traditional menu bars work best with a mouse and a mouse pointer. That's why Android does not have one. However, Android most certainly allows apps to show menus. And these can contain keyboard shortcuts, too. We'll tackle this shortly. But first, let me show you how to define and consume keyboard shortcuts on an app level. The source code of my sample app KeyboardShortcutDemo is available on GitHub. It is a Compose Multiplatform project that targets Android, IOS, and the Desktop. In this article, I focus on Android.

Global shortcuts

Working with global keyboard shortcuts consists of two steps:

Defining the shortcuts
Receiving shortcut activations

Both can be implemented on an Activity level. Here's how to define a keyboard shortcut:

private lateinit var listKeyboardShortcutInfo: List<KeyboardShortcutInfo>

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    listKeyboardShortcutInfo = globalShortcuts.map { shortcut ->
        KeyboardShortcutInfo(
            shortcut.label,
            shortcut.keyAsString.first(),
            shortcut.modifiers()
        )
    }
    …
    setContent {
        val hardKeyboardHidden by
                hardKeyboardHiddenFlow.collectAsStateWithLifecycle()
        val systemInDarkMode = isSystemInDarkTheme()
        var darkMode by rememberSaveable {
                mutableStateOf(systemInDarkMode)
        }
        MaterialTheme(colorScheme = if (darkMode)
                            darkColorScheme()
                        else
                            lightColorScheme()) {
            MainScreen(
                listKeyboardShortcuts = globalShortcuts,
                hardKeyboardHidden = hardKeyboardHidden ==
                    Configuration.HARDKEYBOARDHIDDEN_YES,
                darkMode = darkMode,
                showKeyboardShortcuts = {
                    requestShowKeyboardShortcuts()
                },
                toggleDarkMode = { darkMode = !darkMode }
            )
        }
    }
}

override fun onProvideKeyboardShortcuts(
    data: MutableList<KeyboardShortcutGroup>,
    menu: Menu?,
    deviceId: Int
) {
    super.onProvideKeyboardShortcuts(data, menu, deviceId)
    data.add(KeyboardShortcutGroup(
        getString(R.string.general), listKeyboardShortcutInfo)
    )
}

In onCreate(), we populate a list of KeyboardShortcutInfo instances and, inside onProvideKeyboardShortcuts(), add it to data, which has been passed to us by Android. Please notice the Menu which will usually be null in a Compose-only app.

But what is globalShortcuts? It's defined in GlobalShortcuts.kt.

val globalShortcuts = runBlocking {
    listOf(
        KeyboardShortcut(
            label = getString(Res.string.say_hello),
            key = Key.H,
            keyAsString = "H",
            ctrl = true
        )
    )
}

KeyboardShortcut is a cross-platform generalisation of KeyboardShortcutInfo, which I defined to be able to refer to keyboard shortcuts beyond Android activities. Have you spotted that I pass globalShortcuts to MainScreen()?

Next, let's look at how to receive keyboard shortcut presses.

override fun onKeyShortcut(
    keyCode: Int, event: KeyEvent
): Boolean {
    listKeyboardShortcutInfo.forEachIndexed { index, info ->
        if (info.keycode == keyCode &&
            event.hasModifiers(info.modifiers)) {
            globalShortcuts[index].triggerAction()
            return true
        }
    }
    return super.onKeyShortcut(keyCode, event)
}

The onKeyShortcut() function receives a keyCode and an event. Using both, it is simple to check if a shortcut defined by our app has been pressed. If this is the case, we return true, otherwise super.onKeyShortcut(keyCode, event).

But what does shortcut.triggerAction() do? Here's how it is implemented:

data class KeyboardShortcut(
    val label: String,
    val key: Key,
    val keyAsString: String,
    val ctrl: Boolean = false,
    val meta: Boolean = false,
    val alt: Boolean = false,
    val shift: Boolean = false,
) {
    private val channel = Channel<Unit>(Channel.CONFLATED)
    val flow = channel.receiveAsFlow()

    fun triggerAction() {
        channel.trySend(Unit)
    }

    val shortcutAsText: String
        get() {
            val parts = mutableListOf<String>()
            if (ctrl) {
                parts.add("Ctrl")
            }
            if (meta) {
                parts.add("Meta")
            }
            if (alt) {
                parts.add("Alt")
            }
            if (shift) {
                parts.add("Shift")
            }
            parts.add(keyAsString)
            return parts.joinToString("+")
        }
}

Since KeyboardShortcutInfo is specific to Android, it makes sense to provide an alternative that we can use across platforms. But even on Android we need a mechanism that allows us to trigger and consume keyboard shortcuts in a modern Kotlin way.

That's what KeyboardShortcut is for. label and shortcutAsText will be used by composables. flow allows us to react upon invocations of the keyboard shortcut. Finally, triggerAction(): as its name implies, it triggers an action by trying to send something to a channel. Kindly recall that we invoke this function inside onKeyShortcut(). What does this mean? Once we have determined that a keyboard shortcut has been invoked by pressing the corresponding keys, we make sure to notify everyone interested in the event. We'll, by the way, also call this function from inside our Compose hierarchy. I'll show you shortly.

But before that, let's take a user's perspective. Android and Chrome OS can display a list of available shortcuts. On most devices, this help screen can be opened by pressing Meta-/, which is known as Search-/ on Chromebooks.

Since not all users may be familiar with this system shortcut, consider allowing the user to summon it from within your app. Kindly recall what my sample app does inside setContent {}:

setContent {
    …
    MaterialTheme(colorScheme = …) {
        MainScreen(
            listKeyboardShortcuts = globalShortcuts,
            hardKeyboardHidden = …,
            darkMode = darkMode,
            showKeyboardShortcuts = {
                requestShowKeyboardShortcuts()
            },
            …
        )
    }
}

requestShowKeyboardShortcuts() (this method is defined in android.app.Activity) requests the Keyboard Shortcuts screen to show up. This will trigger onProvideKeyboardShortcuts() to retrieve the shortcuts for the foreground activity. KeyboardShortcutDemo just shows a Show keyboard shortcuts button. Certainly, there are more clever places to incorporate it.

Let's recap. I showed you how to provide keyboard shortcuts on an Activity level. We can even summon a system dialog that lists them. But how do we react to shortcut presses and how do we visualise the shortcut in our user interface? Finally, how do we mention the shortcut to the user so that they can remember it, similar to what I explained regarding classic menu bars?

@Composable
fun MainScreen(
    listKeyboardShortcuts: List<KeyboardShortcut>,
    hardKeyboardHidden: Boolean,
    darkMode: Boolean,
    showKeyboardShortcuts: () -> Unit,
    toggleDarkMode: () -> Unit,
) {
    var snackbarMessage by remember { mutableStateOf("") }
    val helloMessage = stringResource(Res.string.hello)
    LaunchedEffect(listKeyboardShortcuts) {
        listKeyboardShortcuts.forEach { shortcut ->
            launch {
                shortcut.flow.collectLatest {
                    snackbarMessage = helloMessage
                }
            }
        }
    }
    KeyboardShortcutDemo(
        hardwareKeyboardHidden = hardKeyboardHidden,
        snackbarMessage = snackbarMessage,
        shortcuts = listKeyboardShortcuts,
        darkMode = darkMode,
        showKeyboardShortcuts = showKeyboardShortcuts,
        clearSnackbarMessage = { snackbarMessage = "" },
        toggleDarkMode = toggleDarkMode,
    )
}

When a keyboard shortcut is invoked, the sample app shows a snackbar message. We keep the text in snackbarMessage. listKeyboardShortcuts is the list of keyboard shortcuts. KeyboardShortcutDemo() (this composable is invoked from MainScreen()) uses it to populate a menu. hardKeyboardHidden is used to determine if a physical keyboard is ready to use. Kindly just ignore it, I will detail on this in a follow-up article.

So far, I still haven't explained how we react to shortcut presses. The magic happens inside LaunchedEffect(). For each keyboard shortcut, we invoke shortcut.flow.collectLatest {}. In my example, we always set the snackbar message. Real-world apps would certainly provide different implementations, depending on the shortcut.

Menus and keyboard shortcuts in Jetpack Compose

When looking at the KeyboardShortcutDemo() composable, kindly recall the screenshot of the app to understand its structure:

an app bar at the top, including the app name and a menu
a text field (not further discussed in this article)
a switch with an accompanying label (not further discussed in this article)
a button to open the keyboard shortcuts dialog
(not visible in the screenshot) a text when no physical keyboard is ready to use

fun KeyboardShortcutDemo(
    hardwareKeyboardHidden: Boolean,
    shortcuts: List<KeyboardShortcut>,
    snackbarMessage: String,
    darkMode: Boolean,
    showKeyboardShortcuts: () -> Unit,
    clearSnackbarMessage: () -> Unit,
    toggleDarkMode: () -> Unit,
) {
    val snackBarHostState = remember { SnackbarHostState() }
    var showMenu by remember { mutableStateOf(false) }
    …
    Scaffold(
        modifier = Modifier.fillMaxSize()
        …,
        topBar = {
            TopAppBar(
                title = {
                    Text(stringResource(Res.string.app_name)) 
                },
                actions = {
                    IconButton(onClick = { showMenu = !showMenu }) {
                        Icon(
                            imageVector = Icons.Filled.MoreVert,
                            contentDescription = stringResource(
                                Res.string.more_options)
                        )
                    }
                    DropdownMenu(
                        expanded = showMenu,
                        onDismissRequest = { showMenu = false }
                    ) {
                        shortcuts.forEach { shortcut ->
                            DropdownMenuItemWithShortcut(
                                text = shortcut.label,
                                shortcut = shortcut.shortcutAsText,
                                onClick = {
                                    showMenu = false
                                    shortcut.triggerAction()
                                }
                            )
                        }
                    }
                }
            )
        },
        snackbarHost = { SnackbarHost(snackBarHostState) }
    ) { innerPadding ->
        Box(
            modifier = Modifier
                …
                .padding(innerPadding)
                .fillMaxSize(),
            contentAlignment = Alignment.Center
        ) {
            …
            Column(
                horizontalAlignment = Alignment.CenterHorizontally,
                verticalArrangement = Arrangement.spacedBy(16.dp)
            ) {
                …
                Button(
                    onClick = showKeyboardShortcuts,
                ) {
                    TextWithUnderlinedChar(stringResource(
                        Res.string.show_keyboard_shortcuts))
                }
            }
            if (hardwareKeyboardHidden) {
                Text(
                    text = stringResource(
                        Res.string.hardware_keyboard_hidden),
                    modifier = Modifier.align(Alignment.BottomCenter)
                                       .safeContentPadding(),
                    style = MaterialTheme.typography.headlineSmall,
                    color = MaterialTheme.colorScheme.error
                )
            }
        }
        LaunchedEffect(snackbarMessage) {
            if (snackbarMessage.isNotBlank()) {
                snackBarHostState.showSnackbar(snackbarMessage)
                clearSnackbarMessage()
            }
        }
    }
}

The menu will contain as many items as shortcuts has elements. When an element is selected, a snack bar will appear. That's because onClick() of each DropdownMenuItemWithShortcut() invokes shortcut.triggerAction(). The onClick() of the button just invokes the showKeyboardShortcuts lambda.

That's been quite a bit to digest, right? Fortunately, there is only one piece of the puzzle missing. What is DropdownMenuItemWithShortcut()?

Unlike the traditional Activity-level options menu, DropDownMenuItem() (which comes with Jetpack Compose) does not support shortcuts out of the box. This means we need to somehow add this to the Text() composable. The most basic approach is to just add the shortcut at the end of the String. While this works, this does not look particularly pleasing. Besides, that's not how we build UIs with Jetpack Compose.

Here's a composable that provides a DropDownMenuItem() with a shortcut at the end of the text:

@Composable
fun DropdownMenuItemWithShortcut(
    text: String,
    shortcut: String?,
    onClick: () -> Unit,
    modifier: Modifier = Modifier
) {
    DropdownMenuItem(
        text = { ShortcutText(text = text, shortcut = shortcut) },
        onClick = onClick,
        modifier = modifier
    )
}

@Composable
fun ShortcutText(
    text: String,
    shortcut: String?,
) {
    Row(
        modifier = Modifier.fillMaxWidth(),
        horizontalArrangement = Arrangement.SpaceBetween
    ) {
        Text(
            text = text,
            modifier = Modifier.alignByBaseline()
        )
        shortcut?.let { shortcut ->
            Text(
                text = shortcut,
                style = MaterialTheme.typography.bodyMedium,
                color = MaterialTheme.colorScheme.onSurface
                            .copy(alpha = 0.6f),
                modifier = Modifier
                    .alignByBaseline()
                    .padding(start = 16.dp)
            )
        }
    }
}

Have you spotted the alignByBaseline() modifier? While most examples using Row() just vertically center the children, this is a nightmare from a UX perspective. The texts have to be baseline-aligned to be readable nicely.

That looks pretty nice, doesn't it?

You may be wondering where the shortcut text is created. In the KeyboardShortcutDemo() composable, it's passed like this:

shortcuts.forEach { shortcut ->
    DropdownMenuItemWithShortcut(
        text = shortcut.label,
        shortcut = shortcut.shortcutAsText,
        onClick = {
            showMenu = false
            shortcut.triggerAction()
        }
    )
}

So, what is shortcut.shortcutAsText? Kindly recall my custom KeyboardShortcut class:

data class KeyboardShortcut(
    val label: String,
    val key: Key,
    val keyAsString: String,
    val ctrl: Boolean = false,
    val meta: Boolean = false,
    val alt: Boolean = false,
    val shift: Boolean = false,
) {
    …

    val shortcutAsText: String
        get() {
            val parts = mutableListOf<String>()
            if (ctrl) {
                parts.add("Ctrl")
            }
            if (meta) {
                parts.add("Meta")
            }
            if (alt) {
                parts.add("Alt")
            }
            if (shift) {
                parts.add("Shift")
            }
            parts.add(keyAsString)
            return parts.joinToString("+")
        }
}

I was surprised to learn that there seems to be no public-facing API in Android that provides a locale-aware String representation of KeyboardShortcutInfo. However, a function that achieves this must be around somewhere, since the often-mentioned keyboard shortcuts dialog needs something similar, too. Since I couldn't find one, I decided to write my own. Checking the modifiers and the key code isn't too difficult, but there are some nuances that need to be taken into account. For example, on Chromebooks, Meta should be Search or some corresponding symbol. I omitted this for brevity. In a real-world app, you would want to take the string from the resources and handle device-specific variations.

Conclusion

Adding keyboard shortcut support to your app may not sound particularly fancy at first sight, but in my opinion brings a lot of added value. Do your apps already support them? How did you handle the visual representation of the shortcuts? Please share your thoughts in the comments.

Quick tip: (sort of) using Quick Share on macOS

Thomas Künneth — Thu, 19 Jun 2025 10:32:45 +0000

At the time of writing this article, there (still) is no official Quick Share implementation for macOS. While there is an open source app that partially implements the underlying protocol, and while there certainly are quite a few excellent alternate file sharing solutions, you still may want (or have) to rely on Google's version.

The Windows version obviously won't work on your Mac, but it may very well work inside a virtualized Windows guest.

So what is happening there? I am using Parallels Desktop, which allows you to run an authorized (that is, licensed and activated) version of Windows 11 for ARM. Having a Windows environment available on your Mac may come in handy for several reasons. My personal favorites are:

testing Compose Desktop apps
occasionally play some PC-only games
use apps that are not available natively on macOS, which, at the time of writing, was the case for Quick Share

Testing Compose Desktop apps has been a game changer for me, and I will be writing about this, too. For now, let's focus on Quick Share. And virtualization. But first, a short disclaimer. I am not advocating a specific product. There are several virtualization packages on macOS. And they all have their strengths. It just happened that I once tried Parallels and liked it, so I stayed. But what I am going to describe, will likely be working on other products, too.

Before Apple switched to Apple Silicon, Macs were powered by Intel chips. Well, and before that, still others. Anyway, when a virtualization software virtualizes an environment with the same processor architecture, there, inevitably, is less emulation needed than when it also needs to simulate the processor. Those packages still have to do crazy, mind-blowing stuff. But a lot of code can run natively, given that the underlying processor supports virtualization. This is the case for modern Intel and AMD chips. However, current Apple Silicon chips have only limited support for running virtualized Intel/AMD operating systems. While Apple does provide a virtualization layer called Rosetta 2, running an x86/x64 version of Windows is - at the time of writing - not easily possible. That's why Parallels relies on Windows for ARM. This version is usually run on ARM-PCs. Now, you may be thinking: What about software compatibility? Windows for ARM has its own emulation layer, which allows users to run many x86/x64 programs.

Let's turn to Quick Share. The official Google Quick Share application for Windows is compatible with 64-bit versions of Windows 10 and up. Importantly, it also supports ARM-based PCs running Windows 11 and up. Since Quick Share leverages both Bluetooth and Wi-Fi for file transfer, you'll need to ensure both are enabled and working on your virtualized Windows PC and the Android device.

Using Parallels, Bluetooth is activated from the menu bar (Devices / USB & Bluetooth / Configure).

Next, check if Bluetooth is enabled and if your virtual machine is discoverable.

Wi-Fi required a little more thought to make Quick Share work. Specifically, the Network settings should look like this:

Source needs to be set to Wi-Fi rather than Shared Network, which is the default and recommended setting.

While that's basically it, let me show you a few screenshots from the Windows app:

In its settings, you can specify where received files are saved. Since you can share macOS folders with the virtual Windows, it may sound like a good idea to use such folders. Unfortunately, this did not work for me. While the file was briefly visible, it vanished shortly after. Using a folder inside the Windows guest fortunately works like a charm.

In the main section, you can easily change who can send you files. If the main window is closed, this setting is also available from the system tray:

Wrap-up

I have an instance of Windows basically running all the time, since I do a lot of Compose Multiplatform / Compose Desktop coding. No, it's not because of games 🤣. Anyway, for my setup, receiving Quick Share files there and moving them to native Mac folders manually is a decent enough workflow to keep it. Granted, a native macOS version is still overdue. At least, Google could fix the "not being able to save files in networked folders" issue.

What are your thoughts on this? Please share them in the comments.

Did you know … ? Android 16 edition

Thomas Künneth — Sun, 08 Jun 2025 19:30:33 +0000

The rollout of Android 16 is likely going to happen today (while today certainly depends on your time zone 😅). In anticipation of the new release, I made a series of social media posts highlighting changes and additions that may not make it to the front page. Here's a quick collection of these posts.

DEV Community: Thomas Künneth

Adaptable apps on ChromeOS: a post-mortem

What users see

What I started with

What I tried

Time to recap

References

Building a custom launcher for ChromeOS

About wallpapers

Wrap-up

Bubble up - Android 17's new multitasking feature explained

(Chat) Bubbles

A Glimpse Behind the Curtain

The Secondary Display Pitfall

Managing the Task Lifecycle

Wrap-up

Agentic interaction using AppFunctions

AppFunctions

Implementing an AppFunction

Version catalog (gradle/libs.versions.toml)

App module (app/build.gradle.kts)

Testing AppFunctions

Wrap-up

References

From Vibe-Coding to Reality: Building MarvinSync

What is MarvinSync? (And why Vibe-Code it?)

Trusting the folder, not the tag

Making Android Feel Native

What the code fences don’t show (but the session did)

The Friction of Vibe-Coding

What’s Next?

Refuelling your Jetpack

From Jetpack to a unified architecture

How it fits together

In practice: CMP Unit Converter

Takeaways and resources

Setting up local Codeberg runners

Docker / OrbStack

act_runner

F-Droid on ChromeOS: trying to get behind the road blocks

Conclusion

First steps towards Codeberg

What is Codeberg?

Signing up

Migrating your first repository

Finalising the migration

Some thoughts on keyboard shortcuts on Android

Global shortcuts

Menus and keyboard shortcuts in Jetpack Compose

Conclusion

Quick tip: (sort of) using Quick Share on macOS

Wrap-up

Did you know … ? Android 16 edition

7 new services

Ignoring rotation and resizability change restrictions

Embedding the Android Photo Picker

A hint at virtual threads

Supplemental descriptions for views

New key codes

Elegant font APIs deprecated and disabled

Good vibrations

NoWritingToolsSpan

Version catalog (`gradle/libs.versions.toml`)

App module (`app/build.gradle.kts`)