The title was blunt: native is now the future of mobile at Shopify.

Six years ago they went all-in on React Native. Last January, Ali wrote a retrospective saying RN had a bright future. Now they are reversing course, and the stated reason is one thing: coding agents have crushed the cost of writing everything twice.

The switch worked out. Six engineers took Shop App from proof of concept to the app store in 12 weeks. iOS cold start improved 23%, Android 50%.

But the most valuable line in that post is not a number.

Ali writes that an agent can rewrite the code in seconds, then spend minutes working out whether it actually works. Simulator control is too slow, so getting state means going through the accessibility tree or taking screenshots.

His words: if the model cannot quickly verify its own work, it does not matter how good the model is.

That complaint made me read two posts side by side. The Shopify piece from September 10 and the Flutter team’s response forty days later are arguing about the same thing.

The bottleneck is not generation, it is verification

The Flutter post went up on October 20, by Carlos Mendonça and Emma Twersky. Its title is just as blunt: AI makes it easy to migrate, Flutter makes it easy to scale. It exists to answer the question Shopify threw down.

The whole piece rests on one claim. Code generation stopped being the bottleneck a while ago. Verification is the bottleneck now.

Two numbers back it up. 73% of developers say AI makes them more productive when starting a task. 46% do not trust AI’s debugging accuracy without a human checking it.

Squeeze from both sides and the blocker sits on the human side.

The bill for three steps

The team published a comparison table putting native and Flutter next to each other across the three verification steps.

Code-to-running latency: native takes 2 to 5 minutes per cycle. Build, link, archive, install on the simulator. Four debug rounds burn twenty-odd minutes.

Flutter stays under 200 milliseconds. Hot reload injects the change into a running Dart VM and keeps state.

Automated tests: native walks the full simulator lifecycle and a background emulator. Flutter’s headless widget tests run in an isolated environment in under 500 milliseconds.

The UI and state-check row is where it gets interesting.

Native screenshots the simulator and hands the image to a vision model to guess at the layout. Probabilistic, and slow. Flutter goes through MCP to query the Dart VM Service and DevTools, reading the widget and render object trees directly. Deterministic, structured.

Chain the three and you have a complete loop. Every step queues on the native side. On Flutter a round trip is milliseconds.

Harness beats prompt

Fast verification is one thing. Getting the agent to actually use it is another. The team ran an internal experiment called Project One Shot, letting an agent fix a production bug in camera_android_camerax on its own.

The plugin manages Android CameraX lifecycles and surface texture binding, the hairiest kind of Flutter code there is.

Given vague instructions like watch out for memory leaks, the agent failed every time.

It only worked with a deterministic harness. AST analysis over MCP, package-level domain skills, enforced test-driven guardrails. Reproduce with a failing test, write the smallest fix, finish with the full test suite and leak checks.

No room for the agent to freestyle. Every step has its acceptance criteria nailed down.

Three things shipped alongside. An official Dart and Flutter agent plugin bundles an MCP server with ten Flutter and fourteen Dart skills, so the agent can reach the Dart Analyzer and Widget Inspector directly.

A dedicated agent inside Antigravity audits accessibility issues and submits fixes that match existing conventions. Plus an Agent Skills CLI built with Serverpod: one dart run skills@get installs the skills a package ships with into your agent.

The benchmark numbers: Gemini 3.5 Flash from 84.1% to 85.5%, Gemini 3.1 Pro from 89.6% to 92.7%. Modest gains, run by the team on its own eval suite.

Where this actually lands

The post lists a set of deployment targets well beyond phones. Toyota and Lexus head units, the Xiaomi SU7 center console, Nubank’s fintech app with a hundred million users, Universal Music.

The post does not push this angle. I think it is the most convincing part.

What these share is absurdly expensive verification.

Flashing a head unit takes tens of minutes. One production incident in a fintech app costs real money. Music app users tolerate zero jank.

In places like these, a minute off the verification loop is money and time you keep.

Look further out. Once agents writing code is normal, one codebase across platforms saves more than headcount. It saves time.

An agent produces a change, hot reload shows it on phone, desktop and web at once. That is an order of magnitude faster than compiling, packaging and installing per platform.

That is also why the Flutter team has been pushing into automotive, desktop and embedded.

The second half of cross-platform may not happen on phones.

A few things I do not buy

The app store rating section does not hold up. It cites Apptopia’s study of 201,000 apps. On Google Play, Flutter apps average 4.1 stars, and so do non-Flutter apps. On the App Store both sit at 4.0. The conclusion offered is that users do not care about the framework.

All that shows is that cross-platform did not hurt ratings. Flip it around and it also shows cross-platform did not help. Using a tie to argue for adoption is missing a step.

That 200 milliseconds is the time to inject a change. It excludes writing the code, thinking it through, switching windows.

It cannot change class structure either. Add a field or restructure the state tree and you need a restart.

The table measures code-to-running latency, which is an honest definition. Readers will take it as development being twenty times faster, and those are very different claims.

The enterprise examples have survivorship bias too.

Xiaomi SU7, Universal cutting 45% of its code, Toyota and Lexus, Nubank’s hundred million users. All real.

No post ever covers the company that moved to cross-platform for two years and then tore it out. Arguments from these examples are half evidence.

How to do the cross-platform math

Line up both sides first. Shopify’s call: the cost of writing twice has been crushed, and what is left is not worth giving up native capabilities for. Flutter’s call: coordination costs remain.

The example in the post is specific. Same checkout state machine, two instances of the same model. One writes Swift and drops stale events through an async stream. One writes Kotlin and queues events through a reactive flow.

Both pass local unit tests on day one. Weeks later Android checkout conversion drops three points, because under network jitter the retry timing differs.

Both positions hold. They are doing different arithmetic.

I also do not think this pivot is evidence that cross-platform is dead.

This is a company with hundreds of screens, over a thousand engineers, and mobile as a core investment. At that scale, rebuilding for 23% faster cold start and a better crash rate pencils out.

For five people maintaining a mid-sized app, the same move probably does not.

What decides whether you go cross-platform is team size, how many years you will maintain it, and how long your verification chain is. AI changes none of those.

Here is a question worth arguing about instead. If agents really do get a verification cycle down to a few hundred milliseconds, how much longer does native-feels-better hold up.

I would like to hear what is actually on your desk. Is your project single-platform, dual, or cross? What drove that call: performance, headcount, or a boss who said we are going native?

One more question: do you think Compose Multiplatform has a shot? It is cross-platform too, arrived years after Flutter, but it stands on half the Kotlin and Android ecosystem.

Drop a comment. I will pick a few representative ones and write them up as a follow-up.

Both source posts are here. Twenty minutes total.

Native is now the future of mobile at Shopify

AI makes it easy to migrate. Flutter makes it easy to scale.

The real changes are in the later sections. The publishing format changed, the compilation scheme changed, and three defaults were quietly tightened. I installed both compilers on the same machine and fed each one the same source. The results differ.

The point of this release is not syntax

Two of the four stable features are really about turning a choice into a default: the syntax-only mode for destructuring by name, and the unused return value checker. Not one line of old code needs changing. What new code can express changes.

The two experimental ones follow the same line: companion extensions and companion blocks, and full value classes. All of them remove a bit of arbitrary restriction from the language.

The language layer is the quiet part this time. Laid out properly, the substance is in the last three sections of the doc: the Kotlin Multiplatform publishing format, the new compilation scheme, and incremental compilation on Apple platforms. None of those change what you write. They change what you ship and how long it takes to build.

One .kar file replacing seven thousand

Their words:

The new format publishes platform artifacts (except for JVM and Android) as a single .kar archive, which is a ZIP archive additionally compressed with XZ.

A library supporting several targets used to publish several sets of artifacts. Now everything except JVM and Android goes into a single .kar, which is a ZIP with an extra layer of XZ on top.

The numbers are clearer than the description. Their example is cryptography-kotlin: published artifacts went from 7,539 files and 91 MB to 1,036 files and 23 MB. For the whole multi-module project.

One line to turn it on. Per module in the build script, project-wide in gradle.properties:

kotlin.publicationFormat=KOTLIN_ARCHIVE

Two caveats have to be read together. Except JVM and Android: those two ecosystems still use standard Maven artifacts. The consumer side is fully available, so when a library you depend on switches format, your build does not move. The publishing side is still experimental, so if you publish libraries yourself, verify your pipeline separately.

Why Maven Central’s limit is about file count

The notes only say Maven Central recently introduced a publishing size limit. What sits behind that sentence is more interesting than size.

What blocks library authors is not total bytes, it is file count. A library with six targets, one artifact set per target, plus source jars and metadata, lands in the thousands without trying. Every file is a separate record in the repository, a separate upload, a separate index entry. For the repository that is operational cost. For the user it is the first screen of requests during dependency resolution.

So 7,539 files down to 1,036, minus eighty-six percent, matters more than 91 MB going to 23 MB. What you save is requests and index entries, not bandwidth.

JVM and Android being excluded says something too: those two ecosystems are still anchored to standard Maven classifiers and cannot move. The real situation for cross-platform libraries is many targets, mainline platforms on the old format, everything else in an archive. That hybrid will stick around for a while.

The change is completely transparent downstream, and because it is transparent, it can be recommended to everyone. The beneficiaries are library authors and the people maintaining release pipelines, not those of us writing application code.

The new compilation scheme: common code should not quietly reach platform APIs

This section is written with restraint. Four items: make the compiler treat common source sets the same way the IDE does; prevent common code from accidentally resolving to platform-specific declarations; improve consistency of overload resolution and type inference; enable incremental compilation for common source sets.

The first three fix an old hole. One wrong import in commonMain and the IDE marks it red while the command line passes, or the reverse, and the two never agree. The cause: the IDE and the compiler each have their own resolver, each doing its own math.

Unifying them has a side effect: code that used to compile may not anymore. That is not a regression. That code was reaching symbols it should not have seen. Nobody was stopping it.

The fourth is the everyday payoff. Common code finally gets incremental compilation, and people who live in the IDE feel it most. On CI you will not notice, because the pipeline builds from scratch every time.

JetBrains wrote a dedicated post on this scheme in September, with the word reliable in the title. The problem being fixed is exactly unreliability: the IDE and the compiler reaching two different conclusions about the same common code.

The compiler got stricter: three defaults changed

The most visible one first. The same code fails to compile on 2.4.21 and passes by default on 2.5.0-Beta2:

(val mail = email, val name = username) = user

val inside the parens, an equals sign picking which property to take, and the variable name no longer has to match the property name.

An old hole while we are here. Positional destructuring like val (email, username) = user passes on both versions, but the values are assigned by position. I destructured User(username, email) into email=alice, username=alice@example.com. Every variable name wrong, and the compiler said nothing. This feature exists because of that.

Second, the unused return value checker. The same file passes silently on 2.4.21 and warns on 2.5.0-Beta2: unused return value of 'plus'. If an expression produces a non-Unit value and nobody uses it, it tells you.

Third, cross-module inlining. Optional when introduced in 2.4.0, on by default in 2.5.0-Beta2. The off switch is -Xklib-ir-inliner=disabled.

There is one more that is not a default. Type inference generates fewer constraints and no longer stalls on complex generics. The notes are restrained, saying only that it may change inference results, overload selection and diagnostics. In plain terms: after upgrading, some code will infer different types, and that code is code you previously believed was correct. Off switch: -XXLanguage:-EliminateSecondKindIncorporation.

value class is where the cut goes deepest

Value classes used to allow exactly one property and required @JvmInline. Multiple properties work now, plus two new shapes: abstract value classes and value objects.

On my machine: 2.4.21 rejects a multi-property value class outright, telling you to enable -XXLanguage:+FullValueClasses. 2.5.0-Beta2 passes with -Xfull-value-classes.

Same for value objects. 2.4.21 says modifier 'value' is not applicable to 'standalone object'; 2.5 compiles and runs with the flag.

One detail explains it better than the docs. Write === on a value object and the compiler errors immediately. Identity comparison is banned by the language, because it has no identity to compare.

The real trap is migration. value class is no longer inlined by default. The stated timeline: warnings start in 2.5.20, errors in 2.6 or 2.7. On 2.5.0-Beta2 the switch is not even recognized yet; the compiler answers that the flag is not supported, which means the window really does open at 2.5.20.

Meaning: upgrading today will not blow up. But you have until 2.5.20 to mark the old code, deciding what keeps inlining and what lets go. Whether a value class wrapping a single String should inline is a trade-off to begin with, and the language should not make that default for everyone.

The standard library closes two small gaps

Three functions landed for if expressions: onTrue(), onFalse(), ifOrNull(). Printing a line when an add succeeds used to mean a local variable and an if/else. Now one line holds it:

val added = tags.add("wasm").onTrue { println("Tag added") }

The return value is still the same boolean. The check and the side effect sit on one chain, and you no longer build a variable for a case this small.

The other half is Unicode code points. A Char holds one UTF-16 code unit, so when you hit a surrogate pair like an emoji, iterating by Char splits one character in half. The new CodePoint is a value class holding the code point in an Int, and it can tell you how many UTF-16 units it occupies, which category it belongs to, whether it is a letter.

Both need @OptIn(ExperimentalStdlibApi::class). Note the shape of CodePoint: it is only writable because value classes were relaxed. Language and standard library line up in this release.

Two surprises on my machine

First surprise: compilation did not get faster. On a 489-line project, warmed up, 2.4.21 has a median of 2.86 seconds and 2.5.0-Beta2 comes in at 2.99. The output is 161 KB either way. The difference sits in the noise, so it is not slower, but there is no visible payoff from the inference work on a small project. That kind of optimization only shows up in large generic-heavy code.

Second: the scope of that switch. -Xklib-ir-inliner=disabled is rejected outright by the JVM compiler, which says the flag is not supported. It only means something where klib is produced: Native, JS, Wasm.

On by default in the docs has to be read per platform.

Three things to do before upgrading

The JDK floor moved. The compiler’s minimum went from 8 to 17, and anything below now errors out. CI images and Docker base images have to follow, and that step usually eats more time than the code changes.

If you publish Kotlin Multiplatform libraries, do not rush into .kar. The publishing side is still experimental. Try it in a pipeline, do not push it to a real release.

Run your tests. The unused return value check and the inference changes both fall into the passes silently but behaves differently category. Reading the docs will not reveal the problem; running tests will.

Last

Most of what 2.5 does lands on defaults: packaged by default, checked by default, inlined by default, destructured by name by default. Every one of those comes with an off switch, which says the team knows it will step on people, and also that these defaults are not final.

Do you have code the IDE marks red while the command line compiles it fine? After 2.5 it will probably have to come clean. Tell me what broke on your end in the comments.

Sources: Kotlin 2.5.0-Beta2 release notes Kotlin release schedule A more reliable compilation scheme for Kotlin Multiplatform modules

On October 6, JetBrains’ Amper blog published its final post, titled Amper Is Now the Kotlin Toolchain. The name carries a line underneath, Moving to the Kotlin Blog, and it means what it says: that blog stops updating as of that day and merges into the Kotlin blog.

What got renamed is not the blog. It is Amper itself. It is now called Kotlin Toolchain, and it is the official Kotlin toolchain.

News like this is easy to scroll past as another rename to dress up the quarter. But I went through the code and docs, and this one is different: they are scrubbing the word Amper out of the codebase, layer by layer.

How thoroughly? The 0.13 release notes make it clear. Two of the breaking changes: the environment variable AMPER_BUILD_DIR becomes KOTLIN_TOOLCHAIN_BUILD_DIR, and the module layout entry named amper becomes default.

When a name gets scrubbed all the way from config files down to environment variables, it is not a marketing move.

Three moves in three months

I put the timeline in order:

The repo moved in May, the promotion was announced in June, and the name was scrubbed out of the code in October. You can see the first two in the news. The third only shows up if you open the 0.13 release notes.

One line from the June post stuck with me, explaining why the name changed:

As the project evolved, it became clear that the ecosystem doesn't just need
another build tool – it needs a unified entry point into all of Kotlin.

Translation: as the project moved forward, one thing became clear — this ecosystem does not need another build tool, it needs a single entry point into all of Kotlin.

I installed it on this machine

Rather than trust what the docs say, look at how it actually runs. Installation uses the official script. I did not pipe it straight into a shell; I pulled it down and read it first. It does a SHA256 check, and the thing is reasonably well behaved.

curl -fsSL -o /tmp/kt-install.sh https://kotl.in/install.sh

By default it appends a PATH line to your shell config. I skipped that with its own switch so it would not touch my zshrc:

KOTLIN_CLI_NO_MODIFY_PATH=1 sh /tmp/kt-install.sh

After install:

Kotlin Toolchain version 0.13.0 (abc7a5f, 2026-10-01)
Installed Kotlin CLI to /Users/trevorwang/.local/bin/kotlin

Then create a project. It has a set of non-interactive templates; I picked the JVM command line one:

kotlin init --from-template=jvm-cli --no-git

Generated in 0.34 seconds. I expected a pile of files to read; the entire project config is one line:

product: jvm/app

Three source files: a println in main.kt, an object in World.kt, two tests in the test directory.

Build, run and test, all of it

On first build it pulled down a Temurin JDK 25 itself, and after that everything came up green. Install, create, compile, run and test in one pass looks like this:

The whole thing took 30.8 seconds, and subtracting the JDK download the rest is fast. The test section is red because the template deliberately includes an assertTrue(false) in a function named shouldFail. My guess is it wants you to see what failing output looks like, and to note that the exit code is 1.

Another command I like: kotlin show settings. It prints the effective settings for each module and marks defaults with # default:

compose:
  version: 1.12.1  # default
junit: junit-5  # default

What you wrote yourself and what it defaulted to are instantly distinguishable.

Three lines of YAML, four platforms

A single JVM target is not much to look at, so I created another from the kmp/lib template. The full module.yaml it gave me, plus the build results per platform, look like this:

Platform-specific sources do not use Groovy’s source set naming. It is a directory suffix: src@jvm, src@android, src@ios, each holding its own actual. The shared expect goes in src.

You can also build only selected platforms:

kotlin build -p jvm -p android

11.3 seconds, four green lines, output is kt-kmp-jvm.jar and kt-kmp-jvm.aar.

Here is a detail I did not expect. Poking through its download cache, I found that to compile Android it dropped a platform package into my Android SDK, with a timestamp matching this build:

~/Library/Android/sdk/platforms/android-37.0/            11:35
~/Library/Android/sdk/platforms/06259a9c8a-platform-37.0_r02.zip.flag

Add the Temurin JDK, the JUnit runner for tests, and Kotlin/Native for iOS — it pulled all of it. It is almost excessively friendly to newcomers: one install command, zero configuration, and JVM and Android compile. The cost is waiting on downloads during the first build, and it writes into your SDK directory.

The iOS leg stops at Xcode

Add iOS and see:

kotlin build -p iosArm64
Downloading .../kotlin-native-prebuilt-2.4.20-macos-aarch64.tar.gz
ERROR: Xcode first-launch setup could not be completed.
       Run `sudo xcodebuild -runFirstLaunch` and try again.
ERROR: Task 'xcodeEnvironment' failed: Xcode environment is not ready

It downloads Kotlin/Native 2.4.20 first, then stops at that step. The check is new in 0.13; the release notes describe it as Check and/or provision Xcode components automatically.

The interesting part is here: Kotlin/Native itself compiles fine on this machine. I had built an iOS arm64 framework with it directly before, output in 9.8 seconds. What the toolchain checks is whether Xcode’s components have finished first-launch installation, which sits ahead of the compiler’s own requirements, and that step needs root, so you run the sudo command yourself.

I think this behavior is good. It does not compile halfway and then dump a baffling link error on you. It stops at the prerequisite check and prints the command you need.

Two places the name has not been cleaned out

First, the distribution download URL is still the old one, with amper in it: packages.jetbrains.team/maven/p/amper/amper.

The second is funnier. One entry in the Android fix list says it used to install the Android SDK under a non-canonical name, and that name was Amper-33.

Repo, blog, command line, environment variables, module layout — cleaned all the way through, with corners still left. Details like these are more honest than a press release; they show you how many layers a rename really touches.

On the IDE side, there is a new option

That covers the CLI. The IDE side changed just as visibly.

The plugin is listed in the Marketplace as Kotlin Toolchain, version 262.10968.205. Its first line of self-description:

Provides support for Kotlin Toolchain, JetBrains' build tool for Kotlin and
Java projects.

Translation: provides support for Kotlin Toolchain, JetBrains’ build tool for Kotlin and Java projects.

Three things in the feature list I care about: running and debugging JVM, Kotlin Multiplatform and native tests; managing multi-module projects and version catalogs; and hot reload for Compose Desktop and Compose Multiplatform. There is also a note at the top of the page saying some features require an Ultimate subscription.

The really interesting part is the new project dialog. The Build system field is no longer just Gradle; there are two side by side, and the one on the right is Kotlin Toolchain.

It writes one line for each. Verbatim:

Gradle — Flexible and backed by a mature plugin ecosystem
Kotlin Toolchain — Easy to use, declarative, and AI-friendly

Translation: Gradle is flexible and backed by a mature plugin ecosystem; Kotlin Toolchain is easy to use, declarative and AI-friendly.

AI-friendly is their own word. An IDE company putting “AI-friendly” in the default copy of its new project dialog is not a surprise this year, but the placement says a lot.

The platform picker follows the same idea as the CLI templates: five checkboxes for Android, iOS, Desktop, Web and Server, and for iOS and Web you can choose whether the UI is shared with the other targets. Check Android plus iOS and the structure comes out like this:

A project.yaml at the root lists the modules: androidApp, desktopApp, iosApp, shared, webApp, core, server — seven. Each module has its own module.yaml, the same three-line thing from the CLI earlier. Versions still live in libs.versions.toml; it kept that Gradle habit, and the wrapper scripts are called kotlin and kotlin.bat.

Run configurations work as is: pick iPhone 17 | iOS 27.0 in the device dropdown and iosApp runs.

So should you switch

The official FAQ has a passage that answers why they did not just improve Gradle. Verbatim:

With the Kotlin Toolchain, we want to show you our design and get your feedback,
as it will help us to decide which direction to take the design. At the same time,
we are also working with the Gradle team to improve Gradle support in our IDEs
and Gradle itself.

Translation: we want to put the design in front of you and let feedback decide which direction it takes. At the same time, we are working with the Gradle team to improve Gradle support in our IDEs and Gradle itself.

Politely worded, and the meaning is clear: this is not replacing Gradle, it is a side-by-side showing.

Migration is interesting too. Maven projects get a convert command, kotlin tool convert-project, which handles part of it automatically. Gradle projects have no tool, and the official explanation is that Gradle scripts are arbitrary code, so no deterministic conversion rules can be written.

So what do you do? One line in the FAQ stopped me: this is the kind of thing an AI agent is good at, given a set of skills. I went and looked. The skills sit under the Kotlin org, called kotlin-agent-skills, 1,071 stars, ten skill files, two of them specifically about migrating from Gradle to Kotlin Toolchain.

The rules inside are strict: every third-party Gradle plugin has exactly three paths — drop it, replace it with a native equivalent, or rewrite it yourself. Keeping it is not an option. And the convention plugins you wrote in buildSrc do not count as plugins, they count as configuration, and they have to become module templates.

That one is worth writing down. Treat the build script as code and an AI can do the mechanical translation. Treat it as configuration and the implicit conventions become the most expensive part of the migration.

Wrapping up

Summing up this week’s move: the name Amper retires, what it leaves behind becomes the official Kotlin toolchain, and the front door is one kotlin command plus one YAML file.

New projects are worth trying — three lines of config compiling four platforms is genuinely pleasant. Leave old projects alone for now. It is still Alpha, and the team itself says not all migration scenarios are covered.

Repo and docs:

github.com/JetBrains/kotlin-toolchain
kotlin-toolchain.org

One question to close with: if you had to move your current KMP project off Gradle onto this today, which step do you think would stop you first?

On October 5 JetBrains published a short announcement. The title is blunt: IDE support for the Swift language is ending in the KMP plugin. The effective versions are specific: IntelliJ IDEA 2026.3 and Android Studio Rabbit 2 | 2026.2.2.

The list of removed features is specific too. Copying it:

This includes editing, syntax highlighting, and navigation within Swift
files and between Swift and Kotlin.

In other words: editing, syntax highlighting, and navigation inside Swift files, and between Swift and Kotlin.

Reading those lines, a lot of people’s first reaction is that KMP on iOS is finished. Hold on. The second paragraph of the same announcement draws the boundary.

Which layer got removed

The second paragraph reads:

Running iOS applications and debugging Kotlin code on iOS will remain fully
supported. Kotlin/Native functionality, such as Swift Export and importing
Swift packages into Kotlin projects, is not affected.

In other words: running iOS apps and debugging Kotlin code on iOS stay fully supported. Kotlin/Native features like Swift Export and importing Swift packages into Kotlin projects are unaffected.

So what got taken away is the layer in the IDE that reads and edits Swift. The compiler, the Native toolchain, the path into Xcode are all still there.

I verified that second half on this machine. I already had the prebuilt Kotlin/Native 2.4.0 and Xcode 26.2, so I used them to compile a small piece of code into an iOS framework:

kotlinc-native -target ios_arm64 -produce framework -o out/shared src/shared.kt

Nine point eight seconds. The output is a Mach-O 64-bit arm64 dynamic library plus a header file for Xcode. Not one step in that chain regressed. Pulling the Swift features did not touch it.

So what actually carries iOS

Take the chain apart and the order is:

1. Kotlin/Native compiles the shared code into a framework Apple can use — that is the nine point eight seconds above.
2. Xcode links that framework into the iOS app. embedAndSignAppleFrameworkForXcode in Gradle is exactly this job.
3. The Swift shell calls Kotlin. Today that mostly goes through Objective-C header interop, and the team is separately pushing Swift Export, still in Alpha, aimed at letting Kotlin export directly as a Swift module and dropping the header layer.
4. Reading and editing Swift in the IDE was only convenience during development. Remove it and the three layers above do not move.

Get these four straight and the weight of the announcement becomes clear.

Why they pulled it

The official reason is usage. Their telemetry and user research show that iOS developers on KMP projects mostly write Swift in Xcode, while the people working inside the KMP plugin increasingly use Kotlin and Compose Multiplatform.

There is also historical baggage: this Swift tooling was originally built for AppCode, and AppCode was discontinued long ago. Then it moved to Fleet, then into the KMP plugin. Keeping its core architecture in step with the continuous changes in Swift, Xcode and the IntelliJ platform is a real investment. They weighed it and decided not to, and they state plainly that they do not currently plan to replace it with something else.

That trade-off is actually on the same line as KMP’s moves these past months: they are spending effort making the Kotlin side better, not doing Xcode’s job for it.

The community side is ahead of the secondhand reports

On the same day there was another item on the trending list, pointing the opposite direction. The iOS version of the open-source OSM editor StreetComplete entered TestFlight — the first testable build after years of porting work.

That port dates from a tracking issue opened in December 2023, still open today, 51 comments accumulated. The maintainer says a full port is roughly one person-year of work, that the first half of 2024 was pushed full-time on Prototype Fund money, and that by September of that year about half was done.

One claim in the secondhand reports has already expired. It says the Compose Multiplatform MapLibre library does not exist yet and is the blocker for the port. I went and read StreetComplete’s build file. It currently says:

implementation("org.maplibre.compose:maplibre-compose:0.19.0")

That library has shipped on Maven Central from 0.11.0 all the way to 0.19.0. That gap is closed.

The costs have to be stated too. The prototype fund ran out; the maintainer writes in the issue that follow-on funding does not look good — OpenStreetMap has no money, NLNet’s program is contracting, and the crowdfunding sponsors have not increased. Known issues are still open: the map does not work on iOS 15.x, forms can only be dismissed with a gesture, and there are still plenty of bugs.

I counted the repo

While I was there I counted the repo by source set. More convincing than reading news:

• commonMain: 1,281 Kotlin files, 3.6MB
• commonTest: 287 files, 1.3MB
• androidMain: 34 files, 43KB
• iosMain: 33 files, 42KB

So each platform gets a shell of a bit over forty KB and the same app runs on iOS and Android. Among the 33 files on the iOS side, the biggest is IosModule.kt at six thousand bytes, doing dependency injection wiring; the rest are platform-specific pieces: networking, sync, upload, periodic cleanup.

See that ratio clearly and the blast radius of the announcement is clear too: the removed features act on that forty-two KB shell, and have nothing to do with the shared three point six MB.

These two stories are one story

JetBrains’s choice is “I do the Kotlin side well, the Swift side goes to Xcode”. StreetComplete’s approach fits that division exactly: shared logic and UI are all written in Kotlin and Compose, and the Swift side is left as a shell.

So the call is simple. Ask yourself a few things:

• Where do you actually write Swift in this project? If Xcode was open anyway, this announcement barely touches you.
• If you read and edit Swift inside Android Studio, you need to change your workflow from now on, or stay on an older version.
• Do not look at IDE support and toolchain support as the same thing. The first is gone. The second is not.
• A viable technical path does not mean a project reaches the finish line. The StreetComplete story is a reminder about money and people.

How long does the version on your machine still work

The threshold is Android Studio Rabbit 2 | 2026.2.2 and IntelliJ IDEA 2026.3. Mine is 2026.2, so the Swift features you have are still there, they just stop getting updates. If you need them badly, upgrade a little later. If not, let it ride — Swift’s real home has always been Xcode.

In your KMP project, where do you write the Swift on the iOS side? Comments are open.

References:

• https://blog.jetbrains.com/kotlin/2026/10/discontinuing-swift-language-ide-support-in-the-kotlin-multiplatform-plugin/
• https://github.com/streetcomplete/StreetComplete/issues/5421

If you write Kotlin Multiplatform you have probably hit this: the line is red in the IDE, underlined with a cannot find symbol, you hesitate for ages and do not dare commit, then you build and it is green, and it even runs correctly.

We used to blame the IDE acting up, an index that had not been built, just clear the caches. On September 28 JetBrains published a post, and the first line is blunt:

The current compilation approach to Kotlin Multiplatform projects works, but sometimes can lead to unexpected or hard-to-predict behavior.

In plain terms: the current compilation approach works, but sometimes it hands you behavior you cannot predict. Then it lists two examples, both things we have hit and never explained:

The IDE analysis disagrees with the compiler on an overload, type inference, or whether the code should compile at all – with the IDE being stricter than the compiler.

Your commonTest code can unexpectedly call something from a platform source set, breaking your assumptions.

One is the IDE being stricter than the compiler, the other is commonTest quietly reaching into a platform source set. Below I explain the mechanism first, then give my own test results, because in the official example you only get shown half the price of the fix.

Why the disagreement exists

The key is what common code resolves its dependencies against when it compiles.

In a KMP module, commonMain is not compiled into an independent artifact and that is the end of it. When compiling the JVM target, the compiler takes commonMain and jvmMain together and compiles them against the dependency’s platform artifact (a jar on JVM). So a call in commonMain has a chance to implicitly land on a declaration in the dependency’s jvmMain.

The IDE’s code analysis does not do this. It assumes common code can only see the dependency’s common declarations, the part listed in the metadata KLIB. jvmMain declarations are not in there, so the IDE shows red.

Two different understandings of the same line, and neither is wrong, but you are stuck in the middle. The post even gives a nastier version: inconsistent overload selection, where the IDE jumps to the commonMain overload while the runtime prints the platform one.

Then there is type inference divergence, where the common side infers Any and JVM compilation fails outright with Unresolved reference. The reverse happens too: with the same example and the flag on, the common phase fixes the return type of currentEvent() to Event, .name has a basis, and JVM compilation passes. So this feature cuts both ways. It makes code that got lucky fail, and it also fixes code that used to fail.

The difference between those two paths looks like this:

The new scheme is one flag

Kotlin 2.5.0-Beta1 introduced an optional separate compilation mode, so the compiler also uses the strict metadata KLIB resolution when compiling common source sets, lining up with the IDE.

# gradle.properties
kotlin.kmp.separateCompilation=true

It is marked Experimental and off by default. One bonus: it makes incremental compilation of common source sets possible, which was not achievable before.

The official example reads easily. Code the IDE flagged red but the compiler accepted now fails to compile too; just wire up expect/actual explicitly and you are fine.

Test one: it really does stop you

I built a minimal KMP project locally (Kotlin 2.5.0-Beta1, two targets: jvm and js), two modules:

lib/  src/commonMain/Marker.kt      # interface only
      src/jvmMain/Foo.kt            # class Foo, declared only in the platform source set
app/  src/commonMain/Main.kt        # directly new a Foo from lib

app depends on lib, and app’s commonMain news up a class that only exists in lib/jvmMain.

Flag off:

> Task :app:compileKotlinJvm
BUILD SUCCESSFUL in 30s

Flag on, same code:

e: app/src/commonMain/kotlin/Main.kt:3:12 Unresolved reference 'Foo'.
e: app/src/commonMain/kotlin/Main.kt:6:13 Unresolved reference 'Foo'.
BUILD FAILED in 2s

The post was right, and it stops you cold. Not a warning.

Same for commonTest. I put a PlatformOnly class in app’s jvmMain and had commonTest new it: flag off BUILD SUCCESSFUL, flag on gives Unresolved reference 'PlatformOnly'.

Test two: the price of the fix the official example does not show

The official fix is explicit expect/actual. lib’s commonMain declares expect, the platform source set provides actual. I made that change and the JVM side really did pass:

// lib/commonMain
expect class Foo()

// lib/jvmMain
actual class Foo actual constructor()

With the flag on, :app:compileKotlinJvm is BUILD SUCCESSFUL in 1s. That half of the official story is right.

Then I went to compile the JS side of the same module:

e: lib/commonMain/kotlin/Marker.kt:5:1 The 'expect' declaration 'lib.Foo'
   has no 'actual' declaration in module '<commonMain> for JS'.
BUILD FAILED in 2s

expect/actual is a paired contract. Every target needs its own actual. The blog example only ever showed the JVM side. Turn it on in a multiplatform project and you owe one actual per target.

One thing the official post does not mention: the version number is not the gate

The blog says the feature was introduced in Kotlin 2.5.0-Beta1. I took the same bad code and tried it on Kotlin 2.4.20 (current stable):

# without the property
BUILD SUCCESSFUL in 704ms

# with kotlin.kmp.separateCompilation=true
e: app/src/commonMain/kotlin/Main.kt:3:12 Unresolved reference 'Foo'.
BUILD FAILED in 11s

The property still flips behavior on 2.4.20, and I checked that this project really resolves to kotlin-gradle-plugin:2.4.20.

So this flag is not something that came into existence in 2.5, it is just that the team only started talking about it as a feature in 2.5.0-Beta1. Flip it around: do not treat the version number as a gate, and do not treat it worked on 2.4 as a conclusion either. Neither is solid. You have to run it on your own project to know.

A quick reference table

Here is everything above plus the official Known issues section in one table, for when you hit one of these cases:

Should your project turn it on

Combining the above with the official Known issues section, my checklist is this:

• Do the libraries you depend on properly publish metadata KLIB? The new scheme turns that from nice to have into required. A library whose author cut corners will fail the moment you turn it on, and that is not your fault.
• How much does the project rely on common calling platform? The KMP project I have routes platform differences through interfaces and barely uses expect/actual, so before turning it on I need to sweep for these calls, otherwise a pile of Unresolved reference appears all at once.
• Do you use cinterop? The docs call out two known issues here (KT-88178, KT-41509), so projects with native C interop should be careful.
• Modules with only one target are unaffected, the docs say so plainly.
• It is still Experimental and off by default. Treat it as a preview, not an upgrade.

A word on the iOS front

In the same week JetBrains also published a TeamCity design retrospective about turning Kotlin Multiplatform iOS packaging into a guided flow: install a plugin, push, and the IDE pops a Configure CI prompt. Follow it and you go from first push to running tests, signing, shipping to TestFlight, and finally hooking up GitHub to run on every push.

Along the way it generates four files (teamcity.yaml plus Fastfile, Appfile, Gemfile) and leaves them local and uncommitted. The first build runs on a hosted macOS agent, and only after you have seen it pass does it let you commit.

I did not test this part, there is no TeamCity account on this machine. That section comes entirely from the official design retrospective and the official tutorial it points to.

Last

Back to that moment where the IDE shows red and the compiler passes. It was never an IDE bug and never your imagination. Two sets of resolution rules simply were not aligned for a long time. What the team is doing now is pulling the compiler over to the IDE’s side: stricter, more predictable, at the price of code that used to get lucky having to be made explicit first.

What I want to do next is turn it on in the KMP project I have, list every Unresolved reference that pops up, and see how much expect/actual that project actually owes.

Have you turned this flag on in your Kotlin Multiplatform project? How many errors did it report? Tell me in the comments.

References:

• A More Reliable Compilation Scheme for Kotlin Multiplatform Modules: https://blog.jetbrains.com/kotlin/2026/09/a-more-reliable-compilation-scheme-for-kotlin-multiplatform-modules/
• Designing the Kotlin Multiplatform and TeamCity Integration: https://blog.jetbrains.com/teamcity/2026/09/designing-the-kotlin-multiplatform-and-teamcity-integration/
• Official iOS CI/CD tutorial: https://kotlinlang.org/docs/multiplatform/ios-ci-cd-teamcity.html

Same JSON, same app, same run.

The first: the form is full. Guest Ada Lovelace, date Oct 1, 2026, time 7:30 PM, party of 2, two buttons underneath reading Cancel and Confirm booking. Native Material 3 controls all the way down.

The second: the same form, every field empty. Not just empty. The labels on both date-time controls are gone too, leaving two gray rounded boxes.

The only difference is when I sent the updateDataModel message. Send it in the same batch as the components and the fields get dropped. Send it a second later, on its own, and the values land. I will come back to this. It is the most valuable hole I fell into this time.

What A2UI is

One sentence, their words:

A2UI (Agent to UI) is a declarative UI protocol for agent-driven interfaces. AI agents generate rich, interactive UIs that render natively across platforms (web, mobile, desktop) without executing arbitrary code.

The agent does not emit HTML or JavaScript. It emits declarative JSON describing what the interface looks like, and the client renders it with its own native components. The scenario they use to contrast it is the classic one:

User: “Book a table for 2 tomorrow at 7pm” Agent: “Okay, for what day?” User: “Tomorrow” Agent: “What time?”

Three round trips to fill one form. Swap in an agent that generates the form itself, with a date picker, a time picker and a submit button, and the user is operating an interface instead of talking to one.

The smartest design in this protocol, I think, is the catalog. It does not let the agent invent UI freely. The client declares a contract first: these are the components, these are the properties, these are the local functions. The agent can only pick and compose inside that contract. The spec puts it plainly:

Rather than having an agent generate arbitrary UI code or invent unregistered components, the catalog acts as a contract that defines the specific UI elements, properties, and functions available to the agent.

Add the sends-data-not-code property and the security math gets easy: no iframe, no arbitrary code execution.

The official renderer on the Compose side

On September 23, AndroidX shipped an A2UI renderer for Jetpack Compose, 1.0.0-alpha01. I checked each of these artifacts on Google Maven; they all exist:

implementation("androidx.a2ui.compose:compose-runtime:1.0.0-alpha01")  // fine-grained recomposition on Compose Snapshot state
implementation("androidx.a2ui.compose:compose-ui:1.0.0-alpha01")       // components and catalog definitions
implementation("androidx.a2ui:a2ui-model:1.0.0-alpha01")               // protocol data layer
implementation("androidx.a2ui:a2ui-engine:1.0.0-alpha01")              // parsing, schema validation
implementation("androidx.compose.material3:material3-a2ui:1.0.0-alpha01")  // Material 3 implementation of the Basic Catalog

material3-a2ui is the finished product: the Material 3 implementation of the Basic Catalog, one line and it runs. What you have to supply is image, video and audio players, plus callbacks for opening URLs and formatting localized text. Leaving out Coil and Media3 is deliberate:

The A2UI libraries intentionally don’t bundle external media and networking dependencies, such as Coil, Glide, or Media3. Instead, you provide your own renderers.

One more thing KMP developers will ask about immediately. I unpacked the Gradle module metadata for compose-runtime:

- releaseVariantReleaseApiPublication     type=aar
- releaseVariantReleaseRuntimePublication type=aar

Only aar. No klib, no JVM variant. This release is Android-only, so Compose Multiplatform cannot use it today.

Minimal wiring

Two objects on the data side: a parser and a processor.

private val parser = A2uiMessageParser()

private val catalog = materialA2uiBasicCatalogV1(
    image = MaterialA2uiBasicCatalogV1Defaults.image { url, _, _, modifier, _ ->
        Placeholder("image", url, modifier)
    },
    urlOpener = { url -> Log.i(TAG, "open $url") },
    messageFormatter = { pattern, locale, args -> /* MessageFormat */ },
    localeProvider = A2uiLocaleProvider.Default,
)

private val processor = A2uiMessageProcessor(catalogs = listOf(catalog))
val surfaces = processor.activeSurfaces

init {
    viewModelScope.launch(Dispatchers.Default) { processor.collectMessages() }
    viewModelScope.launch(Dispatchers.Default) {
        processor.outboundEvents.collect { Log.e(TAG, "OUTBOUND: $it") }
    }
}

The UI side is one loop, handing each surface to A2uiSurface:

surfaces.forEach { surface ->
    key(surface.id) {
        A2uiSurface(surfaceModel = surface, modifier = Modifier.fillMaxWidth())
    }
}

What goes in is three protocol messages. createSurface opens the canvas, updateComponents describes the component tree, updateDataModel supplies the bound values:

{ "version": "v0.9",
  "createSurface": { "surfaceId": "booking",
                     "catalogId": "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json" } }

{ "version": "v0.9",
  "updateComponents": { "surfaceId": "booking",
    "components": [
      { "id": "root", "component": "Column", "children": ["title", "nameField", "actions"] },
      { "id": "title", "component": "Text", "text": "Book a Table", "variant": "h1" },
      { "id": "nameField", "component": "TextField", "label": "Guest name",
        "value": { "path": "/booking/name" }, "variant": "shortText" }
    ] } }

Note that value on a component is not the value itself but a path into the data model. Which is exactly why whether that third message lands determines whether your form is full or empty.

Once it runs, the pits come one after another

Every item below is something I actually hit and then found the cause or the workaround for. Not one of them is in those two pages of docs.

1. updateDataModel sent in the same batch as updateComponents gets silently dropped. This is the nastiest one. The surface appears normally, nothing errors, and every property bound through path comes up empty. Resend the same bytes one second later and the fields fill in immediately. logcat says all three messages parsed OK and the surface count is 1, but the values never land:

parsed OK -> A2uiCreateSurfaceMessage surfaceId=booking
parsed OK -> A2uiUpdateComponentsMessage surfaceId=booking
parsed OK -> A2uiUpdateDataModelMessage surfaceId=booking
activeSurfaces.size=1 ids=[booking]

So what I ended up doing: send createSurface and updateComponents first, wait for the surface to appear, then push the data model. That happens to be the real order a streaming agent produces anyway. Accidental and correct at the same time.

2. catalogId is v0_9, not v0_9_1. The “stable” example on the docs site says version: v0.9.1 and .../v0_9_1/.... The actual constants in the library are protocol = v0.9 and .../v0_9/catalogs/basic/catalog.json. The parser accepts either version string, but createSurface.catalogId has to match the id of the catalog you registered exactly. Miss it and the surface never appears, again with no error. My fix: stop copying strings out of docs and read them from the library constants.

3. processInput is not a method on A2uiMessageProcessor. It is a top-level extension function in the androidx.a2ui.model.processor package. You have to import androidx.a2ui.model.processor.processInput. Copy the line from the docs verbatim and it will not compile.

4. Failures are silent. Inside, processInput swallows A2uiException, turns it into processor.processError(...), and emits it only on outboundEvents. If you are not collecting that flow (the docs collect it, but never say what skipping it costs), protocol errors and parse failures are completely invisible and all you get on screen is a white box. First thing when debugging this library: wire up outboundEvents.

5. material3-a2ui:1.0.0-alpha01 does not work with the current stable Compose BOM. Its POM demands androidx.compose.* 1.13.0-alpha03 and pins material3 to a strict [1.5.0-alpha28] range. The stable BOM resolves to 1.12.x, so it will not install. I ended up dropping the BOM and pinning versions by hand.

6. There is no documentation for compileSdk 37 minor 1. compileSdk = 37 cannot find the already-installed android-37.1. What works is:

compileSdk { version = release(37) { minorApiLevel = 1 } }

7. The surface root component id has to be root. It is a private constant. Name it anything else and your Column is not the root.

8. Enum values are pure guesswork. Get one wrong and the schema fails, and the docs do not list them:

Text.variant           h1 h2 h3 h4 h5 caption body
Button.variant         primary secondary borderless
TextField.variant      shortText longText number obscured

My approach was to javap the enums out of the AAR and read them one by one.

One more, unrelated to A2UI but impossible to dodge: adding org.jetbrains.kotlin.android under AGP 9.x gets rejected outright. Kotlin support has been built into AGP since 9.0, so you keep only the compose plugin.

My verdict

It works, and what it renders really is native Material 3, not a wrapped web page. But at alpha the docs are running behind the code. The real catalogId, the shape of processInput, message ordering, how to pin versions: you have to unpack the artifacts and look. Good for a proof of concept right now. Do not rush it into production.

On the KMP side, wait. The aar-only fact alone settles it: Compose Multiplatform only gets the Android half.

What I want to try next is closing the outbound path: the user taps Confirm booking, the event goes back to the agent, and the agent sends another updateComponents to change the UI based on the result. I only wired that path up. I never actually pressed the button, so I am not claiming here that it works.

Would you let an agent generate the interface in your AI chat client directly? Or would you rather hard-code the UI and only let the agent fill in content? Comments are open.

References:

• A2UI protocol site: https://a2ui.org/
• The A2UI renderer for Jetpack Compose (official docs): https://developer.android.com/develop/ui/compose/agentic
• Custom catalogs: https://developer.android.com/develop/ui/compose/agentic/manage-catalogs
• A2UI Compose release page: https://developer.android.com/jetpack/androidx/releases/a2ui-compose

Verification boundary: both screenshots, the parse logs for the three messages, the catalogId and protocol version constants, the A/B on message ordering, and the build and install all come from running on a real emulator on this machine (Android emulator API 36.1, APK 13,471,211 bytes, BUILD SUCCESSFUL). Component property names and enum values came from javap on the unpacked AAR. The tap-to-agent return path was not exercised. Images, video and audio use placeholder renderers, not real loading libraries.

A user edits a checklist on the subway: adds two levels, renames one of them, deletes the one they do not want. The whole thing happens offline and only uploads once they are back above ground.

You want that to land on the server as one transaction. But if the client tracks sync state per row, that single save gets split into several independent requests, and if any one of them fails you are left with half-written data in the account.

premi jit chowdhury, the author of Nitivakya, wrote this rework up recently. The app uses KMP + SQLDelight + Supabase and started out as a daily ancient quote, living happily on a localState field (DIRTY / SYNCED / DELETED) on a single favoriteEntity. Then he added Actions, and the structure became a nested tree: Action to Action Levels to Action Level Items.

A row-level flag tracks final row state, not multi-entity mutation intent.

His words: a row-level flag records the final state of that row, not the intent of a multi-entity change. That sentence is where the rework starts.

Three specific collapses

He lists three failures in the post. I will quote them first, then unpack.

2 separate table REST calls caused foreign-key 500 errors over shaky connections. Full-snapshot uploads risked overwriting server-calculated streak progress. Row-level flags couldn’t express a simultaneous “Create Level A + Update Level B + Delete Level C” edit.

Child rows arrive before parent rows, the server returns a foreign key constraint error, and the child rows stay stuck in DIRTY forever. Route around the split requests with a whole-tree snapshot upload and you overwrite the streak count the server computes itself. The third is the hardest to dodge: creates, updates and deletes mixed into one save gesture cannot be expressed by a row flag at all.

The judgment I agree with is this — the problem is not that the flag holds the wrong value, it is that row granularity cannot carry what actually happened in this edit.

His new architecture: local state for the UI, an outbox for uploads

The result separates two layers. Local entity tables keep localState, now used only by Compose to render a status dot. Sync moves to a single aggregate outbox table holding sparse JSON DTOs with only the fields that actually changed.

CREATE TABLE syncQueueEntity (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  userId TEXT NOT NULL,
  type TEXT NOT NULL,
  operation TEXT NOT NULL,
  entityId TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'PENDING',
  createdAt INTEGER NOT NULL,
  payload TEXT,
  UNIQUE(userId, type, entityId)
);

That unique constraint is the point: multiple edits to the same entity collapse into one row. On the Kotlin side, withSync does three things inside one database transaction: performs the local write, deep-merges the new payload into the existing payload in the queue, and removes the queue row outright when it sees a create followed by a delete.

Enqueueing uses ON CONFLICT with a state machine guard so an offline create is not mislabeled as an update:

INSERT INTO syncQueueEntity (userId, type, operation, entityId, createdAt, payload)
VALUES (?, ?, ?, ?, ?, ?)
ON CONFLICT(userId, type, entityId) DO UPDATE SET
  operation = CASE
      WHEN syncQueueEntity.operation = 'INSERT' AND excluded.operation = 'UPDATE' THEN 'INSERT'
      ELSE excluded.operation
  END,
  status = 'PENDING',
  createdAt = syncQueueEntity.createdAt,
  payload = excluded.payload;

Uploads no longer call table by table. One Supabase RPC goes into PostgreSQL. The function locks the row with FOR UPDATE, then runs deletes and upserts in order, and the function body is itself the transaction.

CREATE OR REPLACE FUNCTION public.update_action(
    p_action_id uuid, p_updated_at timestamptz,
    p_action_updates jsonb DEFAULT NULL,
    p_levels_upsert jsonb DEFAULT NULL,
    p_levels_delete uuid[] DEFAULT NULL,
    p_items_upsert jsonb DEFAULT NULL,
    p_items_delete uuid[] DEFAULT NULL)
RETURNS void LANGUAGE plpgsql SECURITY INVOKER AS $$
BEGIN
    PERFORM 1 FROM public.actions WHERE id = p_action_id AND user_id = auth.uid() FOR UPDATE;
    IF p_levels_delete IS NOT NULL THEN
        DELETE FROM public.action_levels WHERE id = ANY(p_levels_delete);
    END IF;
    -- then the atomic upsert of levels and JSONB items
END;
$$;

I ran it locally

I ran the article’s SQL on sqlite3 3.54.0 (scripts /tmp/kmp-article/outbox.sql and atomicity.sql). All three conclusions hold.

INSERT while offline, then UPDATE the same entity: operation really does stay INSERT, createdAt is not refreshed, and only payload is replaced.

But INSERT followed by a straight DELETE is beyond what the SQL layer handles: the row stays, operation flips to DELETE, and payload is wiped to NULL. The author says that self-cancellation happens in the Kotlin transaction, and the test backs that division of labor up.

The foreign key case reproduced too. Insert into the child table first and you get FOREIGN KEY constraint failed; wrapped in a transaction it rolls back cleanly and neither the parent nor the child table keeps half a row. That is the core reason he insists on RPC rather than per-table REST.

On the Kotlin side I compiled and ran deepMerge and the cancellation logic with the kotlinc from the Gradle cache (kotlin-compiler-embeddable 2.4.10). Four offline edits — create level-3, rename level-3, create level-4, delete level-4 — collapse into one row with one payload:

queue row entityId=action-101 operation=INSERT
merged payload={"levelsUpsert":{"level-3":{"title":"Deep Meditation","sequence":3},
"level-4":{"title":"Breath Work","sequence":4}},"levelsDelete":{"level-4":{"id":"level-4"}}}
enqueue count=4, final queue rows=1

Create action-202 and then delete it instead, and nothing is left in the queue. Zero network calls.

One edge I ran into

In that payload above, level-4 appears in both levelsUpsert and levelsDelete. It is created and deleted at the same time.

His deepMerge only merges at key level and does not cancel the same entity across those two maps. So automatic create-then-delete cancellation only covers the INSERT plus DELETE case, the whole-row cancel. A create-then-delete inside the same level has to be handled in order by the server RPC, or pruned by the client during merge.

In other words, the sparse payload buys you out of whole-tree uploads, but it splits conflict resolution across two places: the client transaction and the execution order of the server function. Get either one wrong and you end up with something deleted locally that still exists on the server.

Four questions to check your own setup

First, does your row-level flag record final state or change intent? If it is the former, a nested structure exposes it immediately.

Second, what happens when a child entity reaches the server before its parent? If the answer is an error and a row stuck in DIRTY, your sync path is missing an atomic entry point.

Third, does a whole-tree snapshot overwrite fields the server computes? Streaks, points and counters are the ones that get silently rewritten.

Fourth, insert-then-delete self-cancellation: do you do it on the client or leave it to the server? Doing it in both places is not bad. Doing it in neither is a data hole.

Finally

What is worth reading here is not the outbox pattern itself but how clearly the author draws the line on when to change architecture: for simple one-to-one flags, a row-level flag is enough; once nested composite edits appear, store the change intent as a first-class thing.

How do you handle composite offline edits? Tell me your approach in the comments.

References:

• Original post: https://premjitchowdhury.medium.com/when-offline-sync-relying-only-on-local-state-breaks-and-how-i-fixed-it-in-nitivakya-kmp-245e05892ac3
• Reddit thread: https://www.reddit.com/r/Kotlin/comments/1wrdk0q/when_offline_sync_relying_only_on_local_state/
• Supabase database functions and RPC: https://supabase.com/docs/guides/database/functions

Verification boundary: the three SQLite conclusions and the Kotlin merge logic in this article were actually run locally (sqlite3 3.54.0, kotlinc 2.4.10). The Supabase RPC function and PostgREST’s real behavior were not verified against a project; the function body is excerpted from the original post.

Cloud drive clients are nothing new, but this year I have heard one codebase, two platforms so many times I’ve gone numb to it. So what actually made me stop was not that it runs on two platforms. It’s the shape it gave that idea.

I cloned the repo and counted, and then I got stuck on one thing.

The structure first

Piko is Kotlin Multiplatform plus Compose Multiplatform, five modules. The measured code volume looks like this:

• shared state and business logic, 79 files under commonMain
• ui shared interface, 74 files under commonMain, this is the only source set it has
• app Android entry point, 22 files
• desktopApp desktop entry point, 29 files
• cli a command-line tool for development, not shipped

The first two add up to 153 files and over 31,000 lines of Kotlin, and that’s the part both platforms share. The last two are the entry points, 51 files and 8,000-odd lines together.

So far this looks normal. What’s not normal is the next command I ran.

Not a single line of expect/actual

In KMP, the textbook answer for platform differences is expect/actual: write expect fun in common code, write actual fun in each platform’s source set. I meant to count how many it used so I could quote it as an example.

grep -rn "^\s*expect " --include="*.kt" shared ui app desktopApp
expect declarations: 0
actual implementations: 0

I assumed my regex was wrong and tried a few variations. Same result. A project with 31,000 lines of shared code and 46,000 lines of Kotlin repo-wide uses expect/actual zero times.

What’s stranger is the source set layout. shared has no androidMain, ui doesn’t even have desktopMain, and the one platform-specific source set in shared is called jvmSharedMain — one file, 67 lines.

So this isn’t “used rarely”. It’s a completely different approach.

Its answer: interfaces, plus runtime injection

The author wrote one line in his architecture notes that I think is worth more than any paragraph in a tutorial:

Platform differences go through interfaces, not expect/actual

The reason is in a comment sitting on the capability interface definition:

The implementations need a Context, a window, and each platform’s own playback backend. These are runtime objects, not compile-time platform differences.

That line cut through a muddle I’d been carrying. expect/actual solves compile-time differences: same function name, one implementation per platform, the compiler picks. But the things a real client needs to split are almost all runtime objects. Android needs a Context, needs to register ActivityResult launchers, needs libmpv’s SurfaceView for playback. Desktop needs a window handle, needs MPV’s native DLL, needs the video surface zero-copied into Skia. What these share is that at compile time they look like the same kind of thing. Only the construction differs.

And differing construction is exactly what dependency injection is best at.

Here’s how it does it. A single interface in the shared ui module called PikoPlatform lists everything the interface needs from the platform: clipboard, system color picking, download directory selection, opening and sharing local files, full-screen dialogs, in-app updates.

Two entry points each implement it, AndroidPikoPlatform and DesktopPikoPlatform, and the entry point wires them into the root composable PikoApp(services, platform, appearance, videoPlayer). Inside the UI they’re reached through LocalPikoPlatform, with no hunting for singletons.

Capabilities a platform lacks, expressed with null

The usual complaint about interfaces is verbosity. Take “share a file”: Android has a system share sheet, desktop has no equivalent, so how do you write the interface.

Here’s how it handles that. Capability fields can be nullable:

/** null means this platform has no in-app updates. */
val updater: AppUpdateService?

/** null means this platform offers no frame preview for downloads; the entry point is hidden. */
val videoPreview: VideoPreviewSupport?

Some are booleans:

/** System share sheet. false on desktop where there is no equivalent, so the UI hides "Share". */
val canShare: Boolean

Some are finer grained: whether the soft keyboard pops up, always false on desktop; and the shortcut modifier key — Ctrl on Windows, ⌘ on macOS — exposed as a shortcutModifier property.

The benefit of this convention is that the UI asks once whether you can do a thing, then decides for itself whether to hide the entry point. No scattering platform checks through common code for a feature that only exists on one platform. Once that kind of check piles up, common code is common in name only.

A third tool: an intermediate source set

Interfaces handle “the two platforms really are different”. But there’s another category: code that is identical on both sides and only needs JDK APIs. The sample in Piko is the network proxy selector, PikoProxySelector, 67 lines.

It has to install a process-level ProxySelector into the JVM, because the SDK builds its own OkHttpClient internally, gives you no constructor parameters, and the only way in is global. That code is character-for-character identical on Android and desktop.

Follow the textbook and this is two actuals with copy-pasted content. What it does instead is add an intermediate source set, declaring in the build script that this group holds both JVM targets:

applyDefaultHierarchyTemplate {
    common {
        group("jvmShared") {
            withCompilations {
                it.platformType == KotlinPlatformType.jvm ||
                    it.platformType == KotlinPlatformType.androidJvm
            }
        }
    }
}

That’s where the jvmSharedMain directory comes from. Write it once, both JVM-family targets compile it. Before writing this post I had never seen this trick in any tutorial, and of the three tools it saves the most work.

So by this point KMP has three tiers for drawing platform boundaries:

1. If it can be shared, put it in commonMain. That’s where the vast majority of code goes.
2. If behavior genuinely differs, use an interface plus runtime injection.
3. If the code is identical and only needs JDK APIs, add an intermediate source set.

expect/actual is the fourth tier. It went unused because the first three happened to cover every need in this project. My current view is that expect/actual is for purely declarative differences — a constant, a function with no runtime state. In a genuinely complex client, fewer things land in that tier than you’d think.

So what do those 31,000 lines of shared code look like

ui/src/commonMain is the entire interface: theme, navigation, cloud drive, transfers, settings, trash, login, plus components. The entry is PikoApp, and each platform assembles its dependencies and passes them in.

On Android the wiring happens in Application:

val clientManager = PikoClientManager(AndroidPikoSessionStore(this, sessionManager), appScope)
services = PikoServices(
    preferences = sessionManager,
    clientManager = clientManager,
    downloadManager = PikoDownloadCoordinator(
        storage = AndroidPikoDownloadStorage(this, sessionManager, appScope),
        segmentDownloader = AndroidPikoSegmentDownloader(this),
        // ...
    ),
    uploadSources = AndroidPikoUploadSources(this),
)
platform = AndroidPikoPlatform(this) { appUpdater }

On desktop the wiring happens in main, same shape, different implementations: DesktopPikoPlatform(settings), DesktopPikoDownloadStorage, FilePikoSessionStore. Session storage is the clearest example, because the shared interface is only 21 lines:

interface PikoSessionStore : SessionStore {
    suspend fun loadLastAccount(): String?
    suspend fun saveLastAccount(account: String)
    suspend fun loadCredentials(account: String): PikoCredentials?
    // ...
}

The Android side goes through DataStore. The desktop side writes files under ~/.piko. The UI and business code know nothing about it.

One contrast here is worth flagging. The interface says what both sides must do, but it can’t govern how far apart the two implementations drift. I read the desktop implementation, and it writes session, account and password into three separate files under ~/.piko, with the password in plaintext. On your own machine that’s fine. On a shared machine, worth thinking about. Same job, same interface, and the rigor of the two sides can differ by a lot.

Pitfalls

The architecture notes record a good number of measured pitfalls. Here are the cross-platform ones.

The two sides’ Compose versions can disagree, and the same line of code may only fail on one of them. The desktop UI library is pinned to Compose Multiplatform 1.12.0, while Android is decided by the BOM. The reason is specific: the skiko that ships with CMP 1.13 wraps the rendering backend inside OnScreenRedrawer, and the playback library it uses needs to grab Direct3DRedrawer straight out of there for D3D11 passthrough, so opening a player window throws. In this project, upgrading CMP isn’t changing one number; it means waiting for the upstream playback library to catch up.

On Android, Compose has to go back to stable. The version catalog says: the 1.13 alpha crashes during fast list scrolling — an interactive ListItem reads the secondary text baseline during measurement, and an aligned child looks up a parent not yet in the table. So the BOM moved to stable, and ui and foundation landed on 1.12.x.

Changing a shared module means compiling both sides. The author put this straight into the file meant for collaborators, because changes to shared and ui hit both entry modules at once, and compiling only one side won’t show it. And the two sides’ material3 versions were never the same to begin with, so the same line of code can absolutely fail on only one.

Adding a preference means touching three places. Once in the common interface, once in the Android DataStore implementation, once in desktop settings storage. Same for the global navigation stack: the main screen’s position lives in the repository layer and is persisted, so overlays like the directory picker have to keep their own path stack — change the repository layer and the main screen’s position moves with it.

Dependencies use api rather than implementation for a reason. shared uses api(libs.cmp.runtime) because the state types it exposes are Compose’s State directly, and consumers can only compile if they can see those types. The counterexample is kotlinx-serialization: the SDK declares it as implementation, so it isn’t transitive, and callers have to pull in their own copy.

One licensing detail: the source is MIT, but the Android APK as a whole is GPLv3. That’s because the bundled mpv and FFmpeg are built with GPL. Fine for your own use. If you want to redistribute, read that carefully.

What it looks like running

Piko’s README has screenshots for each platform. I’m putting two here: Android on top, desktop in the same window below.

What’s worth comparing isn’t the content, it’s the navigation. On a phone the nav bar sits at the bottom; in a desktop window it moves to the left side, and that middle decision looks only at window width, not at what device it is. So shrink the desktop window enough and it turns into the phone layout, and tablet split view goes through the same check. That adaptivity is in the shared code too.

Functionally it does more than I expected: magnet links resolve by work, section and episode, subtitles group with their video, ad files are excluded automatically, and you can preview everything before saving and tick the files you want. Playback progress syncs with the official PikPak client, and both downloads and streaming run eight concurrent connections. It also supports lossless clip extraction, uploads, server-side extraction, whole-drive search, duplicate finding, and viewing drive usage and monthly traffic.

Worth mentioning is how it was built: commit history shows Claude as a co-author, and the README states the requirements for LLM-assisted code — understand the logic of what was added, and verify it on a real device. The author says in his post that his color sense is weak, and this interface is M3 output with manual tuning.

Last

For a small project that needs two platforms, my advice is to carve out shared and ui first and leave them cleanly as commonMain only, with every platform implementation pushed into the two entry modules. That way, every time you feel like taking a shortcut and adding a platform check to a shared module, you’ll pause first.

Those 67 lines of PikoProxySelector stuck with me the most. It looked like the most expect/actual-shaped thing in the project, and it ended up solved by adding a source set. When you have enough tools, you stop reaching for the dumbest one.

Project: https://github.com/NihilDigit/piko

java.lang.IllegalStateException: user 42 not found
	at demo.ChainKt.fetchUser(Chain.kt:11)
	at demo.ChainKt$fetchUser$1.invokeSuspend(Chain.kt)
	at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:34)
	at kotlinx.coroutines.DispatchedTaskKt.resume(DispatchedTask.kt:233)
	at kotlinx.coroutines.DispatchedTaskKt.dispatch(DispatchedTask.kt:152)
	... the next dozen lines are all coroutine internals

One line of your own code, then nothing but framework. You know where it blew up, but not who called it. fetchUser is called from several places in this project, and any of them could have passed in 42.

This is not bad luck. It is how coroutines normally behave. And fixing it takes one dependency.

Why the call chain disappears

The whole point of coroutines is writing async code that looks synchronous. The compiler turns every suspend function into a state machine. When the function “returns,” it is not really returning on the JVM call stack; it hands the result to a continuation and lets the dispatcher decide where and when to continue.

The problem is in that “continue.” At the moment of suspension, the frames in between have already been popped off the JVM stack. Resumption starts on a brand new stack: it begins at the dispatcher and jumps straight into fetchUser’s continuation. loadProfile and renderScreen leave no frames on that stack at any point, so the exception has no way to find them.

So losing frames is not a bug. It is the inevitable result of the mechanism. The Kotlin team knows this and has offered a fix: turning on kotlinx.coroutines.debug enables stacktrace recovery.

It just does not save you here. I ran this example locally and confirmed the property made it into the app JVM:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug=on
java.lang.IllegalStateException: user 42 not found
	at demo.ChainKt.fetchUser(Chain.kt:11)
	at demo.ChainKt$fetchUser$1.invokeSuspend(Chain.kt)
	at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:34)

loadProfile and renderScreen are still missing. The official mechanism only covers some scenarios, and suspend-then-resume — the most common path of all — happens to be outside them.

Decoroutinator takes a different angle

Stacktrace-decoroutinator goes at it by replacing the coroutine resumption implementation wholesale. The author puts it plainly:

Decoroutinator replaces the coroutine resumption implementation. It generates methods at runtime with names that match the entire coroutine call stack.

These methods do nothing except call each other sequentially in coroutine call stack order, creating real JVM stack frames.

In plain terms: it does not try to “guess” the call chain out of the continuation. It actually builds those frames. If exceptions need the JVM stack to find the caller, then give the stack something to find.

The project is Apache-2.0, 374 stars, has taken Kotlin Foundation grants, shipped 2.6.6 on September 10, and the repo had commits in mid-September. For a small tool, that is a healthy maintenance state.

The result first, installation second

I dropped the same source file into three modules, the only difference being whether Decoroutinator is on. First run, the original version:

$ ./gradlew :plain:run
java.lang.IllegalStateException: user 42 not found
	at demo.ChainKt.fetchUser(Chain.kt:11)
	at demo.ChainKt$fetchUser$1.invokeSuspend(Chain.kt)
	at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:34)
	at kotlinx.coroutines.DispatchedTaskKt.resume(DispatchedTask.kt:233)
	...

21 lines of stack, and only 4 frames belong to the demo. package, two of which are the same function.

With the decorator on:

$ ./gradlew :decoroutinated:run
java.lang.IllegalStateException: user 42 not found
	at demo.ChainKt.fetchUser(Chain.kt:11)
	at demo.ChainKt$fetchUser$1.invokeSuspend(Chain.kt)
	at kotlin.coroutines.jvm.internal.DecoroutinatorBaseContinuationAccessorImpl.invokeSuspend(base-continuation-accessor.kt:15)
	at dev.reformator.stacktracedecoroutinator.common.internal.Provider.callInvokeSuspendIfResultIsNotCoroutineSuspended(provider-impl.kt:123)
	at dev.reformator.stacktracedecoroutinator.provider.SharedSpec.$decoroutinator$resume(provider-api.kt:106)
	at demo.ChainKt.loadProfile(Chain.kt:15)
	at demo.ChainKt.renderScreen(Chain.kt:21)
	at demo.MainKt$main$1.invokeSuspend(Main.kt:8)
	...

31 lines, 7 frames in demo.. What matters is not that it got longer. It is that these two lines came back:

	at demo.ChainKt.loadProfile(Chain.kt:15)
	at demo.ChainKt.renderScreen(Chain.kt:21)

renderScreen line 21 called loadProfile, and loadProfile line 15 called fetchUser. A complete call chain, with line numbers. Now you can see at a glance who passed in 42.

Not a character of the code changed. Here are the three ways to install it.

On the JVM, one plugin line is enough

plugins {
  kotlin("jvm") version "2.3.21"
  application
  id("dev.reformator.stacktracedecoroutinator") version "2.6.6"
}

This is the least work. The plugin generates helper methods into your classes at build time, and you need no extra JVM flags at runtime.

The same library has two other ways to enable it, both going through JVM instrumentation instead of build-time generation:

# Option two: JVM startup flag
-javaagent:/path/to/stacktrace-decoroutinator-jvm-agent-2.6.6.jar

// Option three: add the dependency, then call this once before any coroutine starts
import dev.reformator.stacktracedecoroutinator.jvm.DecoroutinatorJvmApi

fun main() {
  DecoroutinatorJvmApi.install()
  // run your code as usual after this
}

The coordinates are dev.reformator.stacktracedecoroutinator:stacktrace-decoroutinator-jvm:2.6.6.

Option three has a side effect worth mentioning up front: it works by dynamically loading a Java agent, and the JVM prints a warning at you —

WARNING: A Java agent has been loaded dynamically
WARNING: Dynamic loading of agents will be disallowed by default in a future release

Today it is only a warning. Future releases will disallow it by default. If your environment cares about that, options one and two are safer.

In a KMP project, the plugin does nothing

This is the pitfall I hit hardest this round, and the main reason I wanted to write this for KMP readers.

Seeing the plugin, the first instinct is to apply it to the multiplatform module. I did that, and the stack did not recover at all. Same as no install. Worse, it threw a different error along the way:

Exception in thread "main" java.lang.NoClassDefFoundError:
dev/reformator/stacktracedecoroutinator/provider/BaseContinuationExtractor
	at demo.MainKt.main(Main.kt:6)

Which means the plugin did rewrite bytecode, but left the classes its own runtime needs outside the classpath. I manually added the three artifacts the plugin injects into a normal kotlin("jvm") module, and the NoClassDefFoundError went away — but the stack still did not recover.

The reason is not hard to work out: the plugin only wires itself into a plain JVM module’s compile task, and a KMP jvm target’s compile task is outside what it takes over. So the bytecode moved a little, and the part that actually generates the “fake call chain” never ran.

For a KMP project the right move is to skip build-time generation and use runtime instrumentation instead. Both of these are tested and working:

kotlin {
  jvmToolchain(21)
  jvm()
  sourceSets {
    jvmMain.dependencies {
      implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
      // Option three needs this; drop the line if you are using the agent
      implementation("dev.reformator.stacktracedecoroutinator:stacktrace-decoroutinator-jvm:2.6.6")
    }
  }
}

// Option two: the agent goes only into the run args, no source or dependency changes
val decoroutinatorAgent by configurations.creating
dependencies {
  decoroutinatorAgent("dev.reformator.stacktracedecoroutinator:stacktrace-decoroutinator-jvm-agent:2.6.6")
}
tasks.register<JavaExec>("runKmp") {
  mainClass.set("demo.MainKt")
  classpath = files(kotlin.targets.getByName("jvm").compilations.getByName("main").output.allOutputs,
                    configurations.getByName("jvmRuntimeClasspath"))
  jvmArgs("-javaagent:${decoroutinatorAgent.singleFile.absolutePath}")
}

Both produced recovered stacks inside the KMP module: loadProfile and renderScreen present, 7 frames in demo..

One more thing has to be said clearly: Native and JS targets are out, and it is not a configuration problem. The library works by building stack frames on the JVM. No JVM, no mechanism. The author was asked in issue #5 whether a multiplatform version was planned, and answered that there is no plan for now. That issue has been open since 2022.

So the real choice for a KMP project is: install it for the JVM/Android side, leave iOS alone. If you are mostly chasing iOS crashes, this article will not help you.

Known pitfalls

The README lists a few, and every one of them is real:

• Android only supports the plugin route, and it depends on MethodHandle, so it needs API 26 (Android 8) or above. On older versions it silently turns recovery off instead of crashing, so it is safe to include.
• R8/ProGuard breaks it. Obfuscation renames the classes the runtime needs, so add decoroutinatorAndroidProGuardRules() to your release rules.
• Coverage disappears when used with Jacoco. This is a Jacoco limitation; the fix is to make Jacoco’s agent run before Decoroutinator’s.
• The Shadow plugin has a known conflict (shadow#882). If you build a fat jar, read the workaround first.
• Robolectric puts its classes in a separate classloader, which makes tests fail. You need to exclude dev.reformator.stacktracedecoroutinator. in packagesToNotAcquire.

Also, if you only want it in tests, the official advice is to apply the plugin in a separate subproject for tests. If that is hard to split out, there is a switch:

stacktraceDecoroutinator {
  androidTestsOnly = true
}

To check whether it actually got installed at runtime, query the status:

DecoroutinatorCommonApi.getStatus { it() }

On Android it can also bundle DebugProbes for you, via embedDebugProbesForAndroid = true, which lets you dump coroutine state at runtime.

Should you install it

I lean yes, especially if someone on the team is still locating coroutine bugs by adding logs and guessing.

What it does is narrow: put real frames on the JVM stack. No API changes, no invasive refactor, and removing it is a one-dependency change. The cost is one more instrumentation layer at runtime, plus the pitfall list above — most of which only show up in Android packaging. A pure JVM project barely notices.

One caution: it changes the resumption implementation itself. So run a pass in staging before shipping to confirm there is no behavior difference, rather than flipping it on in your critical path.

The full comparison project is at https://github.com/trewvip-arch/decoroutinator-kmp-demo

All three modules share one source file, plain / decoroutinated / kmp. Run it once and you see the original of every stack output in this article:

./gradlew :plain:run          # not installed, chain is broken
./gradlew :decoroutinated:run # plugin route, chain intact
./gradlew :kmp:runKmp         # KMP + agent, chain intact
./gradlew :kmp:runKmpInstall  # KMP + install(), chain intact

Environment: Stacktrace-decoroutinator 2.6.6, Kotlin 2.3.21, kotlinx-coroutines 1.11.0, JDK 21, macOS. Every stack output here was actually run.

Google’s adk-kotlin hit 1.0 GA on September 7. 1.1.0 came on September 15, and the Ktor 3.6.0 artifacts landed on Maven Central on September 16. I took those three and built something that actually works: an agent that can go verify for itself whether a given KMP library supports iOS, with the server and the client in the same KMP project.

One thing up front. I stepped on a landmine while writing this: the request body I copied out of the source returned a 400 on a real server, and with no error message at all. It took me the better part of half an hour to pin down. It was a version issue. That gets its own section later, because it’s more worth remembering than the tutorial itself.

What this agent solves

The question KMP developers ask most often is: does this library support iOS?

READMEs often don’t answer it, or answer with something out of date. The authoritative source is the Gradle module metadata the library publishes to Maven Central — that .module file is generated by the build, and what it lists is the platform variants this particular compile actually produced.

So the tool does something very direct: pull down the .module, parse out every variant name, and count how many mention iOS.

@Tool
fun checkLibraryPlatforms(
  @Param("Maven group id, e.g. com.google.adk") group: String,
  @Param("Maven artifact id, e.g. google-adk-kotlin-core") artifact: String,
  @Param("Version to check, e.g. 1.1.0") version: String,
): String {
  val url = "https://repo1.maven.org/maven2/${group.replace('.', '/')}/" +
    "$artifact/$version/$artifact-$version.module"
  // ... fetch, parse, count iOS variants
}

@Tool and @Param are ADK annotations. Why they matter comes later.

Structure: why two modules

adk-kotlin-agent-quickstart/
├── shared/          KMP module
│   └── src/
│       ├── commonMain/   Ktor client + protocol DTOs (shared by jvm / iOS)
│       ├── jvmMain/      CLI entry point + CIO engine
│       └── iosMain/      Darwin engine
└── agent-server/    pure JVM module: ADK agent + HTTP server

It looks like it should fit in one module. It doesn’t. google-adk-kotlin-webserver depends internally on Ktor 2.3.13, while the client needs Ktor 3.6.0. Put them together and Gradle’s “highest version wins” drags the server up to Ktor 3 too, but ADK’s code was compiled against the Ktor 2 API and blows up at runtime.

Not a guess. After it came up I looked at the classpath, and the server really was this set:

ktor-server-netty-jvm-2.3.13.jar
ktor-server-core-jvm-2.3.13.jar
ktor-client-core-jvm-2.3.13.jar
...

The client side is on 3.6.0. Physically separated, everybody’s happy.

Version pinning

KSP has to pair exactly with Kotlin. This is the easiest place to bury a bug. I copied the exact combination the google/adk-kotlin repo uses for its own build:

[versions]
kotlin = "2.3.21"
ksp = "2.3.9"          # bump with kotlin, don't touch it alone
adk = "1.1.0"
ktor = "3.6.0"

Three server dependencies:

dependencies {
  implementation(libs.adk.core)        // agents / models / tools / sessions / runners
  ksp(libs.adk.processor)              // generate tool schemas at compile time
  implementation(libs.adk.webserver)   // expose the agent over HTTP
}

How a tool becomes a schema

This is the biggest difference between ADK for Kotlin and the Python version. Python leans on runtime reflection. Kotlin does it at compile time with KSP.

This one line inside KmpSupportAgent is the key:

tools = KmpLibraryService().generatedTools()

I never wrote a single line of generatedTools() anywhere in the project. After compilation it turns up at:

agent-server/build/generated/ksp/main/kotlin/com/example/adk/server/
├── CheckLibraryPlatformsTool.kt
├── ListAvailableVersionsTool.kt
└── KmpLibraryService_GeneratedTools.kt

The last one contains:

public fun KmpLibraryService.generatedTools(): List<FunctionTool> = listOf( ... )

The upside is no reflection at runtime, which keeps R8/obfuscation, Native images and startup time clean. The cost is that changing a tool signature forces a recompile, and dynamic tool registration is off the table.

The agent itself

object KmpSupportAgent {
  @JvmField
  val rootAgent = LlmAgent(
    name = "kmp_library_platform_agent",
    model = Gemini(name = "gemini-3.1-flash-lite"),
    instruction = Instruction("""
      You are an assistant for Kotlin Multiplatform developers.
      When the user asks whether a library supports a platform, never answer
      from memory. Call `checkLibraryPlatforms` and read the result.
      ...
    """.trimIndent()),
    tools = KmpLibraryService().generatedTools(),
  )
}

A note on @JvmField. Every agent’s rootAgent in the official examples carries it. I copied it at first too and assumed it was required. All it does is turn a Kotlin object property into a real static field (instead of INSTANCE.getRootAgent()), which makes life easier for Java callers. I removed it, recompiled, ran it again — the server still came up and /list-apps still returned. Because AdkServerConfig.inMemory(agent) takes the agent object directly and never goes through reflection. Copying it is fine, just don’t believe it won’t start without it.

One thing I deliberately spelled out in the instruction: platform.type is an aggregate marker. Kotlin/Native targets all report native, and which Apple target it actually is only shows up in the variant name. Leave that out and the model happily reads the word native and draws its own conclusion, when it can’t actually get from native to whether iOS is in there.

Starting the server

fun main() {
  val config = AdkServerConfig.inMemory(KmpSupportAgent.rootAgent)
  AdkDevServer(config).start(wait = true)
}

AdkDevServer hangs a dev UI off the side. The routes look like this:

Three of them you can verify directly:

$ curl -s localhost:8080/list-apps
["kmp_library_platform_agent"]

$ curl -s localhost:8080/version
{"version":"1.1.0","language":"kotlin","language_version":"21.0.10"}

$ curl -s -X POST -H "Content-Type: application/json" -d '{}' \
    localhost:8080/apps/kmp_library_platform_agent/users/demo-user/sessions
{"id":"b86f7324-81db-49df-8007-1700077ebdb4","appName":"kmp_library_platform_agent",...}

/run_sse uses plain SSE, one data: <json> line per event followed by a blank line. The server implements it by hand because Ktor 2.x has no SSE plugin. The comment in the source is a good read:

Ktor 2.x has no SSE plugin, so stream manually. Use async respondBytesWriter, not respondTextWriter, whose blocking bridge parks via a coroutines internal gone in 1.11.0.

Ktor 2.x has no SSE plugin, so stream it by hand. Use the async respondBytesWriter, not respondTextWriter — its blocking bridge depends on an internal implementation that was already removed in kotlinx-coroutines 1.11.0.

In other words, the comment is warning you about itself: bump the coroutines version and this API may break.

Client: written in commonMain

This is where the actual cross-platform part lives. Request building and SSE parsing all sit in commonMain without touching platform APIs:

fun run(prompt: String, sessionId: String? = null): Flow<Event> = channelFlow {
  val sid = sessionId ?: createSession()
  httpClient.preparePost("$baseUrl/run_sse") {
    contentType(ContentType.Application.Json)
    setBody(RunRequest(appName, userId, sid, Content.text("user", prompt), streaming = true))
  }.execute { response ->
    val channel = response.bodyAsChannel()
    while (true) {
      val line = channel.readLine() ?: break
      if (!line.startsWith("data:")) continue
      val payload = line.removePrefix("data:").trim()
      if (payload.isEmpty()) continue
      val event = json.decodeFromString<Event>(payload)
      send(event)
      if (event.turnComplete) break
    }
  }
}

Only the engine is per-platform, closed off behind one expect/actual:

// commonMain
expect fun createPlatformHttpClient(json: Json): HttpClient

// jvmMain
actual fun createPlatformHttpClient(json: Json) = HttpClient(CIO) { ... }

// iosMain
actual fun createPlatformHttpClient(json: Json) = HttpClient(Darwin) { ... }

The loop exits on two fields: partial marks a streaming chunk that isn’t finished, turnComplete marks the end of the turn. Without turnComplete you have to infer it from the connection closing, and that drags you all the way to a timeout.

That 400

Now the trap I mentioned at the top.

I wrote the request body from my own understanding, using the app_name / user_id / new_message naming — after all, that’s how Python ADK does it, and I really did see ApiModels.kt in the repo source hanging an alias on every multi-word property:

@JsonNames("app_name") val appName: String,
@JsonNames("user_id") val userId: String,

Send it:

HTTP/1.1 400 Bad Request
Content-Length: 0

No body, no stack trace, not a single ERROR line in the server log. So I tried camelCase and it came back 500 — which means deserialization passed and the failure happened further down (the model call). In other words:

• camelCase → parses, walks all the way to the Gemini SDK
• snake_case → never reaches business logic

@JsonNames is the “alternate name” mechanism in kotlinx-serialization. In theory both spellings should be accepted. I even wrote a minimal repro with the same annotation and the same Json config, and snake_case parsed fine. So it isn’t kotlinx.

It’s the version. I went and read the tag:

v1.1.0's ApiModels.kt:
  data class AgentRunRequest(
    val appName: String,
    val userId: String,
    ...
  )
  → not a single @JsonNames

The commit that added those two aliases, 94dcdd13 (feat: accept snake_case and camelCase in web server request bodies), is dated 2026-09-15, landed on main, and went in after the v1.1.0 tag. There’s also a test file in the repo that says the server reads snake_case — it describes main’s behavior, not the 1.1.0 you can actually download.

Decode snake_case with the real AgentRunRequest and the real adkJson and the error is unambiguous:

kotlinx.serialization.MissingFieldException: Fields [appName, userId] are required
for type with serial name '...AgentRunRequest', but they were missing

So the rule is: for 1.1.0, always camelCase. snake_case waits for the next release.

The lesson here isn’t “read the tag”. It’s “reading main’s source is not the same as reading the version you depend on”. If I hadn’t actually sent the request and tried it, the sample code in this post would be copied from unreleased behavior and 400 on the first run.

If you want a self-check trick, the /version endpoint is genuinely useful — the server reports its own version, and then you compare against that tag’s source, which beats guessing against main.

What the tools actually print

This part doesn’t need a model. The tools are pure Kotlin and run directly:

./gradlew :agent-server:runTools

First, cut into ADK itself:

com.google.adk:google-adk-kotlin-core:1.1.0
platform.type values: androidJvm, common, jvm
variants mentioning iOS: 0
Verdict: no iOS target. This library cannot be consumed from an
iosArm64 / iosSimulatorArm64 source set.

Now Ktor for contrast:

io.ktor:ktor-client-core:3.6.0
platform.type values: common, js, jvm, native, wasm
variants mentioning iOS: 9
  - iosArm64ApiElements-published
  - iosSimulatorArm64ApiElements-published
  - iosX64ApiElements-published
  ... (9 total, across Api / Metadata / Sources)
Verdict: iOS targets are published, so Apple targets can depend on it.

Same function, same decision logic, and the two libraries come out opposite. That contrast gets its own note below.

Version lookup and the error path while we’re here:

com.google.adk:google-adk-kotlin-core — latest=1.1.0
recent: 0.5.0, 0.6.0, 0.7.0, 0.8.0, 0.9.0, 1.0.0, 1.0.1, 1.1.0

Could not fetch metadata for com.google.adk:does-not-exist:9.9.9 (HTTP 404).
The coordinates or version are probably wrong.

The error path returns a human sentence instead of throwing. What the tool hands back is a string. An exception cuts the turn off right there, and the model can’t even say “that library doesn’t exist”.

The cross-platform part

shared is genuinely cross-platform. I actually compiled it:

$ ./gradlew :shared:compileKotlinIosSimulatorArm64 :shared:compileKotlinIosArm64
BUILD SUCCESSFUL in 33s

Same commonMain code, both JVM and iOS pass.

agent-server can only ever run on JVM (or Android). It’s not a config problem — the Gradle variants google-adk-kotlin-core publishes to Maven Central are only common / androidJvm / jvm, and google-genai-kotlin is the same. No iOS variant, no Native variant.

So if you want to run the agent on iOS there are two roads: put it on the server and let iOS be a client only (which is the structure of this project), or wait for upstream to add Native support. I filed an issue on the ADK repo about it, #504, no reply yet.

Side note: this “agent lives on the server only” split is actually the more sensible call in most cases — model keys never ship in the client bundle, and tool execution plus permission checks stay somewhere you control.

How to run

export GOOGLE_API_KEY=...
./run-stack.sh

The script does four things: installs the server and starts it on 8080, polls /list-apps until it’s really up, runs the client, then tears the server down and passes the client’s exit code through untouched.

(The first version of that script leaked: it started the service through the launcher script Gradle generates, and that script runs java as a child process. kill only killed the wrapper, so the server was orphaned and sat on 8080 forever. Starting java directly is what makes $! the server itself.)

Or split it:

./gradlew :agent-server:run     # terminal 1
./gradlew :shared:runClient     # terminal 2

Last thing, let me be clear about how far I verified, so you don’t hit a step down when you follow along.

What works: the whole project compiles (including KSP codegen); the server starts; /list-apps, /version and session creation all return 200; the client’s /run_sse request is accepted by the server and reaches the model call layer in com.google.genai.kotlin.

What doesn’t: a real model conversation. That needs your own Gemini API key, which I don’t have. So I didn’t paste the full conversation output for the “does it support iOS” question from the top of the post. You only see that with a valid key attached, and I’m not going to paste output I never ran.

Code is at https://github.com/trewvip-arch/adk-kotlin-agent-quickstart

Apache-2.0. Open an issue in the repo if something’s wrong.

When I introduced ADK for Kotlin 1.0, I wrote a line: “if iOS support lands later, that’s one codebase reused across three platforms.” That phrasing was slippery. Put it next to “KMP core” and it reads far too easily as “iOS should just work.”

Then a reader asked: it’s written in Kotlin Multiplatform, so doesn’t iOS already work?

I should not have glossed over that. So this time I went and checked myself, and not by reading what the docs say. I took the build artifacts apart.

The conclusion, up front: no. And this is not something one extra target line fixes.

There is a hard way to check what a KMP library actually supports

Method first, because the method is more useful than this particular conclusion.

When a KMP library publishes, it generates a Gradle module metadata file (the .module file) listing every platform variant the library actually compiled. It is a build system artifact, not marketing copy someone wrote. A library can claim it “supports multiple platforms,” but if the metadata has no variant for one, the build simply cannot resolve it and compilation fails outright.

So to learn a library’s real platform coverage, one command is enough:

# Generic recipe: swap the package path in for group
curl -sL "https://repo1.maven.org/maven2/com/google/adk/google-adk-kotlin-core/1.1.0/google-adk-kotlin-core-1.1.0.module" \
  | python3 -c "
import sys, json
d = json.load(sys.stdin)
vs = d.get('variants', [])
plats = sorted({v['attributes'].get('org.jetbrains.kotlin.platform.type', '?') for v in vs})
names = [v['name'] for v in vs]
ios = [n for n in names if 'ios' in n.lower()]
print('platform.type :', ', '.join(plats))
print('含 ios 的变体 :', len(ios), '个')
for n in ios[:4]: print('   -', n)
"

Run it against ADK for Kotlin and the output is:

platform.type : androidJvm, common, jvm
含 ios 的变体 : 0 个

How to read that result

One thing is easy to misread. I nearly confused myself the first time: the iOS target does not show up in platform.type.

Kotlin/Native is uniformly tagged native under platform.type. Which Apple platform it is shows up in the variant name. So the correct read is both layers together:

• platform.type contains native → the library compiles Kotlin/Native targets
• variant names include iosArm64 / iosSimulatorArm64 / iosX64 → only then does iOS actually work

Compare against a library that definitely supports iOS, Ktor say:

platform.type : common, js, jvm, native, wasm
含 ios 的变体 : 9 个
   - iosArm64ApiElements-published
   - iosArm64SourcesElements-published
   - iosSimulatorArm64ApiElements-published
   ...

64 variants, 9 with ios. That is what “actually supports iOS” looks like.

ADK has 8 variants. platform.type is only androidJvm / common / jvm, and variants with ios number zero.

I checked every version while I was at it, including the latest 1.1.0. No iOS anywhere.

The source layout agrees. Under core/src/ the source sets are:

androidMain
commonJvmAndroidMain      ← note the name
commonMain
jvmMain
(no iosMain)

And the target declarations in core/build.gradle.kts are just jvm() plus Android. Not one line of iOS.

Under the com.google.adk group on Maven Central, the number of iOS-related artifacts is zero.

Three walls, each harder than the last

Knowing there is no iOS is not enough. It is worth seeing why, because the answer decides how much “just do it yourself” costs.

Wall one: they deliberately split out a layer called commonJvmAndroidMain

The source set name is the answer. It is the part JVM and Android share. It dependsOn(commonMain) and contains:

reactive-streams is the key signal. It is the JVM world’s reactive streams spec, and nothing like it exists on Apple platforms. ADK’s Java interop signatures are built on top of it. The source comment puts it as “the api-vs-implementation question for the Java-interop signatures”.

The authors know perfectly well the code has two layers: one that is genuinely cross-platform common logic, and one that is “shared by JVM and Android.” The distinction is deliberate, because right now they only want to support those two platforms.

Wall two: jvmMain is all JVM-only too

gson, google-cloud-storage, mcp (the Java SDK for MCP), ktor. Neither Google Cloud Storage nor the MCP Java SDK has an iOS version, so session persistence and cloud storage would need a separate iOS implementation.

Wall three (the fatal one): google-genai-kotlin does not support iOS either

commonMain has this line among its dependencies:

commonMain {
  api(libs.google.genai.kotlin)   // com.google.genai:google-genai-kotlin:1.0.0
}

I ran the same method on it:

Platform variants: androidJvm, common, jvm

Google’s own Kotlin SDK for generative AI has no iOS target either.

And it is an api dependency, not implementation. That means it sits on every consumer’s compile classpath. There is no way around it.

So the truth is: to get ADK for Kotlin running on iOS, you first have to port Google’s GenAI Kotlin SDK to iOS. That is a whole other SDK’s worth of work, and it lives in Google’s hands, outside anything you can change.

So what does “compile it myself with iOS support” actually mean

Not a fork plus three target lines. Roughly:

The last two are not in your repo. Especially the third: that means moving someone else’s code.

1.1.0’s direction makes this clearer, not murkier

ADK for Kotlin 1.1.0 shipped September 15 (1.0 went GA September 7, 1.0.1 on September 10 — fast cadence). Look at what it adds:

• AppFunctionsToolset, wiring into Android’s AppFunctions
• An Android AppFunctions conversion layer
• Injects the app’s AppFunctions descriptions into model instructions
• A BaseFutureSkillSource base class for Java, plus Java examples of long-running tools
• The Plugin.onRunError callback

The fixes land in the same area: unknown tool names no longer kill the whole call, session recovery is fixed for workflow agents, and a turn survives when an MCP server rejects a request.

Look at where the weight sits. The most substantial new capability in 1.1.0 is the Android AppFunctions line — letting an agent call functions an Android app exposes.

Which tells you the iOS gap is not an oversight. It is a strategic choice. Google’s energy is on the Android side: Gemini Nano, ML Kit, LiteRT-LM, Firebase AI, and now AppFunctions, all laid down for Android. ADK for Kotlin’s “Kotlin Multiplatform” is currently shorthand for “Kotlin Multiplatform (Android + JVM).” That common layer exists for those two platforms to share, not as groundwork for iOS.

So what do you do if you build for iOS

Three paths, in my order of preference.

Path A: run the agent on the server, keep iOS as a client (recommended)

ADK for Kotlin’s JVM leg is fully usable. That is one of its main battlegrounds, not a crippled build.

So run the agent logic on a server JVM and have iOS call it over HTTP. The ADK ecosystem even has the piece for this: the A2A (Agent-to-Agent) protocol, which is exactly what the google-adk-kotlin-a2a module is for (it is also JVM-only, but servers are JVM anyway).

The cost is losing on-device capability. Privacy, offline and low latency no longer all fit. The upside is you can ship today with zero porting risk.

For most products that trade is worth it: your agent already calls a model over the network, so it was never purely offline.

Path B: write your own “ADK-lite for iOS”

Take only the design ideas from commonMain — orchestration, sessions, memory, tool schemas — and rebuild them on iOS out of parts the KMP ecosystem already has:

• Ktor for networking (KMP supports iOS natively)
• Call the Gemini REST API directly, bypassing google-genai-kotlin
• SQLDelight for persistence

But then you are not “using ADK.” You are reimplementing it from its design. Business logic can be shared. The framework gets rewritten.

Path C: wait, or push

1.0 to 1.1.0 was 8 days. Iteration is not slow. If iOS is on the roadmap, waiting pays off.

One thing I did while I was at it: I opened an issue in the repo to get this settled —

https://github.com/google/adk-kotlin/issues/504

I asked three things: is iOS on the roadmap, what is the actual blocker (I suspect it is the GenAI Kotlin SDK missing a native target, not ADK itself), and what architecture does the team recommend today.

Why I think the issue is worth something: the repo only has a handful of issues total, and one feature request filed last month got a need attention label within two days. The team is watching. If you need iOS, go add a thumbs up. Demand signals beat everything else.

The method is worth more than the conclusion

Back to the method from the top.

Next time you evaluate any KMP library — ADK, or some other “cross-platform” framework — do not just read the README and release notes. The README will say things like “runs on all supported platforms,” which looks comprehensive, but who defines “supported” and how far it goes is usually left out.

Go read the .module file. It lists what the build system can actually resolve:

• iosArm64 / iosSimulatorArm64 present → iOS really works
• js / wasmJs present → web really works
• only common / jvm / androidJvm → JVM and Android only

One curl saves you two weeks of refactoring.

That is the biggest cognitive trap in KMP these last couple of years: “built on KMP” and “works on all KMP platforms” are different claims. The first is about how the code is organized. The second is about what you actually get. ADK for Kotlin is a good example — the core really is a carefully designed cross-platform architecture, and right now it chooses to keep the iOS door shut.

How I verified: read the Gradle module metadata for every version of com.google.adk:google-adk-kotlin-core (including 1.1.0) on Maven Central, the core/build.gradle.kts and core/src/ source set layout, the platform variants of com.google.genai:google-genai-kotlin, and cross-checked the release notes for ADK for Kotlin v1.0.0 / v1.0.1 / v1.1.0.

Android, iOS, desktop. Those are the three places KMP has covered solidly for the last few years. The fourth leg is WebAssembly, and last week’s Chasm 2.0 release is on that line.

Before looking at it, there is one easy confusion to clear up first, or you will get the whole roadmap wrong.

Chasm: a Wasm runtime written in Kotlin

Its self-description is one line: Chasm is a WebAssembly runtime built on Kotlin Multiplatform. In other words, a WebAssembly runtime built with KMP.

Mind the word order. It is a thing that runs Wasm, written in Kotlin. It is not Kotlin compiled to Wasm. Those two point in opposite directions. More on that shortly.

The project sits at 227 stars now (221 when I wrote the first draft) and supports the Wasm 3.0 spec, minus Memory64 and vector instructions. It implements the Tail Call, Typed Function References, Wasm GC, Multiple Memories, Exception Handling and Wide Arithmetic proposals. A runtime that handles GC and exceptions is not a toy anymore.

2.0 shipped September 16, and the author says plainly that it is full of breaking changes: a new Android target (min SDK 28); the JVM target floor raised to JDK 17; the Host Function API rewritten, from passing a list of values in and returning a list of values out to reading and writing the runtime stack directly; the deprecated macosX64 and iosX64 targets removed; the Gradle plugin no longer supporting AGP 8.

One note on progress: as of writing this (September 21), there are no commits or releases after 2.0. The author is collecting feedback. That is the right pace. A major version just shipped, hold steady before iterating.

What caught my attention most is one trade-off the author spells out:

I want to do everything within the native constraints of each platform, and that means no FFI or anything like it.

Anyone who does cross-platform work knows the weight of that sentence. The cheap way to let a JVM call a Wasm runtime is a thin C interface on top. He took the expensive path: a native implementation per platform. The cost is double the work. The payoff is no FFI dependency and no ABI compatibility headaches.

Don’t mix them up: these two point opposite ways

I suspect a lot of people see Kotlin and Wasm next to each other and jump straight to: does KMP support Wasm now?

No. These are two things pointing in opposite directions.

Kotlin/Wasm is the official compilation target. Its job is compiling Kotlin source into .wasm and shipping it off to the browser. Direction: outbound.

Chasm does the opposite work: take an existing .wasm file, execute it in its own runtime, running on JVM, Android and iOS. Direction: inbound.

Mix those two up and your understanding of the whole roadmap is off.

The fourth leg means the official one

The official docs are plain about it: Kotlin/Wasm compiles Kotlin to WebAssembly, for Compose Multiplatform web apps or for running in a standalone Wasm VM outside the browser (the latter reaching platform capabilities through WASI).

Two points.

One: the Web platform target for Compose Multiplatform is Kotlin/Wasm. Which means UI written in Compose really does run in a browser, sharing the same UI code with Android, iOS and desktop. That is what the fourth leg actually means.

Two: there are hard browser requirements. It needs the WebAssembly garbage collection (WasmGC) and exception handling proposals. I assumed Safari would be the problem child; after checking the official material, the bar is lower than I expected. The versions:

The Safari row deserves its own explanation. 18.2 landed at the end of 2024, shipping as iOS 18.2 / macOS 15.2. On iOS and iPadOS, Safari rides along with the OS; users do not update it separately. So translated, that requirement is not don’t use Safari, it is don’t let your users sit on ancient hardware. Get that one wrong and the whole technology decision flips.

One more detail worth knowing: the exception handling proposal now comes in an old and a new version. The Kotlin toolchain supports both, but the wasmJs target uses the legacy one by default, for wider compatibility. Switching to the new one takes explicit configuration.

Measured: what the Wasm side costs

Measured on a real KMP project on this machine, with both a JS and a Wasm target. First the numbers from my first draft, on Kotlin 2.4.0 + CMP 1.11.1:

$ ./gradlew :app:webApp:wasmJsBrowserDistribution
→ BUILD SUCCESSFUL in 4m 10s
→ 50 actionable tasks: 50 executed

Four minutes ten, and that is with dependencies already cached.

The artifacts:

The two wasm files add up to 14.2 MiB; the whole directory is about 15MB.

Then I temporarily bumped the project to Kotlin 2.4.20 + CMP 1.12.0 and ran it again:

$ ./gradlew :app:webApp:wasmJsBrowserDistribution
→ BUILD SUCCESSFUL in 3m 33s
→ 50 actionable tasks: 48 executed, 2 up-to-date

Not dramatic, but the direction is clear: builds half a minute faster, app wasm down 0.30 MiB, about 5%.

I should be clear that this is not a strictly even comparison. Two tasks hit cache on the second run, so part of that 3m33s is savings rather than the compiler getting faster. But the conclusion that this line keeps getting faster and smaller holds.

Compare the desktop numbers, packaged for JVM: 133MB, roughly nine times as much. The reason is simple. Of those 133M, 77M is the JVM runtime and 20M is Skia. In the browser neither gets bundled. No JVM, and rendering goes straight to the browser’s Canvas and WebGL.

That is the most concrete benefit of the Wasm side: you do not carry the runtime.

webpack does throw a string of warnings during the build, saying several assets exceed the recommended 244 KiB ceiling. It names webApp.js at 529 KiB and both wasm files. 8.25 MiB is over thirty times its suggestion. Meaning: without code splitting and lazy loading, a user downloads 15MB on first open. On a weak connection that is a real experience problem.

What the Web side picked up this month

While bumping versions I went through two sets of release notes. A few items matter a lot if you build Chinese-language apps, so they get their own section.

Web changes in CMP 1.12 (August 25):

• Automatic Noto font loading. When a glyph is not covered by the theme font, it loads Noto on demand. Anyone building Chinese or multilingual apps knows what that means: rare characters used to render as tofu blocks
• Two tofu fixes specifically: unknown glyphs on a text field’s first draw, and tofu on the second and later draws of the same text
• Fixed a bug where div#cmp_a11y_root was sized 0×0. That one is serious: it made everything Compose rendered invisible to hit-test based accessibility tools
• Wheel events now carry both axes, which fixes diagonal scrolling. Precise trackpad gesture detection on Chrome. Fixed pointer state left dangling after pointercancel, which system gestures, palm rejection and device disconnects all trigger
• Also fixed: focusing a text field on a mobile browser could hide the soft keyboard
• The web target also picked up haptic feedback support and Modifier.keepScreenOn

CMP 1.13.0-alpha01 (September 10):

• The deprecated compose.web.targets(...) Gradle plugin API is gone. If it is still in an old build script, the upgrade fails outright
• Experimental support for system window insets on the web
• A new experimental API for rendering WebGL textures
• When the browser or device lacks WebGL2, you get a message you can understand instead of an opaque crash

Kotlin 2.4.20 (September 7) moved the Wasm backend a lot more. This release notes page has sixty-odd Wasm entries. Three you will hit sooner or later:

• Range checks are on by default. Better safety, a bit of performance in exchange
• wasmExports is deprecated and banned. If you reach into wasm exports directly through JS interop, the upgrade breaks
• Prototyping suspend functions generated via the stack-switching proposal. Not usable yet, but worth remembering the direction. It is the official path for async in Wasm

One upgrade caveat: refactoring callable references and generating a unified fun interface base class broke klib binary compatibility. If your dependencies include someone else’s published wasmJs klib, they may need to republish. This kind of break is far more sensitive in the multiplatform ecosystem than on the JVM. Run a build before upgrading; do not find out at release time.

Where it fits, where it doesn’t

The best deal is when you already have a KMP project and want a web client for free. Same as desktop: add a target. Internal tools and admin backends work too. You do not care about a 15MB first load, you care about one codebase.

Where it really pays off is logic-heavy apps with relatively fixed UI. The more business logic you share, the better the math.

Going the other way: consumer marketing pages and lightweight sites, do not bother. A 15MB first load plus old-browser incompatibility is a bounce. SEO-dependent products are out too, because crawlers cannot see content rendered by Wasm. If Web is your only platform, plain React or Vue is less trouble.

The test compresses to one question: is your core value the Kotlin code you already wrote? If yes, use Wasm. If not, do not force it in the name of technology uniformity.

Appendix: a minimal working project

Three steps to a running app.

Step one, add the target in build.gradle.kts:

plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.composeMultiplatform)
    alias(libs.plugins.composeCompiler)
}

kotlin {
    @OptIn(org.jetbrains.kotlin.gradle.ExperimentalWasmDsl::class)
    wasmJs {
        browser()
        binaries.executable()
    }

    sourceSets {
        commonMain.dependencies {
            implementation(compose.runtime)
            implementation(compose.foundation)
            implementation(compose.material3)
        }
    }
}

Step two, write the entry point at src/wasmJsMain/kotlin/main.kt:

import androidx.compose.ui.ExperimentalComposeUiApi
import androidx.compose.ui.window.ComposeViewport
import kotlinx.browser.document

@OptIn(ExperimentalComposeUiApi::class)
fun main() {
    ComposeViewport(document.body!!) {
        App()
    }
}

Step three, put the UI in commonMain, shared by all three platforms:

@Composable
fun App() {
    MaterialTheme {
        var count by remember { mutableStateOf(0) }
        Column(Modifier.padding(24.dp)) {
            Text("Hello, Wasm!")
            Button(onClick = { count++ }) {
                Text("点了 $count 次")
            }
        }
    }
}

Run it:

./gradlew wasmJsBrowserDevelopmentRun   # dev mode, with hot reload
./gradlew wasmJsBrowserDistribution     # production bundle

ComposeViewport is Compose Multiplatform’s mount point on Web/Wasm, roughly the same role as setContent on Android or application on desktop. So the integration cost of the fourth leg is one target and one entry function, with the UI code still shared.

How to use Chasm

Back to the project from the opening. Here is what using it looks like, the minimal example from the README:

plugins {
    id("io.github.charlietap.chasm.gradle") version "3.0.0-2.0.0"
}

chasm {
    modules {
        create("ExampleService") {
            binary = layout.projectDirectory.file("src/main/resources/example.wasm")
            packageName = "com.example"
        }
    }
}

With that in place, the build reads your .wasm file and generates a Kotlin class, ExampleService, where every exported function becomes a Kotlin function you can call directly. You use an existing Wasm module like an ordinary Kotlin library.

Underneath is a single Wasm VM abstraction: on JVM and native platforms it uses Chasm’s own implementation, in the browser it reuses the host’s built-in VM.

What does that solve? Say you have a C/C++/Rust library compiled to Wasm and you want it inside an iOS app. That used to mean writing FFI glue. Now you call it as a Kotlin library. Or take a cross-platform plugin system, where plugins ship as Wasm and the host executes them.

That is the real reason Chasm deserves its own section. It shows the other half of what Wasm can do.

My take

Chasm and Kotlin/Wasm in the news at the same time is a good thing. One sends Kotlin out, one brings Wasm in; they connect the two from opposite directions. Two-way connection like that means the ecosystem is growing some depth.

The real barrier for Wasm is not technology, it is size and compatibility. A 15MB bundle, browser requirements for GC and exception handling: those are hard commercial constraints, not engineering fastidiousness. When I measured that 4m10s build time I thought, this technology is mature now. But mature does not mean right for your product.

One more thing: these four KMP surfaces are nowhere near equal. Android and iOS have a decade behind them, desktop five or six years, Web/Wasm two or three. Holding them to the same standard is unreasonable. The smoothness you are used to on Android will mostly need re-learning on Wasm.

If you want a web client, my advice is to add a Wasm target to your existing project first and run a Hello World. The config above, half an hour to verify. The important part is in your existing project. You will hit real problems immediately: whether your dependencies publish wasmJs variants (the most common blocker), whether your expect/actual declarations miss a wasmJs branch, how much build time you add. A toy project will not show you any of that; only real dependencies expose it. Half an hour hitting the wall is a much better trade than two weeks of refactoring followed by discovering the library does not support it.

Will you add a web client to your KMP project? Is a 15MB first load acceptable? Comments are open.

Sources: the CharlieTap/chasm repo and the 2.0.0 release notes; the official Kotlin docs on Kotlin/Wasm and “Supported versions and configuration”; the official WebAssembly roadmap for GC support versions; the Compose Multiplatform 1.12.0 and 1.13.0-alpha01 release notes; the Kotlin 2.4.20 release notes; a Reddit r/Kotlin thread. Test environment: Mac mini (M4, 16GB), project is a KMP app with both JS and Wasm targets, built once under Kotlin 2.4.0 + CMP 1.11.1 and once under Kotlin 2.4.20 + CMP 1.12.0 (the upgrade was temporary; the project was restored afterward).

Apple’s M6 benchmarks have been trickling out the last couple of days. Single-core about 24% above the M4 part, multi-core about 48%, and multi-core straight up matches M3 Max — a mid-range chip tying the previous flagship on multi-core is genuinely wild.

On the GPU side, 12 cores pulled 4,071 single-core and 22,783 multi-core on Geekbench, roughly 20% above M5.

And then I started seeing people discuss it: chips are this fast now, should we build out desktop too?

So I tried it on a project of my own. The conclusion is a bit of a letdown: this has basically nothing to do with chip benchmarks.

What I actually ran

The machine is a Mac mini, M4, 10 cores, 16G of RAM. The project is a KMP + Compose Multiplatform AI chat client, with shared holding the shared logic and desktopApp as the desktop entry point.

Packaging is one command:

./gradlew :desktopApp:createDistributable

Ran it twice: 22 seconds the first time, 8 the second. Both fast — but dependencies were already downloaded by then and the code hadn’t changed much. The real first cold build (fetch dependencies, compile Kotlin, generate the runtime image) is measured in minutes.

Fast is fast, but that’s not the point. The last number is:

$ du -sh lange.aichat.app
133M

One hundred and thirty-three megabytes. For a chat client.

It gets interesting when you break it open:

77M is the JVM itself, plus 20M of Skia, so the floor just to make the thing run is 97M. The part you wrote yourself is maybe a few hundred K. And that 77M is already after one pass through jlink, not the raw size.

So the account is clear: Compose Desktop is pleasant to write, but the distribution cost is sitting right there. Unless you replace the JVM premise (the GraalVM native-image road), a hundred-odd megabytes is the norm.

If M6 is this much faster, where does it actually help

Compilation. Kotlin compilation, Gradle parallel tasks, native linking — these are all multi-core work, and 48% more multi-core genuinely shortens build times.

I also measured another target in the same repo while I was at it:

./gradlew :app:webApp:wasmJsBrowserDistribution
→ BUILD SUCCESSFUL in 4m 10s

4 minutes 10 seconds, all 50 tasks run, CPU and memory pegged. For anyone running several builds a day, this is the multi-core gain you feel most directly.

And end users?

For a chat client, the bottlenecks users can feel are these: cold start — JVM loading plus Compose init, which is single-core and IO, so multi-core barely helps; scrolling and animation — that’s Skia, and 20% more GPU is overkill for a 2D UI; first screen — that’s the network.

M6 could be twice as fast and users still wouldn’t feel your app get faster.

So should you build the desktop app or not

Here’s how I see it.

If you already have a KMP project and want one more platform, just add it. The shared logic is already there, it’s one more entry point. Internal tools and developer tools too — you’re only installing it on your own team’s machines, nobody cares how big the bundle is.

What genuinely deserves its own project is a different class of need: reading and writing files locally, multiple windows that stay resident in the background, running models on the machine. Those are things desktop can do and phones can’t. In that case 133M is nothing — users are installing a tool, not a toy.

Conversely, be careful with lightweight consumer utilities. Nobody downloads 133M for a little weather app. Same for hard cold-start requirements: you can’t route around the JVM cold-start curve, unless you go GraalVM.

Side note, Compose Multiplatform 1.13 is already working on AppCDS and AOT (the 1.13.0-alpha01 notes mention “significantly faster app startup”). If you’re hesitating right now because startup is slow, you can wait one or two releases.

Last

M6 is great. Builds get faster, and for people typing code every day that’s a real gain.

But it doesn’t change the desktop trade-off. What holds you back is bundle size and cold start, and the chip has nothing to do with either. If your motivation is “capture the new hardware dividend”, you may be looking in the wrong place — the real desktop dividend is in packaging technology (jlink, AppCDS, GraalVM), not CPU benchmarks.

If you’re already doing KMP, desktop is actually the cheapest end to add: shared is written, add an entry point and you have one more platform. That reason has nothing to do with chips, and I think it’s more solid than a benchmark score.

Would you add desktop to your project? How big a bundle can you live with? Comments are open.

Test environment: Mac mini (Apple M4, 10 cores, 16GB), macOS 27.0, JDK 21.0.10, Kotlin 2.4.0 + Compose Multiplatform 1.11.x. M6 scores come from leaked Geekbench results and public reporting from cnBeta, Notebookcheck, Phoenix Tech and others.

Starting with yesterday’s news: Claude Code 2.1.277 now supports AGENTS.md (September 18).

The Register’s headline was blunt: “Anthropic decides to support OpenAI’s markdown instruction spec.”

If you don’t live inside AI coding tools every day, you might think: it’s a config file name. Who cares?

It matters. Because this whole standoff started with a hard line the Shopify CEO said in public.

Rewind to August 26. Shopify CEO Tobi Lütke posted on X:

I am considering banning Claude Code at Shopify until they are willing to read AGENTS.md, .agents/skills and similar files.

An e-commerce giant threatening to ban a mainstream AI coding tool company-wide — over nothing more than its refusal to read one markdown file.

And the reason he gave is, to me, worth more than the news itself:

Both AGENTS.md and CLAUDE.md apply recursively down the directory tree. When thousands of developers maintain one monorepo, some directory will inevitably be missing a file, and the result is that some developers end up with an agent that has had a chunk of its brain cut out.

We solved it with automation, but that is a stupid complexity tax, and we should not have to pay it at all.

“An agent with a chunk of its brain cut out” — if you have ever maintained a large repo, that one sinks in.

First, what AGENTS.md actually is

The official definition is one sentence:

Think of AGENTS.md as a README for agents.

A README for agents.

A README is for humans: how to get up and running fast, what the project does. AGENTS.md holds what the agent needs but does not belong in a README: build steps, how to run tests, code conventions, a few hard rules.

Its standing today is higher than a lot of people realize:

• Adopted by 60,000+ open source projects
• Started as a collaboration between several: OpenAI Codex, Amp, Google’s Jules, Cursor, Factory
• Now stewarded by the Agentic AI Foundation under the Linux Foundation

The minimal example from the official docs looks like this:

# AGENTS.md
## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons

That is all it is. No schema, no special syntax. Just markdown.

What makes it actually useful: one file works across multiple agents. Codex, Cursor, Jules, Copilot and Claude Code all read it, so you are not maintaining a config per tool.

Side note: Claude Code insisted on its own CLAUDE.md for a long time. Developers started asking in August 2025, the issue collected nearly 5,000 GitHub reactions, and it was finally closed as won’t fix. It took Shopify threatening a ban to get support on September 18.

Why one file escalates into a platform engineering problem

Plenty of people will think: it is just getting Claude Code to read one more file. Why would Shopify escalate to a company-wide ban?

Because in a monorepo with thousands of people, one file format discrepancy turns into chaos you cannot control.

The mechanism Lütke described is worth copying down:

monorepo/
├── AGENTS.md          ← global rules (tech stack, commit conventions)
├── backend/
│   └── AGENTS.md      ← backend-specific (do not touch db/migrations)
├── mobile/
│   └── AGENTS.md      ← mobile-specific (packaging, signing)
└── infra/
    └── AGENTS.md      ← infrastructure-specific

AGENTS.md applies nearest-first — the agent reads the closest one in the current directory and inherits the rules above it.

That is where the trouble starts:

• Say the team uses both Cursor (reads AGENTS.md) and Claude Code (only reads CLAUDE.md)
• Someone writes AGENTS.md under mobile/, and nobody remembers to write a CLAUDE.md too
• Developer on Cursor: the agent knows to run the signing script before packaging
• Developer on Claude Code: the agent does not

Same code, same task, two different results. And no alert will ever catch it — you just occasionally notice that a colleague’s AI is “especially dumb.”

That is the complexity tax Lütke was talking about: not that it cannot be solved, but that the problem should not exist in the first place.

Down to practice: writing one for a KMP + AI chat client

Okay, news done. On to the actual subject.

Say we are building a Kotlin Multiplatform + Compose Multiplatform AI chat client — one Kotlin codebase running on Android and iOS.

A project like this has its own quirks when writing AGENTS.md: in one repo, three kinds of code follow completely different rules.

Start with the directory tree:

ai-chat/
├── AGENTS.md                      # root: global hard rules + common commands
├── settings.gradle.kts
├── gradle/
│   └── libs.versions.toml         # version catalog (single source for dependency versions)
├── shared/                        # shared business logic (no UI)
│   ├── AGENTS.md                  # rules for this layer
│   ├── build.gradle.kts
│   └── src/
│       ├── commonMain/kotlin/     # ← shared across platforms
│       ├── androidMain/kotlin/    # ← Android implementation
│       ├── iosMain/kotlin/        # ← iOS implementation
│       └── commonTest/kotlin/
├── composeApp/                    # Compose Multiplatform UI
│   ├── AGENTS.md
│   └── src/
│       ├── commonMain/
│       ├── androidMain/
│       └── iosMain/
├── androidApp/                    # Android shell project
│   ├── AGENTS.md
│   └── src/main/AndroidManifest.xml
└── iosApp/                        # iOS shell project (Xcode)
    ├── AGENTS.md
    └── iosApp.xcodeproj

Note: the structure itself is the first layer of information for the agent. If the agent cannot tell shared/ from composeApp/, it will write UI code into the logic layer.

Root AGENTS.md: only global hard rules and common commands

# AGENTS.md

An AI chat client built with KMP + Compose Multiplatform.
One Kotlin codebase, compiled to Android / iOS.

## Project structure
- `shared/`     — shared business logic, **contains no UI**
- `composeApp/` — Compose Multiplatform UI (all platforms share one set of screens)
- `androidApp/` — Android shell (Activity / Application / manifest)
- `iosApp/`     — iOS shell (Xcode project / SwiftUI entry point)

## Build and test
- Full build:             `./gradlew build`
- Shared module compile:  `./gradlew :shared:compileKotlinMetadata`
- Install to Android:     `./gradlew :androidApp:installDebug`
- Run all tests:          `./gradlew allTests`
- Run one class:          `./gradlew :shared:allTests --tests "*ChatRepository*"`
- iOS framework:          `./gradlew :shared:linkDebugFrameworkIosSimulatorArm64`

## Hard rules (violating these breaks compilation on every target)
1. `java.*`, `android.*`, `platform.*` are **forbidden** in `commonMain`
2. All platform differences go through `expect` / `actual`, never `if (isAndroid)`
3. **Do not copy the logic for iOS** — that throws away the point of using KMP
4. New dependencies go into `gradle/libs.versions.toml` first; modules reference only the alias, **never hardcode a version**
5. After changing `commonMain`, it must still compile for both Android and iOS

A few things about how this is written that I think matter a lot:

① Commands must be copy-pasteable, not descriptions. Write ./gradlew :shared:compileKotlinMetadata, not “compile the shared module.” Give the agent something it can run directly and it does not have to guess.

② Hard rules need their consequences spelled out. “No java.* in commonMain” is a rule. Add “it breaks compilation on every target” and the agent understands it is a hard constraint, not a style preference.

③ Kill ambiguity with a single source of truth. “Versions live only in libs.versions.toml” — that one line stops the agent from hardcoding versions all over the place.

shared/AGENTS.md: only what is specific to this layer

A subdirectory AGENTS.md should not repeat the root file. It should hold only what you need to know once you are in that directory:

# shared/ — shared business logic

## What each source set is for
- `commonMain/` — platform-agnostic logic. Need a platform capability, declare it here with `expect` first
- `androidMain/` — the Android implementation of each `expect` (Android SDK / JVM APIs)
- `iosMain/`     — the iOS implementation of each `expect` (Kotlin/Native + Foundation)
- **Every new `expect` needs both `actual` implementations, in androidMain and iosMain**

## Directory conventions
- `data/`      — repositories, data sources, DTOs
- `domain/`    — domain models, use cases
- `platform/`  — platform abstractions behind expect/actual
                 (KeyValueStore, HttpEngine, AppInfo…)

## Networking (the core of an AI chat app)
- Use **Ktor** everywhere. No OkHttp or URLSession directly in the shared layer
- Streaming responses always return `Flow<ChatChunk>`. Do not manage UI state in shared
- Timeouts, retries and error mapping all live in `data/remote/`

## Commands
- Tests:        `./gradlew :shared:allTests`
- iOS framework: `./gradlew :shared:linkDebugFrameworkIosSimulatorArm64`

See what is in there? This layer holds purely KMP-specific knowledge:

• the pairing rules for expect/actual (the easiest place to screw up in KMP)
• why networking has to be Ktor (OkHttp does not exist on iOS)
• why streaming uses Flow (the defining feature of an AI chat app)

None of this goes in a general README, and the agent trips on it every single time.

The shell projects: each one says what not to touch

androidApp/AGENTS.md:

# androidApp/ — Android shell

## What goes here
- Activities, Application, AndroidManifest.xml, res/ resources
- **Business logic always goes in shared/, UI always goes in composeApp/**

## Common commands
- Install:  `./gradlew :androidApp:installDebug`
- Logs:     `adb logcat -s AiChat:V`

## Watch out
- New permissions require an AndroidManifest.xml change and **an update to this file**
- Before changing minSdk, check API compatibility for what shared/ uses

iosApp/AGENTS.md:

# iosApp/ — iOS shell (Xcode project)

## Important: this is not built with Gradle
- This is an Xcode project. **Do not try to build it with gradlew**
- After changing code in shared/, run this first:
    `./gradlew :shared:linkDebugFrameworkIosSimulatorArm64`
  so Xcode picks up the new framework, then Run from Xcode

## The Swift side is glue only
- Lifecycle, permission requests, navigation containers
- Business logic **always goes back to shared**. Never rewrite it in Swift

## Common traps
- Missing permission description in Info.plist: only fails at runtime on the simulator, Xcode says nothing
- After changing framework exports, Clean Build Folder
- Kotlin sealed classes must be exhaustively switched on in Swift (write every branch, no default)

Why three separate files?

Because what to do and what not to do flip completely from one directory to the next:

• In shared/, you write: do not touch platform APIs
• In androidApp/, you write: do not put business logic here
• In iosApp/, you write: do not build this directory with Gradle

One repo, rules that contradict each other. A single root AGENTS.md cannot hold this — that is exactly why nearest-first exists.

Side note: mixed tools on the team

AGENTS.md is only a convention, and different tools still read it differently. The docs give some config pointers:

• Aider: add one line to .aider.conf.yml — read: AGENTS.md
• Gemini CLI: configure { "context": { "fileName": "AGENTS.md" } } in .gemini/settings.json
• Migrating from the old name: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md (the symlink keeps compatibility)

In a KMP project there is also the case of uneven tool versions — someone’s Claude Code is still below 2.1.277. You can drop a CLAUDE.md -> AGENTS.md symlink in the key directories as a stopgap.

But remember what Lütke said: that is paying the complexity tax.

If you can upgrade everyone’s tools, do not maintain two files. Symlinks are a transition, not the destination.

A few traps I have hit

① Do not turn AGENTS.md into a translated README. A README is a project intro for humans. AGENTS.md is an operating manual for the agent. The difference: a README says what, AGENTS.md says how, and it has to be executable.

② Do not write should, recommend, try to. How an agent handles vague wording is unpredictable. Either it is a hard rule (with the consequence stated) or leave it out.

③ Do not let it go stale. A stale command is worse than no command — the agent runs it and gets stuck on a task that no longer exists. When you change a build script, update AGENTS.md in the same pass. Make it a habit.

④ Do not overstuff it. The official minimal example is a dozen lines and it is enough. Context is a budget, and every line you write for the agent takes space away from understanding the code.

⑤ Draw the directory tree. Best return on effort of anything here. One accurate tree saves the agent ten ls calls.

What I think

First, the AGENTS.md outcome is really platform-neutral beating tool-locked.

Anthropic held out for nearly a year and then supported it anyway. The reason is simple: when 60,000 projects use one format, not supporting it means taxing your users.

That complexity tax line from Shopify hits the real pain every large repo has.

Second, for KMP projects AGENTS.md is probably worth more than for an ordinary project.

Because KMP’s traps are unusually directory-specific:

• Does this code belong in commonMain or iosMain? Completely different rules
• Does this API exist on every platform?
• Do I need to relink the iOS framework after this change?

Saying all of that out loud in every conversation is expensive. Written into directory-level AGENTS.md files, it becomes a one-time investment.

Third, the long-term significance may be bigger than it looks.

As AI coding tools move from completing code to finishing tasks on their own, does the repo have a file that states the rules starts to look a lot like does this project have automated tests — a marker of engineering maturity.

There is a side benefit too: writing AGENTS.md is itself an exercise in cleaning up team conventions. It forces you to write down the implicit rules that only old-timers know — and that may be worth more than making the AI a little smarter.

I would like to ask you:

Does your project have an AGENTS.md? If not, which part do you think is hardest to write: the build commands, or the conventions that live only in people’s heads?

Or what trap have you hit in a KMP project that documentation later fixed? Tell me in the comments and I can turn it into the next post.

Sources: the AGENTS.md spec (agents.md), The Register (9/18), 36Kr / CSDN coverage of the Shopify–Anthropic dispute (8/26), the Claude Code 2.1.277 release notes.

A while back I wrote a piece on HarmonyOS and KMP, and at the time I found one key fact: the stable release the community published was HarmonyOS support built on KMP 2.2.21 / CMP 1.9.2.

Going back to that repo the other day, I found one extra line in the branch list:

develop-2.4 Documentation set for framework KMP 2.4.21 _ CMP 1.12.0

And the branch was updated 21 hours ago.

There is another one:

main-2.2 (default branch) Documentation set for framework KMP 2.2.21 _ CMP 1.9.2

On one side, the stable release already shipped. On the other, the new baseline being pushed forward.

On the HarmonyOS front, KMP is starting to line up with the latest upstream version.

And at almost the same moment, upstream JetBrains had just released Kotlin 2.4.20.

Two tracks, colliding at one point in time.

First, the upstream track: what changed in Kotlin 2.4.20

If you only skim the changelog you might think, oh, another patch-and-polish release — of the two hundred-odd changes, most are bugfixes.

But a few of them land hard for people who write KMP.

One: Swift interop can finally hold its own.

Swift export now supports mapping Kotlin’s sealed class straight to a Swift enum:

// no more default
let name = switch shape.sealedType() {
case .circle(let t):    "圆"
case .rectangle(let t): "方"
}   // ← exhaustiveness check

Handling this kind of polymorphic type used to mean either a pile of if let on the Swift side, or being forced to add a default branch that can never run — which kills exhaustiveness checking outright. Now the compiler catches the gaps for you.

There is also cross-language inheritance: a Kotlin type can inherit from a Swift class or protocol (including pure Swift libraries), with no wrapper layer needed.

Both point the same direction: the interop friction KMP has always been criticized for on iOS is being sanded down, bit by bit.

Two: klib incremental compilation hits Beta.

kotlin.incremental.native=true

Change one line of Kotlin and you no longer wait for the whole native module to rebuild. If you have done Kotlin/Native, you know what that does for the day-to-day.

Three: the Kotlin/JS test toolchain moved from Karma to Playwright — about time.

So the theme of the upstream track is: smoothing out the seams between languages.

Now the HarmonyOS track: where it actually stands

To understand the HarmonyOS side you have to start with its version numbering scheme, written in the stable release announcement that went out yesterday:

Version numbers use “upstream baseline + HarmonyOS adaptation sequence”: 2.2.21-1.0.0 / 1.9.2-1.0.0 means a HarmonyOS adaptation stable release based on upstream KMP 2.2.21 and CMP 1.9.2.

That rule matters. It says one thing:

HarmonyOS support is not a separate stove. It is chasing upstream versions.

Which is why you see numbers like 2.2.21-1.0.0 — the 2.2.21 in front is the upstream Kotlin version it corresponds to, and the 1.0.0 behind is the HarmonyOS adaptation’s own iteration number.

Already published to Maven:

And the new develop-2.4 branch targets a baseline of KMP 2.4.21 / CMP 1.12.0.

The development cadence announcement says it too:

develop branch: used for monthly development-state code merges, merged into main after each monthly release gate.

In plain language: one version forward every month, merged into the stable line only once it is ready. Not shipping on a whim, but a rolling cadence.

What that branch has been busy with

I went through the develop-2.4 commit history. The recent activity is interesting.

The latest one adapts the CAPI user manual to API 26 — bumping the OHOS CAPI version to API26, updating “modules, minimum API, and typical dependency libraries” to match, and adding a whole section on “special changes caused by the CAPI upgrade to API 26.”

Another one updates akinterop to 1.0.1 and sqldelight to 2.2.1-1.1.0.

Those two directions map exactly to the two real blockers for HarmonyOS cross-platform work:

• CAPI follows the HarmonyOS system version — the system upgrades, the bridge layer has to upgrade with it. That is the “do not fall behind” problem
• Adapted version numbers for third-party libraries — whether the ecosystem libraries keep up decides whether a project dares to use this at all

While we are here: what CMP 1.12 brings upstream

Since develop-2.4 is tracking CMP 1.12.0, what changed in 1.12 upstream is worth a look too.

CMP 1.12.0 shipped on August 25, and the highlight is on the Desktop side:

MCP server was introduced for Compose Hot Reload that enables AI agents to interact with a running Compose application in real time

In plain language: Compose hot reload got an MCP server, so an AI agent can interact with a running Compose app in real time.

That one is subtle. The intersection of Compose and AI is moving from “use AI to write Compose code” toward “let AI operate the running app directly.”

It also brings a batch of breaking changes, so watch out when migrating:

• The deprecation level on typealiases like NativeCanvas and NativePaint was raised to ERROR
• The background parameter on SwingPanel is deprecated

Jumping from 1.9.2 to 1.12.0 is not just a version number change — migration cost counts too.

What the two things together tell you

Put the two tracks side by side and the picture is fairly clear:

KMP’s “one codebase, many platforms” is being pushed forward on several fronts at once.

• Upstream is polishing cross-language interop (Swift export, incremental compilation)
• The HarmonyOS community track is chasing upstream versions (2.2 → 2.4), filling in system support (CAPI → API 26), and widening the third-party library ecosystem

They are not the same team, but they are heading in the same direction — making “write Kotlin once, run on more platforms” a little less friction.

For developers, the test is simple:

When you evaluate a new platform, the question is no longer “does it support this” but “which upstream version has it caught up to, are the libraries enough, does the performance hold up.”

From “can it run” to “can it keep up” — that shift is itself a new stage.

But the community’s real voice is worth more than the announcement

Announcements are always pretty. I went and read the community discussion forum on purpose, because that is where this track’s actual temperature is.

The hottest thread asks “can this be merged into the official JetBrains branch soon” (started 30 days ago, 7 replies).

The poster was direct:

Adding HarmonyOS to my existing pure KMP & CMP app project runs into a large number of unsupported libraries, and during compilation several already-adapted libraries show internal dependency conflicts. I hope it can be merged upstream soon so library developers across the whole KMP community can add ohos versions, the CPF community’s progress on library support is far too slow.

He named three libraries specifically: androidx-datastore, androidx-room3, androidx-sqlite — “these three are basically the foundational dependency libraries for the persistence approaches everyone uses.”

Then the part that stings:

None of them support ohos x86. On Windows a developer can barely build and test an app with normal functionality — at minimum you have to keep a HarmonyOS phone plugged in as the test target…

He also gave a concrete trap: a room3 alpha pulled from some mirror repo generates code that errors on a missing androidx.sqlite implementation, while upstream room3 3.0.1 works fine.

The official reply came, and it was honest:

Hello, support for ohos x86 is already in planning, thanks for your interest.

Other threads are each real in their own way:

• “Under skia rendering the page frame production is dragged to about one frame per 3 seconds, suspected abnormality in the VsyncOnDemand deferred deregistration mechanism” — performance
• “material3 blocks porting an existing project” — component library traps
• “Is webView supported right now?” — capability coverage
• “Has anyone actually shipped a project? What traps did you hit” — and someone replied with: “currently doing a KMP adaptation of a voice assistant”

Add these up and you have the real state of this track: it runs, people are using it, but the ecosystem and performance are still catching up.

Why “following upstream” is slow work

Seeing that “progress is far too slow” line, some people will assume it is a matter of insufficient investment.

But there is a technical reality worth spelling out: HarmonyOS support changes the compiler backend. It is not writing a plugin.

Go through the CPF-KMP-CMP repo list and you see these names:

kotlin, compose-multiplatform, compose-multiplatform-core, skiko, akinterop, cicd-toolkit…

These are HarmonyOS forks of the Kotlin compiler, the Compose framework, and the graphics rendering layer.

Which means the work includes at least:

• Adding a new compilation target to Kotlin/Native
• Wiring Compose’s rendering pipeline into HarmonyOS’s Render Service
• Getting the Skia graphics library that Skiko wraps to run on HarmonyOS

And every time upstream ships a new version, all of those changes have to be re-aligned.

That is what the “upstream baseline + adaptation sequence” version scheme really means — it describes the nature of the work precisely: continuous tracking, not a one-time port.

Look again at “monthly development-state merges, merged into main after each monthly release gate” and it reads differently:

This is not slow. This is doing a very heavy thing at a pace that can be sustained.

A few of my own views

One: the essence of “adaptation” here is following upstream, not reinventing the wheel.

You can see it in the version scheme alone (upstream baseline + adaptation sequence). The core work on the HarmonyOS track is getting upstream’s compiler and UI framework running on HarmonyOS, not inventing a separate API.

Which means its ceiling is tied to upstream: upstream smooths out Swift interop and that is a dividend for iOS; upstream improves the compiler and HarmonyOS only gets it by keeping up.

Two: the three community complaints point at the same problem.

x86 support, third-party library versions, performance — three things on the surface, all “ecosystem maturity” underneath.

And ecosystem maturity has a cruel property: it cannot be solved with enthusiasm, only with time and real projects wearing it in. The official reply of “already in planning” is true, and there is a certain helplessness in how true it is.

Three: if you are evaluating whether to get on this track, here is a framework.

Do not ask “does it support HarmonyOS” — ask these three questions:

1. Which upstream version has it caught up to? (right now 2.2.21 is stable, 2.4.21 is in development)
2. Have the libraries I depend on been adapted? (especially foundational ones like persistence and networking — room3 and datastore are the acknowledged pain points)
3. What is my dev machine? (if you need an x86 emulator, you still have to wait; an Apple silicon Mac plus a real device is the steadier combination)

All three clear, then start. One blocked, and the plan goes in a note for later.

Last

Kotlin 2.4 and HarmonyOS 2.4 look like two unrelated things.

But they are answering the same question:

One body of Kotlin code: how many places can it run, and how well?

Upstream is sanding down the seams between languages, and the HarmonyOS track is widening the map.

Both are making that number bigger.

I want to ask you something:

Would “HarmonyOS support has caught up to 2.4” make you reconsider a KMP project you have on your desk?

Or have you already been through the traps on this track? Talk in the comments — I would genuinely like to hear from real projects.

References: CPF-KMP-CMP community repos (AtomGit/GitCode) branch and release announcements, public posts in the community discussion forum, JetBrains Kotlin 2.4.20 release notes.

On September 7, JetBrains released Kotlin 2.4.20.

If you only skim the changelog you might think, oh, another patch-and-polish release — after all, of the two hundred-odd changes, most are bugfixes.

But for people writing KMP, a few things in this version are genuinely nice. Swift interop especially finally closes several long-standing gaps.

Conclusion first: the three things worth watching are Swift interop, compile speed, and cross-platform consistency. Taking them one at a time.

1. Swift export supports sealed class: iOS folks can finally skip default in their switch

If you have written iOS with KMP, you have almost certainly hit this awkward spot.

You define a perfectly elegant sealed interface in Kotlin:

sealed interface Shape

class Circle : Shape
class Rectangle : Shape

fun createCircle(): Shape = Circle()

Logically seamless. On the Kotlin side you pattern match in one shot.

But on the Swift side, a Kotlin sealed type could only be treated as an ordinary class. You could not do exhaustive matching at all — just a pile of if checks and a default at the end to catch the rest.

The worse part: the day someone adds a new subclass on the Kotlin side, the Swift side does not fail to compile — so a case nobody handles can reach production.

2.4.20 fixes this. Sealed types now map to Swift enums, and the compiler generates a sealedType() method:

let shape = createCircle()

let name = switch shape.sealedType() {
case let .circle(type): "It's a \(type.value)"
case let .rectangle(type): "It's a \(type.value)"
}

Note this — no default.

The Swift compiler checks exhaustiveness, and because it maps to an enum, Xcode autocomplete works properly too. The day a new sealed subclass appears on the Kotlin side, the Swift side fails to compile and tells you to handle it.

That is a lot better than “finding out at runtime that a case is missing.”

2. Cross-language inheritance: use pure Swift libraries without the detour

The second change is more practical: Swift export now supports cross-language inheritance.

What does that mean? A real scenario — you want to use CryptoKit, a pure Swift library, on the iOS side, but it cannot be imported into Kotlin directly.

The old approach was either an Objective-C bridging layer, or giving up and finding a substitute implementation on the Kotlin side. Now you can just do this:

Declare an interface and an open base class on the Kotlin side:

interface CryptoProvider {
    fun hashMD5(input: String): String
}

fun processHash(provider: CryptoProvider, input: String): String =
    provider.hashMD5(input)

open class SwiftBase

Inherit the base class and implement the interface on the Swift side, then pass the object back to Kotlin:

import CryptoKit

final class IosCryptoProvider: SwiftBase, CryptoProvider {
    func hashMD5(input: String) -> String {
        guard let data = input.data(using: .utf8) else { return "failed" }
        return Insecure.MD5.hash(data: data).description
    }
}

let provider = IosCryptoProvider()
print(processHash(provider: provider, input: "Hello, world!"))

When Kotlin receives that Swift object it calls it as a normal implementation of the interface.

This is what the team calls the reverse import pattern: the contract lives in Kotlin, the implementation lives in Swift. For cases where you must depend on a platform-native library, the road is finally clear.

3. Incremental compilation hits Beta: change one line, stop waiting for a coffee

This one may be the biggest improvement to day-to-day development.

Kotlin/Native compile times have always been one of KMP’s sore spots. klib incremental compilation has existed since 1.9.20, but it kept getting polished. Now it enters Beta officially, and the team says debug build times drop substantially.

Turning it on is one line in gradle.properties:

kotlin.incremental.native=true

The team also mentions they plan to enable it by default in an upcoming version.

While we are here: when exporting an XCFramework, the assembleSharedXCFramework task now generates a Package.swift file automatically. Publishing an XCFramework with SwiftPM dependencies used to mean handling SwiftPM distribution yourself. That is now taken care of.

4. Wasm: a few changes that are easy to miss and hard to skip

If your project has a web side, these are worth noting.

Companion object initialization order now matches the JVM

In Kotlin/Wasm, companion object initialization order for parent and child classes could run opposite to the JVM. In cross-platform projects, that kind of difference turns into the worst bugs: works fine locally, behaves like a ghost on another platform. It now follows JVM behavior.

Wasmtime runtime support

The wasmWasi target used to run only through Node.js, and needed a JavaScript bootstrap layer. Now you can use Wasmtime, the standalone WebAssembly runtime:

kotlin {
    wasmWasi {
        wasmtime()
    }
}

New compilation modes

Previously there was only monolith mode (compile the whole project and its dependencies together into a single binary — smallest output, but a full rebuild every time). Now there are two multi-module modes, so you can pick:

• Use multimodule-closed-world during development to recompile only changed modules, for faster iteration
• Keep monolith for production builds, to keep the output as small as possible

Configuration:

kotlin.wasm.compilationMode=multimodule-open-world

Watch for one breaking change: top-level require() inside a @JsFun declaration now fails to compile. If you wrote it that way before, migrate to the @JsModule annotation or an import() expression.

5. Kotlin/JS: Karma retires, Playwright takes over

Kotlin/JS browser tests have always used Karma as the launcher, but the Karma project has gone unmaintained for two years.

2.4.20 introduces a new test DSL: Playwright underneath as the driver (supporting Chromium, Firefox, and WebKit), Mocha as the test runner, and webpack still as the bundler for now (the team says Vite comes later).

Usage is a test {} block inside browser {}:

kotlin {
    js {
        browser {
            @OptIn(ExperimentalJsTestDsl::class)
            test {
                timeout = 2.seconds
                chromium()
                firefox()
                webkit()
            }
        }
    }
}

Also, suspend lambdas can now be exported as JavaScript async functions — handy for cross-platform calls.

6. Standard library and everything else

A few handy ones:

• Coroutine stack trace recovery: a new StackTraceRecoverable interface. When exceptions fly between coroutines, you can see where they came from and who rethrew them. For exceptions with complex constructor parameters, implement copyForStackTraceRecovery().
• Collection utilities: new functions for checking element equality and uniqueness.
• kotlin.test: new assertion function overloads.
• Gradle: full compatibility from Gradle 7.6.3 through 9.7.0; the Problems API now carries compiler diagnostic IDs and groups them, so you can locate the source of a problem fast when debugging.
• Compiler: invokedynamic compilation of when expressions on JVM 21+ is now stable (on by default); a new kotlinr run command and a standalone native image.

What these changes mean for KMP developers

Put it all together and I think 2.4.20 sends three signals.

1. iOS interop is moving from “works” to “works well”

Sealed classes mapping to enums, cross-language inheritance for pure Swift libraries — both hit exactly what people complain about most on the iOS side of KMP. People used to say KMP is “good on Android, a bit lacking on iOS.” That gap is visibly narrowing.

2. Compile experience is being treated as a real problem

klib incremental compilation into Beta, Wasm multi-module compilation — both solve the same thing: not making daily development wait. Compile speed is one of KMP’s most concrete reasons people bounce off it. This is the right direction.

3. Cross-platform consistency is getting more attention

Wasm companion object initialization matching the JVM looks like a small change, but “behavior differs across platforms” is exactly the nastiest class of bug in cross-platform projects. The team is actively narrowing those differences.

One other piece of news while we are here: Google released ADK for Kotlin 1.0 a few days ago, for writing production-grade AI agents in Kotlin. The Kotlin and AI agent circles have visibly been overlapping a lot more this year.

Upgrade advice

• Ordinary projects: just upgrade. This release is mostly fixes, low risk.
• KMP projects: strongly recommended. The Swift export changes are a real improvement in day-to-day feel.
• Projects using Wasm: check require() calls inside @JsFun before upgrading. That is the only breaking change.
• Want to try incremental compilation: add kotlin.incremental.native=true and test the waters; report problems upstream.

Kotlin’s release cadence has always been steady, no great leaps. This “fix a few real problems each time” style of iteration is, honestly, the friendliest thing for production projects.

References: What’s new in Kotlin 2.4.20 · GitHub Release

If you are a senior engineer, what do you write down as your requirements when you go job hunting?

More money, less work, a modern stack, a solid team. Roughly that.

Jake Wharton is different. This Android / Kotlin open source legend, known to Chinese developers as “J God,” drew up nine criteria for choosing a job.

The first one: do not join an AI company, do not work on AI-centric products, and do not accept a company forcing AI on its engineers.

By his own estimate, that single line rules out about 80% of potential employers.

Before you rush to call him precious about it: it is not that he has no options. A senior Kotlin engineer in the US typically starts at a $200K base salary, plus roughly $100K a year in equity vesting over four years. Going into AI could pay more.

He did it anyway.

InfoQ published the full transcript of this two-hour interview a few days ago, over thirteen thousand characters. What struck me most was not his conclusion. It was the reasoning he gave.

Who he is: one of the people who made Kotlin Android’s official language

If you are not in the Kotlin world, you may not know how much weight that name carries.

Jake Wharton is the author or core contributor of OkHttp, Okio, Retrofit and other star open source libraries. Anyone who has written Android has probably used his code.

More importantly: he was the first engineer on the Google Kotlin team.

Before Google, he worked at Square (later Cash App). To convince the company to adopt Kotlin internally, he wrote an argument document. He later made it public, and it indirectly drove the whole Android community’s interest in Kotlin.

Then Google decided to make Kotlin an official first-class language for Android, and he joined that team.

He says the opportunity was “almost impossible to turn down.” Nothing is a bigger endorsement than joining the company responsible for the entire Android toolchain and pushing Kotlin to official status.

So he is not anti-technology. He is someone who bet his career on a language and a toolchain.

Which raises the question: why is a person like that so resistant to AI coding?

Reason one: AI spreads in the opposite direction from every tool before it

This is the passage I agreed with most. Wharton’s words:

Traditionally, a development tool is usually pushed bottom-up by engineers. Maybe one engineer falls in love with a new language, Kotlin for instance. Or a new IDE, IntelliJ IDEA. Or a new build system. The engineer finds value in it at work, the enthusiasm spreads to others, and then everyone goes and convinces engineering management to approve adopting it.

But AI tools seem to spread in the exact opposite direction. Why is a company CEO telling engineers what tools they should use in their daily work?

That is a sharp observation.

Think about how Kotlin took off: a group of engineers genuinely found it good, started using it quietly in their projects, and slowly convinced their bosses. Bottom-up. Organic.

The rollout path for AI coding tools at plenty of companies looks like this: executives see the news, mandate that everyone must use AI to boost productivity, and put it in performance reviews. Top-down. Administrative.

The legitimacy of a tool used to come from it actually being good. Now, sometimes, it comes from being mandated.

That shift is worth a thought from every engineer.

Reason two: what you hand over is capability, not just work

On the idea that AI turns engineers into cogs, here is his full formulation:

AI can help engineers handle repetitive work, but the most irresponsible use is letting AI generate code beyond the user’s own capability. If you cannot complete the task without a large model, you often cannot truly understand, verify or maintain the result either.

Once dependency forms, what an engineer hands over is not just part of the work but their own capability and bargaining power, and eventually they may become a cog that is easier to replace at low cost.

Note the boundary of that statement: he did not say “do not use AI.” He said “do not use AI to generate code beyond your capability.”

Those are very different sentences.

The first means “AI will replace you.” The second describes a more specific and much quieter risk:

If a requirement would normally take you two days to think through the design, and now AI spits out working code in ten seconds that you do not fully understand —

you have the code, but your understanding of the system has actually degraded.

A few rounds of that, and part of what you maintain is something you cannot read yourself.

At that point, where is your value anchored?

Reason three: copyright and licenses, the accounting is not settled

He is direct about this one:

As I see it, they are built on large-scale use of copyrighted content. Model training ignored artists’ copyright and ignored open source licenses.

Being able to access something on the internet does not mean you have the right to recombine it, rewrite it, or output it verbatim.

For someone who has poured a lot of himself into open source, the position is easy to understand. His code was taken to train models, and then what the models produce is sold back to him. Ethically, that accounting really is not settled.

He adds a detail: open source maintainers now have one more burden to deal with — a flood of low-quality AI-generated PRs.

I believe that. Anyone who has maintained an open source project has felt it.

But he does not think AI is going away

Do not misread him. His read on AI’s capabilities in the interview is actually restrained and clear-eyed:

“AI is already unnervingly powerful,” but that does not mean it can carry the whole software engineering process reliably and without error.

To him, AI can at most be one tool in the toolbox. It cannot become the foundation of engineering capability.

“Not the foundation.” I think that metaphor is exactly right.

A tool in the toolbox is something you can leave unused. A foundation is something you cannot stand without.

He also makes a counterintuitive point: AI being able to write code does not mean open source libraries lose value. Because the value of open source is not just “here is a piece of code that works.” It is the long-term dividend of continuous maintenance —

Someone may fix an edge-case bug today that you would not hit yet. Two years later, when you refactor your business, you would have triggered it, but because you use the same open source library, it was already solved ahead of time.

The logic is tight: AI gives you one copy of code today. Open source gives you continuously evolving public infrastructure. Those are not the same thing.

Kotlin talk, the parts that matter to us

The second half of the interview is about Kotlin, and a few points are genuinely useful if you write Kotlin:

1. “Kotlin looks a lot like what Java wants to be in ten years”

His explanation: Java has to avoid breaking existing code, so the language evolves slowly. Kotlin can hand developers many modern features that might land in Java later, and still works with codebases stuck on Java 8 / 11.

2. Knowing Kotlin is no longer a career advantage

That stings, but his explanation is fair:

I am not sure it counts as an advantage anymore. In a sense that reflects Kotlin’s success: it has become a default requirement rather than a scarce, hard-to-find skill.

Because Google made Kotlin the official Android language, people learning Android learn Kotlin directly, and employers assume you know it.

But —

If a developer has more than routine Kotlin, things like Kotlin Multiplatform that are relatively advanced, that can still be a differentiator and set you apart from other Kotlin developers.

“KMP is still a differentiator” is probably the most direct signal in this interview for people like us.

3. Meta donated its Kotlin formatter

In the same week he recorded this episode, Meta contributed its Kotlin formatter to the Kotlin Foundation. It may become the official formatter.

4. In 2026, Kotlin is governed by three parties

The ideal is JetBrains, Google and the community all participating. One of the reasons the Kotlin Foundation exists is so the language is no longer wholly owned by JetBrains — so no single company controls it.

My own bind: building an AI client while listening to him argue against AI

A personal note.

I am writing a booklet about AI chat clients right now — building a cross-platform AI chat app from scratch. The stack is KMP.

So reading this interview gave me a strange sense of dislocation: I am building a product on AI capabilities while one of the most respected people in the industry says AI is ruining engineering.

Calm down and think about it, though, and I do not find it contradictory.

What he opposes was never “the tool called AI.” It is three things:

1. Treating AI as mandatory organizational discipline rather than an optional tool
2. Using AI as a substitute for thinking, losing your ability to verify and maintain
3. Business models built on copyright and license problems

Of those three, only the second is something I have to stay vigilant about — especially when I write code and write tutorials myself.

Tools will keep getting stronger. That is the trend, you cannot stop it and you do not need to. But “is my judgment still in my own hands” is something only you can be responsible for.

That is probably what he means by “not the foundation.”

Last

One more line from the interview stuck with me:

I do not think the overall quality of software has improved over the past few years, and I do not think these tools will improve software quality in the long run. But some company executives see a different picture.

Which picture is right? Nobody knows yet. It may take five years to find out.

But one risk is certain: if a person outsources all of their capability, then whether or not AI is that strong, they have already lost their bargaining power.

What do you make of it? How much of your current work involves AI?

Tell me in the comments — I especially want to know if anyone else is building products with AI while quietly uneasy about where its boundaries are.

Sources: full Jake Wharton interview (InfoQ, 2026-09-11) · original video

Anyone who writes Kotlin has been carrying the same nagging feeling for the past two years.

The AI agent wave keeps rolling in, but open the source and look: LangChain, CrewAI, AutoGen, all Python. If you want to build an agent inside the Kotlin ecosystem you already know, you either hand-roll it on an HTTP client, or write a Python service and call it from Kotlin, with a process boundary and serialization sitting in between for good measure.

On September 9, Google filled that gap: Agent Development Kit (ADK) for Kotlin 1.0 is officially GA.

And this is not a straight port of the Python version. Underneath it is a Kotlin Multiplatform (KMP) core.

That detail matters. More on it later.

First, what this thing actually is

ADK for Kotlin’s positioning is clear: fully decoupled from the model backend, session storage, and memory system.

In plain terms: you write the agent logic once in Kotlin, and the model can be Gemini or something else entirely; sessions can live in memory, in Room, or in the cloud, and you swap them as you like.

1.0 is feature-aligned with ADK Python and Java, and it brings over the multi-agent patterns that matured in the Python ecosystem:

• Hierarchical multi-agent: agents chain together and delegate tasks to specialized sub-agents
• Context compaction: history that grows too long gets summarized automatically, keeping tokens inside the window
• Human-in-the-loop: sensitive operations pause and wait for user confirmation before continuing
• Resumable sessions: agent interaction state serializes and restores across sessions
• Java interop: existing Java applications can call Kotlin-written agents directly
• Vertex AI integration: enterprise Session, RAG Memory, and Memory Bank services

One of these deserves its own paragraph: context compaction.

Anyone who has written an AI chat client knows that managing history across turns is unavoidable work. A sliding window loses information, and stuffing everything in blows the token budget. ADK makes it a built-in framework capability, so you do not have to build that wheel yourself.

The technical part: why this counts as Kotlin-native

This is the part of ADK for Kotlin I find most interesting.

Tools as annotations, schemas generated at compile time

Python agent frameworks generally lean on runtime reflection to read function signatures and generate tool descriptions. ADK for Kotlin takes another road: generation at compile time with KSP (Kotlin Symbol Processing).

The code you write is just an ordinary Kotlin function:

class InfrastructureDiagnosticsService {

    @Tool
    suspend fun getServiceMetrics(
        @Param("Target service or database cluster") serviceName: String,
        @Param("Time window in minutes") windowMinutes: Int? = 15,
    ): ServiceMetrics {
        // query the monitoring backend: Datadog, Prometheus, Cloud Monitoring
        return ServiceMetrics(
            serviceName = serviceName,
            cpuUsagePercent = 91.4,
            connectionPoolUsagePercent = 98.5,
            p99LatencyMs = 2450,
            errorRatePercent = 4.2,
        )
    }
}

KSP generates a generatedTools() extension function at compile time.

Three things follow from that: type safety (the schema cannot drift away from the signature), suspend function support (coroutines fit in naturally), and zero runtime reflection (fast startup, small binary, which matters a lot on Android).

If you are used to compile-time checking in Kotlin, this design direction should resonate: anything the compiler can catch, do not defer to runtime.

Skills: progressive disclosure

ADK has a concept called a Skill, and I think it is cleverly designed.

You write a standard operating procedure as SKILL.md and drop it into resources:

---
name: database-incident-triage
description: Standard operating procedure for diagnosing database latency spikes.
allowed-tools: [getServiceMetrics, fetchRecentDeployments, notifyOnCall]
---

# Database Incident Triage SOP

1. **Telemetry**: Call `getServiceMetrics` to inspect CPU, latency, and pool saturation.
2. **Correlation**: Call `fetchRecentDeployments` to check for recent changes.
3. **Safety Rules**: Never restart primary nodes during peak hours.
4. **Notify**: Broadcast diagnosis to `#production-alerts`.

The agent only loads that SOP into context when it needs it, and bundled resource files such as assets/mitigation_rules.txt are pulled on demand too.

The team calls this progressive disclosure: spend tokens where they matter, do not dump every piece of knowledge into the model up front.

Hands on: a database incident triage agent

The official example is a practical one. Suppose production fires a database alert and we want an agent to help triage it:

object IncidentTriageDemoAgent {
    val rootAgent = LlmAgent(
        name = "incident_triage_agent",
        model = Gemini(name = "gemini-3.8-flash"),
        instruction = Instruction(
            """
            You are an SRE on-call diagnostic assistant.
            1. Load the matching triage SOP using `load_skill`.
            2. Follow the playbook steps strictly.
            3. Use your diagnostics tools to inspect telemetry and notify the team.
            """.trimIndent()
        ),
        // compile-time generated function tools (zero reflection)
        tools = InfrastructureDiagnosticsService().generatedTools(),
        // dynamic skill toolset
        toolsets = listOf(SkillToolset(NewFileSystemSource(resolveSkillsDir()))),
    )
}

Run it:

fun main() = runBlocking {
    val runner = InMemoryRunner(
        agent = IncidentTriageDemoAgent.rootAgent,
        appName = "IncidentTriageApp"
    )

    val alert = "ALERT [P1]: Database latency spike detected on 'users-postgres-cluster'!"

    val events = runner.runAsync(
        userId = "oncall-sre",
        sessionId = UUID.randomUUID().toString(),
        newMessage = Content.fromText(Role.USER, alert)
    ).toList()

    for (event in events) {
        event.content?.parts?.firstOrNull()?.text?.let { println("Agent: $it") }
    }
}

Note the runBlocking plus streaming events. Coroutines are a first-class citizen here, not something bolted on afterwards.

On receiving the alert, the agent walks the whole flow by itself: load the SOP, call getServiceMetrics() and find the connection pool at 98.5%, call fetchRecentDeployments() and pin it to a deploy 25 minutes ago, post the diagnosis to the alert channel, recommend a rollback.

That is a complete loop of tool calls, domain knowledge, and autonomous decision-making.

On-device Android: it is not cloud-only

If you work on mobile, the Android extensions may be the more exciting part for you.

The hard part of mobile AI is the balance: cloud inference is capable, but latency, privacy, and offline availability are all problems. ADK for Kotlin 1.0 ships a modular Android story:

• LiteRT-LM: small models on device
• ML Kit (beta): local inference
• Firebase AI Logic: hybrid cloud and on-device orchestration
• Room persistence: history in SQLite, survives process death
• AppSearch indexed memory: an on-device full-text memory service
• FileArtifactService: generated files such as statements and receipts land directly in local storage

The official financial assistant sample wires all of it together:

fun createAndroidRunner(applicationContext: Context, agent: LlmAgent): InMemoryRunner {
    return InMemoryRunner(
        agent = agent,
        appName = "AndroidFinancialApp",
        // SQLite persistence: sessions survive process death
        sessionService = RoomSessionService.fromContext(applicationContext),
        // on-device full-text indexed memory
        memoryService = AppSearchMemoryService.fromContext(applicationContext),
        // app-private file storage
        artifactService = FileArtifactService.fromExternalFilesDir(applicationContext)
    )
}

And HITL is handled pragmatically. For something sensitive like a transfer, you just add a flag when defining the tool:

@Tool(
    name = "transferFunds",
    description = "Transfers money to another account. Requires explicit user approval.",
    requireConfirmation = true
)
fun transferFunds(
    @Param("Recipient account ID") recipientId: String,
    @Param("Amount in USD") amount: Double
): String { /* ... */ }

When execution reaches it, the agent pauses and waits for the user to tap confirm in the UI.

If you build finance or healthcare apps, this is close to non-negotiable.

What it means for KMP developers

Back to that KMP core from the top of the post.

ADK for Kotlin’s core engine is cross-platform and decoupled from the model backend, session storage, and memory. The implication of that architectural choice: agent business logic is shareable.

Picture it. Your agent orchestration, tool definitions, and SOP skill files run on Android, and they also run on a server JVM. If iOS support lands later, that is one codebase across three targets — which is exactly the story KMP has been telling all along.

Combine that with what we covered on Kotlin 2.4.20 (sealed class mapping in Swift export, cross-language inheritance), and the puzzle pieces on Kotlin’s cross-platform and AI tracks have visibly started fitting together this year.

For anyone building an AI chat client there is a more direct takeaway: the framework-level pieces — session persistence, context compaction, HITL — already have mature implementations. You do not have to build them from scratch.

How to start

Just add the dependencies:

dependencies {
    // core engine + KSP processor
    implementation("com.google.adk:google-adk-kotlin-core:1.0.0")
    ksp("com.google.adk:google-adk-kotlin-processor:1.0.0")

    // Android on-device extensions (optional)
    implementation("com.google.adk:google-adk-kotlin-mlkit-android:1.0.0-beta")
    implementation("com.google.adk:google-adk-kotlin-litertlm:1.0.0")
    implementation("com.google.adk:google-adk-kotlin-firebase-android:1.0.0")
}

Official resources:

• 📖 Docs and getting started: adk.dev
• 🐙 GitHub: github.com/google/adk-kotlin
• 📱 Android guide: Building Android agents with ADK
• ☕ Java interop sample: ADK Kotlin Java sample

Wrapping up

I do not think the point of ADK for Kotlin 1.0 is that there is one more agent framework on the pile. The point is this:

The Kotlin ecosystem finally has an agent development story that is compile-time safe, coroutine-native, and reusable across platforms.

It does not drag Python’s patterns over. It redesigned around Kotlin’s language features: KSP instead of reflection, coroutines instead of callbacks, a KMP core instead of a single-platform implementation.

If you work in KMP, this is worth a serious look.

Reference: Announcing ADK for Kotlin 1.0 - Google Developers Blog (2026-09-09, by Guillaume Laforge)

Start with a number: four.

Android, iOS, desktop — that’s the main ground Kotlin Multiplatform has covered steadily for years (Web / Wasm is still in progress). Write one set of shared logic, add one Compose UI, and several platforms run together.

And yesterday, that list gained a fourth member: HarmonyOS.

And this time it isn’t “theoretically runs” — it’s an official release. Components are in the Maven repo, the toolchain plugin is searchable in the Android Studio plugin marketplace, and the docs are on AtomGit.

What surprised me most was the publisher’s line:

Teams already using CMP on other platforms can reuse the same Compose code for UI and business logic directly, without writing a whole separate ArkUI implementation for HarmonyOS.

No ArkUI rewrite. For anyone doing cross-platform, those few words carry real weight.

Let’s get the facts straight

What shipped is the first HarmonyOS release of KMP&CMP, on September 15, 2026.

The key facts:

• Who made it: built jointly by community partners in the CPF-KMP-CMP SIG (note: a community SIG, not JetBrains official — I’ll get into that distinction later)
• Based on: upstream KMP 2.2.21 / CMP 1.9.2
• Goal: bring the “shared logic, native UI rendering” paradigm to HarmonyOS
• How to get it: components are published to the Maven repo; the toolchain plugin KMP OHOS Support is searchable and installable from the Android Studio plugin marketplace

The official positioning on who it’s for is clear too:

For teams already using KMP/CMP for cross-platform work, this release helps lower the cost of moving to HarmonyOS. HarmonyOS teams can also use it for mixed Kotlin and ArkTS development, and to widen their technology options.

Translated: KMP teams who want HarmonyOS now face a lower cost; HarmonyOS teams who want Kotlin now have a path.

Some background while we’re here — this has been building for three months. The community edition opened Beta in June, and in August InfoQ reported a round of measurements (95% less rendering memory, 90% fewer GC jank incidents). Now it’s properly landed.

Highlight one: Compose runs on HarmonyOS directly, no UI rewrite

This is the one I think is most valuable.

On HarmonyOS, the official route is ArkTS + ArkUI. For a team already doing KMP/CMP, that means the HarmonyOS side needs its own separate UI — business logic shared, but the interface rewritten.

This release paves that road:

CPF-KMP-CMP provides platform implementations of compose.ui, compose.foundation, compose.material and compose.material3 on the HarmonyOS side, so you can keep the familiar declarative UI habits while building HarmonyOS screens.

compose.material3 is there. Which is to say, the Compose code you’re used to writing is recognized on HarmonyOS.

For a project already running CMP on Android/iOS, that means the cost of adding HarmonyOS drops from “rewrite a UI” to “add a target”.

How big a difference is that? Anyone who’s done cross-platform knows.

Highlight two: Kotlin ↔ ArkTS two-way interop

The second one matters a lot for existing projects.

The reality is: plenty of HarmonyOS projects already have a pile of ArkTS (system capabilities, business modules), and ripping it all out for Kotlin isn’t an option.

The answer here is akinterop:

Shared logic can keep being written in Kotlin. When the system side or existing modules stay in ArkTS, use akinterop for two-way interop: declare intent with annotations / decorators, let the toolchain generate the bridge, and write less C glue. Primitive types, containers and exceptions can cross sides, existing projects can adopt incrementally, and nothing has to be torn down for interop.

“Adopt incrementally, nothing torn down” — that line is the reassurance existing projects needed.

Annotation declares intent, toolchain generates the bridge — a far better experience than hand-writing C glue. Anyone who’s written JNI knows that pain.

Highlight three: unified rendering (this is the technical core)

This one’s more hardcore, but I think it’s the most technically substantial piece of the whole thing.

The problem first: traditional cross-platform UI approaches usually build their own rendering pipeline.

What’s wrong with building your own? The report says it directly:

Traditional cross-platform UI solutions often build their own rendering pipeline, which tends to add initialization and composition overhead, and often shows up as slow startup and animations that don’t match the system.

Self-rendering means your UI doesn’t go down the system’s path — startup needs an extra init step, animation rhythm doesn’t line up with the system, and it just looks “not native”.

This approach goes the other way:

CPF-KMP-CMP connects Compose’s drawing capability to HarmonyOS’s Render Service / RenderNode system rendering, with HarmonyOS handling composition and refresh scheduling uniformly (unified rendering requires API 19 or above).

Handing drawing over to HarmonyOS to composite itself pays off in a chain:

• Faster first frame: no self-rendering init wait, so startup and navigation feel snappier
• Fine-grained partial refresh: update only when state changes, with partial recording support — only the changed region is repainted
• Native component mixing: Compose screens can mix with ArkUI and C-API, so native capabilities like maps and video are easier to embed
• System-aligned animation: frame rhythm follows the system’s DisplaySync, so animation matches native HarmonyOS apps

That last one matters especially. The reason cross-platform apps look fake at a glance often isn’t wrong layout — it’s that the animation rhythm is wrong, frame scheduling off the system’s beat.

⚠️ Note one limitation: unified rendering requires API 19 or above. On older devices it degrades.

The performance account: 20% off compile time, 30% off heap

They gave some genuinely specific numbers this time, unlike the vague claims that usually pass for “performance optimization”:

Compile side (parallel compilation):

Splitting LLVM IR and running local optimization across threads before merging shortens compile waits on large projects; typical scenarios save roughly 20%+ of the time.

Memory side (CommonGC):

Using a concurrent mark-copy collection algorithm to reduce memory fragmentation and GC pause time, KN heap usage in typical scenarios drops by about 30%.

There are also two engineering optimizations that are genuinely practical:

• Modular splitting: a single KMP project can be configured into multiple .so files, and combined with distributed compilation it shortens builds further
• Debug incremental compilation: on macOS / Linux, incremental compilation based on a static library cache — only the changed part recompiles, no full relink every time

(Anyone doing KMP probably has a small stress reaction to the words “full relink”)

One more detail I like — no idle spinning in the background:

The unified rendering path supports requesting VSync signals on demand, actively suppressing refresh drawing when page content hasn’t changed; it also supports LTPO hardware characteristics, stopping pointless draw loops automatically once the app goes to the background… This is framework default behavior, requiring no extra code from the app.

Default behavior, no app code needed. This kind of “the framework worries about it for you” design is far friendlier than making you turn animations off by hand in onPause.

Getting started: three steps

The flow is simpler than I expected:

(1) DevEco Studio: use 6.0.0+ to download HarmonyOS SDK API 17+, open the harmonyApp in the project and set up the debug signature. (2) Android Studio: write KMP&CMP code day to day. (3) Android Studio: pick a device and harmonyApp, hit Run (keep DevEco running while pushing the package).

Note the parenthesis in step 3 — DevEco Studio has to stay open while pushing. That kind of “two IDEs cooperating” detail is exactly where people trip, and they said it up front.

The docs are on AtomGit (search CPF-KMP-CMP/docs) if you want to dig in.

Why this piece of the HarmonyOS puzzle matters so much

Honestly: for KMP developers in China, this puzzle piece may matter far more than Web/Wasm.

The reason is practical — for mobile work in China, HarmonyOS is no longer a “should we consider it” question, it’s a “when do we have to” question. Especially in government and enterprise, finance, automotive and IoT, where it’s moving faster than many expected.

And the choice KMP teams faced with HarmonyOS used to be awkward:

• Shared logic carries over, but the UI gets rewritten (ArkUI) → which means an extra person on the HarmonyOS side
• Or drop KMP entirely and start a separate HarmonyOS project → all the shared-logic advantage gone

The point of this release is right there: it takes most of the “HarmonyOS UI has to be rewritten too” cost out of the equation.

For a small team, that may be the difference between “can’t afford it” and “can afford it”.

A cooler read: how to see this

Hype is hype. I need to be clear about a few boundaries so you don’t misjudge.

First, this is a community SIG project, not JetBrains official.

The publisher is the CPF-KMP-CMP SIG, not JetBrains and not an official Huawei release. That doesn’t make it bad — quite the opposite, this kind of “ecosystem foundation” usually gets chewed through by community SIGs bit by bit — but set your expectations accordingly:

• Long-term maintenance depends on community activity, without the explicit commitments an official API carries
• When you hit a problem, the answer is in the community (issues, discussions), not in official docs

Second, unified rendering needs API 19+.

If your target devices include a lot of older HarmonyOS builds, you don’t get that biggest performance dividend, so assess your device distribution.

Third, it solves a real problem.

Cross-platform on HarmonyOS used to offer basically two options:

• Write ArkUI separately for HarmonyOS, maintaining two UIs
• Skip HarmonyOS, wait for official support

Now there’s a third: keep writing shared logic, reuse the Compose UI, bridge existing ArkTS with akinterop.

For a team that’s already invested in KMP, the cost-benefit of that third road is hard to ignore.

Put it back in the arc of the last few days

Funny thing: this lines up with two topics from the last couple of days into one thread.

In the Jake Wharton piece, he puts it clearly:

Knowing Kotlin is no longer a career advantage… but having something more advanced like Kotlin Multiplatform can still be a differentiator.

The Shopify piece concludes: once AI makes “reimplementing it” cheap, the “share the UI” camp takes the biggest hit, while “shared logic + native UI” holds up better.

And then today: KMP’s map just gained another region — and a big one.

Three things point the same way: the value of cross-platform is shifting from “save headcount” to “architecture governance + ecosystem coverage”.

Chewing through platforms one at a time was always the core story of the KMP bet. With the HarmonyOS piece filled in, for developers in China especially — it may be the first time many of them have a real reason to look at KMP seriously.

One question to leave you with:

If you can write HarmonyOS UI in Compose, would you still maintain a separate ArkUI codebase for it, or just extend your KMP project to HarmonyOS?

And — for the project in your hands, is HarmonyOS a “must do” or a “let’s see”?

Comments are open, I really want to know where people actually are.

References:

• First official HarmonyOS release of KMP&CMP (Kuai Technology / Drive Home, 2026-09-15)
• Docs: search CPF-KMP-CMP/docs on AtomGit