DEV Community: Nek.12

How Does My Agent Survive 37+ Compactions in a Row? A Deep Dive into Proactive Compact in Builder

Nek.12 — Thu, 09 Apr 2026 11:11:43 +0000

How Does Compaction Work in Builder?

Today I shipped the 0.10.0 update to Builder CLI, and it landed huge improvements to compaction and cache efficiency.

Why Builder's Compact Is Better Than Native

By default, when you go through onboarding, Builder recommends the local proprietary compact, which is far more detailed than the native one. Native compact can still be selected or configured in the config file if your provider supports it. I recommend local - here's why.

The native compact algorithm for Claude Code and Codex was reverse-engineered a long time ago, and it's literally 5 - 7 lines of instructions along the lines of: "write a description of the work, idk, make no mistakes." I reverse-engineered the native compact myself to make sure of this and to pull out the best parts.

The only real advantage of native compact is preserving reasoning traces from previous conversation, but that can be achieved another way (described later). The local compact in Builder uses a carefully crafted prompt that I've been polishing for several months, covering all the important details that affect the agent's ability to continue working. Because of this, the compact can survive literally dozens of sessions without losing the overall task context. I have large refactors that ran autonomously through more than 37 compacts in a row, all night long - without any issues.

All of Builder's code is open source, so you can read the prompt. But without the harness improvements I also made for the compact, and without the ability to change this prompt in official harnesses, it won't get you very far.

Example: Builder ran through 22 compacts

The compact in Builder is also better than the original because it saves the entire conversation history no matter how many compacts you've had - but the model only sees the fresh history. That means you can roll back 19 compacts at any point, start a new conversation, fork it, and go off into a separate branch. On top of that, unlike some providers, Builder preserves cache, so it ends up being much cheaper. This is offset by the fact that my compact is more detailed - but as I've said, Builder's main goal is quality, not price tag or speed. In future versions I plan to optimize the compact so it contains nothing unnecessary and costs less than other providers.

Proactive Compact - New in 0.10.0

Beyond the prompt itself, the compact in Builder is proactive. Version 0.10.0 ships the first experimental tool that lets the model decide on its own when to run a compact. The model in Builder knows it has limited memory, knows how much space is left, knows when to make checkpoints - and gets a notification about remaining context.

Enable via:

[tools]
trigger_handoff = true

And this isn't implemented the way it is in Claude Code, where it freaks the model out and it refuses to work. And not the way Codex does it, where it constantly stops to "take a breather." In Builder, it's just one of the agent's autonomous processes - one that doesn't cause unnecessary pauses or degrade work quality!

Proactive compact prevents losing changes, breaking builds, tests, or overwriting your decisions in situations where the model runs out of context and compact gets triggered at a bad moment - causing it to forget that it has a file partially edited or a spec half-implemented. In my tests, the model knows on its own when it needs to hand off to the next agent, and prepares the workspace for that, which makes agent-to-agent collaboration across compacts much better.

Plus, the main agent can pass what's called a letter to the future to the next agent. The general compact prompt, especially the native one, often doesn't include specific things from the model's internal reasoning - things it knows but hasn't gotten to implement yet. Since reasoning traces aren't saved, my solution lets the model save them itself and pass them forward.

Builder prepared for compact, passed instructions for saving important info, triggered native compact, and continued working

Pre-Compact Before Starting a Task

Another UX improvement you won't find in other harnesses: pre-compact before starting a task. The harness constantly checks, whenever you send any command to the agent, whether there's enough context to complete the task - and based on heuristic analysis decides: should the task run now, or should it compact first and then move on to the next part of the plan?

This way your command is saved directly, doesn't go through an LLM summarization loop, doesn't waste tokens, and the agent starts fresh with clean context and no hallucinations. This lets you just talk to the model without thinking about compaction - the harness figures it all out alongside the model, freeing you from having to manually trigger slash commands or worry about hitting the "dumb zone." This is enabled by default.

Queues Across Compacts

The last improvement I really love - queue support across compacts. Your prompts, slash commands, and any processes, including background subagents, can survive compacts and transfer ownership to the next agent without any loss.

For example, you can queue up: right after a task completes - a compact with a custom prompt, then a slash command, and also spin up three background subagents. When the compact finishes, the model automatically receives your prompt, the summary, the message from the previous agent, your slash command, and the output from all three subagents - and picks up from that point as if nothing happened. No lost information, no stops, no limits on what you can do while the agent is running.

This seriously simplifies the workflow: give the agent a task, immediately schedule a compact, and then tell it to open a pull request and fix the comments in it with background agents for planning and execution. You won't find this in any harness out of the box. Maybe some allow it through hooks, but Builder's advantage is that all of this is implemented natively - with maximum integration out of the box.

Try Builder here

I got tired of every existing coding agent. So I built my own - Builder.

Nek.12 — Tue, 07 Apr 2026 15:39:29 +0000

Today I'm excited to show my new project I've been working on for the past 2 months - Builder.

It's a free and open-source coding agent built specifically for professional agentic engineers, and it works with your existing token subscription.

Why build your own when CC and Codex exist?

I used Claude Code for over five months, then spent a long time with Codex CLI and the desktop app, Opencode, Junie, and others. And all of these major projects share three core problems for me.

Opacity

Existing tools are opaque to a professional engineer. In Junie, instead of the actual commands the agent runs, you only see one-line descriptions of what's happening. In Codex, command calls are aggressively hidden and only accessible in transcript mode. And in Claude Code, instead of letting the model work freely through bash commands, it uses its own opaque custom toolset for reading, writing files, and searching.

Maybe that's fine for people who don't want to look at code and don't want to understand what's going on. But for an engineer who understands the process and wants to work with the model collaboratively - like with a pair programmer - it's a bad fit. And not a single agent wrapper I know of has ever focused on engineers.

Bloat

Many agentic harnesses pack in a ton of features for vibecoders that only make sense for specific workflows. For day-to-day work, agentic engineers find them more of a hindrance than a help. I'm talking about things like planning mode, 38+ persistent notifications in ClaudeCode, orchestration modes, Swarm, plugins, Explorer agents, and so on.

All of this not only gets in the model's way and pollutes the context, it also ruins the user experience - and nobody has actually proven the value of these "improvements" compared to straightforward prompting and iterative work with an agent. So I wanted an agent without a planning mode (which only constrains the model), and without the flashy gimmicks that prettify responses while making the model hallucinate (looking at you, Junie).
MCP deserves a special callout - it's been considered an anti-pattern in agentic development for a while now: it pollutes the context with useless tools, and most of them can't be used alongside bash tools.

All of this gets replaced by more effective strategies for engineers who direct the model as a coding agent, rather than delegating their own thinking to it.

Instability and closed nature

These kinds of harnesses often have their own opinions on how things should be done - and those opinions keep changing. With every update you can expect your workflow to change in some way too. It's unclear what's going on under the hood: what the system prompt looks like, how compaction works, missing settings, no real way to switch models or providers. You can't tell what ends up in the context, when cache invalidation happens, or what changed in the latest update that might have silently broken your workflow.

I simply got fed up with sitting down to work one fine day only to find my agent suddenly hallucinating - and it turning out to be yet another hidden bug in the harness that invalidated something under the hood and was feeding the model bad data. So I decided to write my own harness.

Builder CLI's background shell management

What makes Builder better

Collaborative architecture work

Many harnesses don't let models work together with the user on product and architectural design. One of the key things in my wrapper is giving the agent the ability to ask a question whenever it runs into a problem, a blocker, or finds something in the code it wants to refactor or improve.

In practice, this results in dramatically better output quality: agents no longer try to bulldoze their way through every problem and end up implementing terrible, broken solutions or trashing the architecture. Instead, they ask a question and solve the problem together with the user.

Instrumented workflow instead of blind trust

The second key thing is evolving agentic harnesses beyond a simple loop where the agent spins and is just trusted to do everything right - toward a clearly instrumented workflow that prevents the agent from making dumb mistakes. Many agents start hallucinating - and that's normal for the current state of models. Even people forget things, lose context, miss small details that can actually matter. That's why in Builder, a separate parallel agent always watches over your agent's work, checking its output for quality and compliance with your project's rules.

Quality over token savings

Large agent wrappers right now are optimized for quick fixes, minimal viable solutions, conserving context and tokens. Essentially, you're paying with output quality and your own time spent cleaning up after the model - all to save a few thousand tokens and run 20% faster.

In Builder's design, I'm focused first and foremost on output quality: proper architecture, code safety, performance, first-principles solutions - not the hacks that are currently the default for virtually every agent.

What's already there

I've already fully replaced Codex CLI with Builder and don't open it anymore. I use it for everything, including work tasks.

Current features:

Agent loop equivalent to Codex CLI
Background tasks, background agents, subagents, orchestration
Supervisor - a parallel agent that continuously watches the model and improves its results
Auto and manual context compaction in multiple modes; native Codex compaction is supported via settings, but I've long since switched to Builder's own compaction, which is several times better in quality
Two display modes: compact and detailed. In detailed mode, full information about what the model did is available - something like a transcript view, but with far more data than in Codex or Claude Code
Questions from the model to the user
Model steering and prompt queuing
Native image and PDF viewing
Native web search
Prompt and session history
Notifications (including system notifications) when the model finishes
agents.md standard support
Agent Skills support
Code syntax highlighting
Custom slash commands and many built-in ones
Conversation editing and forking
Lots of keyboard shortcuts
Toggles for OpenAI: turbo mode, model verbosity, thinking mode

I'm currently actively working on worktree management and also laying the groundwork for a native desktop app.

Finished the code review

What won't be there

So you can decide whether Builder is right for you, here's what conflicts with its philosophy and won't be implemented:

MCP support - pollutes the context and is incompatible with bash tools
Planning mode - a legacy leftover from Anthropic's models that constrains the model
UI bells and whistles for people who aren't doing serious programming
Micro-compaction and anything that invalidates caches - it costs a lot of money
Sandbox - ClaudeCode, Codex, and Junie still don't have proper sandboxing, and I've been using them without it for a long time. As a professional engineer I simply don't end up in situations where the model deletes something. Safety is handled through proper prompting right now; file editing is configurable and access can be restricted. Sandboxing won't save you on any OS from destructive actions - so I decided not to put on the tinfoil hat.
WebFetch or equivalent - there's already a CLI, Markdown standards, and skills for that. No need for an extra tool that hands the model an LLM-processed Medium article. Just use any CLI script like jina.ai if the agent needs internet access.
Gemini and Anthropic subscriptions - because those are now illegal for us.

Current state

The product is quite ready to use, but I realize I focused primarily on the features I use myself to start dogfooding it as quickly as possible. So I haven't tested the agent on Windows or Linux, haven't tested it with a bare API key, and haven't implemented support for other model providers.

Please report any issues and missing features - open an issue on GitHub and I'll do my best to address everything. Any feedback is very welcome.

Getting started guide

I'd also love some stars on GitHub.

I switched to a tiling window manager on macOS. Full breakdown: Aerospace, Amethyst, and Yabai

Nek.12 — Fri, 27 Mar 2026 11:08:25 +0000

A week ago I ran into a problem. I started using more and more parallel workflows and more and more terminal tabs. I use Ghostty, but keeping up with that many tabs - even with its pretty solid UX - became simply impossible. I had 3 - 4 windows open with two to four tabs each running in parallel, and the entire workflow depended purely on window order and which one was currently in focus. For working with agents across multiple projects and multiple clients simultaneously - that approach just doesn't work anymore.

I tried Cmux - a new terminal emulator built on top of Ghostty - but it's still rough around the edges: no native tabs, ugly UI, no blur. The concept is solid, but the implementation needs more time. That said, I know plenty of people who are very happy with cmux - if you're not as picky about UI/UX as I am, you'll really like its workspace-based model: each workspace is a separate tab with a single terminal session. You could also try Codex App, but since I have my own agent, I didn't want to switch to a desktop Electron app lacking the features I need just because I couldn't manage my windows properly. The solution for me turned out to be tiling window managers, which I'd been wanting to try for a long time.

What is a tiling window manager

A tiling window manager is something that came from Linux. It's a non-traditional window management system: instead of manually dragging and resizing windows, the window manager does all of that for you using various algorithms when a window is opened or its boundaries change. You say: I have X windows, I want them to fill the entire screen in the most convenient arrangement without overlap - and the manager does it for you. A tiling WM simply won't allow a single pixel of empty space on the screen: it constantly resizes windows so they stay snapped together with a sensible distribution.

On Mac there are only three options, because macOS has serious limitations - you can't replace the window manager entirely like you can on Linux. Your experience will always be second-rate compared to Linux, but there are working solutions.

The main macOS bug you need to know about

There's a major bug in macOS that will seriously affect your workflow. That's exactly why I say the experience is second-rate. All native tabs in macOS apps are treated as new windows by window managers - there's no way to tell whether it's a tab or a window. macOS always sends a signal that a new window was opened, even if what actually happened was a new tab opening in an existing window. This means your tiling WM will treat all open tabs as new windows, and empty space will keep multiplying on your screen depending on how many tabs you have open.

There's no fix for this, and any app using native macOS tabs will behave badly in a tiling WM. Ghostty uses native tabs - which is exactly why I had to ditch the tab concept in my terminal entirely.

My current workflow

I disabled tabs in Ghostty and even the window affordances, and moved as fully as possible to keyboard-driven control - part of a broader focus on moving away from the mouse. Right now I can't even see the close and minimize buttons in my terminal. Other apps keep them - like Android Studio, which spams modal windows and needs to be maximized to full screen, or Telegram, which I want to float on top of everything.

For the terminal, I open, close, and minimize windows with hotkeys that are flexibly configured in Ghostty. The screen splitting logic works like this:

I open the first terminal - it takes up the full screen.
I open a second one via CMD+N - the space immediately splits in half, each terminal takes exactly 50%.
I open a third window - the half where focus was splits again. The new terminal opens in the same folder I was in at the moment of opening.
Each additional window divides the space using the golden ratio principle (Binary Space Partitioning): depending on whether there's more horizontal or vertical space in that particular section of the screen.

This lets you spawn child windows from a single window in the same directory and launch things like Vim or multiple copies of a dev agent inside them.

At some point, as you can see in the screenshot above, I'm already close to the limit of what my brain can handle. So I separate workflows by project using standard macOS Spaces: a dedicated Space for my agent, for Respawn, for each client project - and one extra for general tasks.

Three tiling WM options for macOS

One thing upfront: all the configuration was done for me by my assistant OpenClaw, not by me. Tiling window managers are a pretty niche product aimed at developers - configuration is done via YAML files in various folders or through bash macros for hotkey management. I would have taken forever figuring it out on my own.

Aerospace

The first option I wanted to try. It has a fairly convenient YAML configuration, though I still couldn't be bothered to dig into it. It's a clone of the i3 window manager from Linux - those who know, know.

The main problem for me: it's manual. Opening any window doesn't trigger an automatic relayout of the rest. I needed the window manager to handle all windows for me automatically, so I had to drop Aerospace.

That said, it's stable, highly configurable, it has handy workspace functionality with fast switching and even some semblance of a user interface on Mac. Aerospace has window groups, each with its own layout mode. One group is split vertically into columns, another is split horizontally in half, a third isn't split at all. You manage them manually through hotkeys. The concept is really cool if you're willing to learn how to work with them and memorize all the necessary hotkeys. If you've already used a tiling WM on Linux - I'd recommend Aerospace first, it's the closest thing to a proper professional window manager experience on macOS.

Amethyst

A completely different approach - more simplified and user-friendly. Amethyst has a full graphical interface via an icon in the menu bar, where you can configure everything, though YAML configs are also supported and take priority.

For me the biggest issue was that it doesn't support mouse control - everything is keyboard only. Sometimes my layout is complex enough that I just want to drag a window with the mouse instead of fumbling with arrow key combos. It also has poor support for modal windows and dialogs - they're treated as separate windows, and when a tiny "Do you want to send a voice message?" popup appears in Telegram, the entire screen gets wrecked: all windows shuffle around to make room for it. So I just stopped using it. But I'd recommend trying Amethyst first if you want to get into the world of tiling WMs - the GUI makes the entry point much gentler.

Yabai

The last contender, and the one I settled on. As far as I know, it's the oldest tiling WM project on macOS. It supports the Fibonacci layout (Binary Space Partitioning) that I wanted, and generally has all the features of the previous two combined.

Two downsides. First, Yabai has no graphical interface at all - all configuration is through bash scripts and shell commands, it runs as a background service, and it's started and stopped via the terminal. On one hand, that's a barrier to entry; on the other, I just told my OpenClaw to set up the configuration I needed, and it set everything up in 10 seconds. A one-time setup overhead is much better than tolerating some other persistent bug.

Second, Yabai has no built-in hotkey support - you need a separate utility that translates hotkeys into shell commands. OpenClaw recommended skhd. I honestly don't even care what that is - I just asked the agent to set everything up and sent it a list of the hotkeys I needed, and it was all ready in a minute. An unexpected bonus of yabai was that it works really well with AI agents: my Gemini already knew absolutely everything about its configuration options, so setting it up from a single voice message in Telegram took 10 seconds.

Yabai has a lot going for it. Beyond supporting all the features I needed, it has a handy visual highlight when dragging windows with the mouse: you can immediately see exactly how the space will be split and where the window will end up. This makes mouse-based rearranging so simple and intuitive that, I'll admit, I now often skip the hotkeys and just use the mouse.

Additionally, Yabai supports extended features when you partially disable macOS system security - you can remove shadows, rounded corners, and the slow transition animations between Spaces. The main advantage - it uses native macOS Spaces instead of its own, which means support for different Spaces on different monitors. All the other options require you to disable this feature or they break. I didn't install the system extensions myself: every update requires a reboot and re-disabling security, which is more annoying than the slow animations.

Yabai can also be disabled with a single shell command - handy when you want to play games or let someone else use the computer.

If you have an agent that can configure everything for you and you want the best option with maximum control - go with Yabai. But I wouldn't install it just to try it out: by default it ships with no configuration and barely works until you create the config files.

Conclusion

Will I keep using a tiling window manager? Absolutely - at least until the problem of managing dozens of windows while working with agents gets solved. Maybe cmux will get polished up and I'll switch to that, but every day I like tiling WM more, and I notice I'm using the mouse less and less. I'll never go back to native macOS features like Stage Manager - objectively, that thing is unusable.

Case Study: How I Sped Up Android App Start by 10x

Nek.12 — Thu, 29 Jan 2026 13:48:44 +0000

At my last job, we had a problem with long load times, especially for the first launch of our Android app. ~18% of people were leaving before the app even opened. I was tasked with fixing this situation and achieving an app load time of under 2 seconds.

At first glance, the task seemed impossible, because the app on startup hits the backend more than four times, registers a new anonymous user, exchanges keys for push notifications, initializes three different analytics SDKs, downloads remote configuration, downloads feature flags, downloads the first page of the home screen feed, downloads several videos that play on app start during feed scrolling, initializes multiple ExoPlayers at once, sends data to Firebase, and downloads assets (sounds, images, etc.) needed for the first game. How can you fit such a huge volume of work into less than two seconds?!

After two weeks of meticulous work, I finally did it! And here's a complete breakdown of how I made it happen.

Audit and Planning

I conducted a full audit of the codebase and all logic related to app startup, profiled everything the app does on start using Android Studio tooling, ran benchmarks, wrote automated tests, and developed a complete plan for how to achieve a 2-second load time without sacrificing anything I described above.

Implementing all of this took just one week thanks to the fact that I planned everything out, and the team could parallelize the work among several developers.

What I Did

1. Switching from Custom Splash Screen to Android Splash Screen API

We switched from a custom splash screen, which was a separate Activity, to the official Android Splash Screen API and integrated with the system splash screen. I've written many times in my posts and always say in response to questions, or when I see developers trying to drag in a custom Activity with a splash screen again, or some separate screen in navigation where they load something: this is an antipattern.

Our Splash Activity contained a huge ViewModel with thousands of lines, had become a God Object where developers just dumped all the garbage they needed to use, and forced all the rest of the app logic to wait while it loaded. The problem with custom Activities is that they block the lifecycle, navigation, and take time to create and destroy. Plus, they look to the user like a sharp, janky transition with the system animation that Android adds when transitioning between Activities. This creates a user experience that increases not only the actual load time, but also how it's perceived by the user.

We completely removed the Splash Activity and deleted all two thousand lines of code it had. We switched to the Splash Screen API, which allowed us to integrate with the system Splash Screen that Android shows starting from version 8, add an amazing animation there, and our own custom background.

Thanks to this, because we were no longer blocking data loading for the main screen with this custom Activity, we got a significant boost in actual performance from this change. But the biggest win was that people stopped perceiving the app loading as actual loading. They just saw a beautiful splash animation and thought that their launcher was organizing the app start so nicely for them. And even if they thought the app was taking a long time to load, they were more likely to think it was because of the system or because of the load on their phone (and most often - that's exactly what it is), and not because the app is lagging, because the system Splash Screen looks like a part of the OS, not of the app.

2. Developing a Startup Background Task System

In order to get rid of this huge Splash Activity, I needed to develop a custom system of startup jobs that executed when the app launches. In pretty much any app there are a lot of things that need to be done on startup: asynchronous remote config updates, reading something, initializing SDKs, feature flags, sending device or session analytics data, loading services, checking background task status, checking push notifications, syncing data with the backend, authorization.

For this, I made an integration with DI, where a smart Scheduler collects all jobs from all DI modules in the app and efficiently executes them with batching, retry, and error handling, sending analytics, and measuring the performance of all this. We monitored which jobs took a lot of time in the background afterwards or which ones failed often, diagnosed and fixed issues.

Another architectural advantage of the system I developed is that developers no longer had to dump everything in one pile in the Splash Activity ViewModel. They got access to registering background jobs from anywhere in the app, from any feature module, for example. I believe that problems with app behavior aren't a question of developer skill, it's a question of the system. This way, I helped the business by creating an efficient system for executing work on startup that's fully asynchronous and scales to hundreds of tasks, many years into the future.

3. Switching to Reactive Data Loading Model

We historically used old patterns of imperative programming and one-time data loading. This was probably the most difficult part of the refactoring. But fortunately, we didn't have that much tied to imperative data loading specifically on app startup:

I migrated to asynchronous data loading using Jetpack DataStore. They have a nice asynchronous API with coroutine support, that is non-blocking, and this significantly sped up config loading, user data loading, and auth tokens.
Next, I migrated to a reactive user management system. This was the hardest part at this stage. Our user object was being read from preferences on the main thread, and if it didn't exist, every screen had to access the Splash Screen to block all processes until a user account was created or retrieved from the backend and the tokens were updated.

I redesigned this system to an asynchronous stream of updates for the user account, which automatically starts loading them on first access as early as possible on app startup. And changed all the logic from blocking function calls that get the user to observing this stream.

Thus, also thanks to the fact that we use FlowMVI - a reactive architecture, we got the ability to delegate loading status display to individual elements on the screen. For example, the user avatar & sync status on the main screen loaded independently while the main content was loading asynchronously, and didn't block the main content from showing. And also, for example, push registration could wait in the background for the User ID to arrive from the backend before sending the token, instead of blocking the entire loading process.

In the background, we were also downloading game assets: various images and sounds, but they were hidden behind the Splash screen because they were required for the first game launch. But we didn't know how many videos a person would scroll through before they decided to play the first game, so we might have plenty of time to download these assets asynchronously and block game launch, not app launch. Thus, the total asset load time could often be decreased down to 0 just by cleverly shifting not loading, but waiting. I redesigned the asset loading architecture to use the newly developed background job system, and the game loading logic itself to asynchronously wait for these assets to finish downloading, using coroutines.

4. Working with the Backend

Based on my profiling results, we had very slow backend calls, specifically when loading the video feed on the main screen.
I checked the analytics and saw that most of our users were using the app with unstable internet connections. This is a social network, and people often watched videos or played games, for example, on the bus, when they had a minute of free time.

I determined from benchmark results that our main bottleneck wasn't in the backend response time, but in how long data transfer took.

I worked with the backend team, developed a plan for them and helped with its execution. We switched to HTTP/3, TLS 1.3, added deflate compression, and implemented a new schema for the main page request, which reduced the amount of data transferred by over 80%, halved TCP connection time, and increased the data loading speed by ~2.3x.

5. Other Optimizations

I also optimized all other aspects, such as:

Code precompilation: configured Baseline Profiles, Startup Profiles, Dex Layout Optimizations. Net ~300ms win, but only on slow devices and first start;
Switched to lighter layouts in Compose to reduce UI thread burst load;
Made a smart ExoPlayer caching system that creates them asynchronously on demand and stores them in a common pool;
Implemented a local cache for paginated data, which allowed us to instantly show content, with smart replacement of still-unviewed items with fresh ones from the backend response. Huge win for UX.

Also, on another project, in addition to this, I managed to move analytics library loading, especially Firebase, to a background thread, which cut another ~150 milliseconds there, but more on that in future posts I will send to the newsletter.

Results

Thus, I was able to reduce the app's cold start time by more than 10 times. The cold first app start went from 17 seconds to ~1.7.

After that, I tracked the impact of this change on the business, and the results were obvious. Instead of losing 18% of our users before onboarding started, we started losing less than 1.5%.

Optimizing app startup time is quite delicate work and highly personalized to specific business needs and existing bottlenecks. Doing all this from scratch can take teams a lot of time and lead to unexpected regressions in production, so I now help teams optimize app startup in the format of a short-term audit. After analysis (2-5 days), the business gets a clear point-by-point plan that can be immediately given to developers/agencies + all the pitfalls to pay attention to. I can also implement the proposed changes as needed.

If you want to achieve similar results, send your app name to me@nek12.dev, and I'll respond with three personalized startup optimization opportunities for your case.

AGP 9.0 is Out, and Its a Disaster. Heres Full Migration Guide so you dont have to suffer

Nek.12 — Tue, 20 Jan 2026 13:20:25 +0000

Yesterday I migrated a big 150,000-line project from AGP 8 to AGP 9. This was painful. This is probably the biggest migration effort that I had to undergo this year. So, to save you from the pain and dozens of wasted hours that I had to spend, I decided to write a full migration guide for you.

Be prepared, this migration will take some time, so you better start early. With AGP 9.0 already being in release, Google somehow expects you to already start using it yesterday. And they explicitly state that many of the existing APIs and workarounds that you can employ right now to delay the migration will stop working in summer 2026. So for big apps, you don't have much time left.

Before we start, please keep in mind that despite AGP somehow being in production release, a lot of official plugins, such as the Hilt plugin and KSP, do not support AGP 9.0. If you use Hilt or KSP in your project, you will not be able to migrate without severe workarounds for now. If you're reading this later than January 2025, just make sure to double-check if Hilt and KSP already have shipped AGP 9.0 support.

If you're not blocked and still here, here is what you need to do to migrate your KMP project to AGP 9.0.

The biggest migration point: Dropped support for build types

Previously, we didn't have build types on other platforms in KMP, but Android still had them. And in my opinion, they are one of the best features for security and performance that we had, but now they will not be supported and there is no replacement for them. You literally have to remove all build type-based code.

At first glance, this seems like a small problem, because teams usually don't split a lot of code between source sets. It usually revolves around some debug performance and security checks. But there is a hidden caveat. BuildConfig values will stop working completely, because they are using the build types under the hood.

I had in my codebase dozens and dozens of places where I had a static top-level variable isDebuggable, delegating to BuildConfig.DEBUG, which I was checking and using a lot to add some extra rendering code, debugging, logging code, and to disable many of the security checks that the app had, which were only applicable on release.

Why I was using it as a static variable instead of something like context.isDebuggable is because the R8, when optimizing the release build of the app, would be able to remove all of that extra debug code without the need to create extra source sets, etc. This works well for KMP, where release and debug split wasn't fully supported in the IDE for a long time.

But now this is completely impossible. This is a huge drawback for me personally, because I had to execute a humongous migration to replace all of those static global variable usages with a DI-injected interface, which was implemented using still build configuration, but in the application module, e.g.:

// in common domain KMP module
interface AppConfiguration {
    val debuggable: Boolean
    val backendUrl: String
    val deeplinkDomain: String
    val deeplinkSchema: String
    val deeplinkPath: String
}

// in android app module
object AndroidAppConfiguration : AppConfiguration {
    override val debuggable = BuildConfig.DEBUG
    override val backendUrl = BuildConfig.BACKEND_URL
    override val deeplinkDomain = BuildConfig.DEEPLINK_DOMAIN
    override val deeplinkSchema = BuildConfig.DEEPLINK_SCHEMA
    override val deeplinkPath = BuildConfig.DEEPLINK_PATH
}

This may result in a significant refactor, because I personally used the static isDebuggable flag in places where context/DI isn't available. So, I had to sprinkle some terrible hacks with a global DI singleton object retrieval just to make the app work and then refactor the code.

When you're done with this step, you must have 0 usages of BuildConfig, build types, or manifest placeholders in library modules. Note that codegen for build-time constants is still fine, just not per-build-type / Android one. You can create a custom Gradle task if you want that will generate a Kotlin file for you in ~20 lines.

I know that devs love BuildConfig.DEBUG a lot, and I also used it to manage deep link domains, backend URL substitution for debug and release builds, and all of that had to be refactored, which is why I urge you to stop using such code pattern with these static isDebuggable flags right now.

Also avoid using Context.isDebuggable boolean property, because that's a runtime check which can be overridden by fraudulent actors, so it isn't reliable. Don't use it for security reasons. Remember - debug code should only be included in debug builds.

Remove all NDK and JNI code from library modules

The next step you have to take is remove all the NDK and JNI code that you have in library modules. I have a couple of places where I need to run some C++ code in my app, and those were previously located in the Android source set of the KMP library module where they were needed, because Apple source set didn't need that native code, but Android did.

An official statement from Google is that NDK execution in library modules and C++ code execution and JNI will not be supported at all since AGP 9.0. So now, the only way you can preserve that code is if you move it to the application module. Again, that is something that is a huge drawback for me, but because Google didn't give us any opportunities and didn't want to listen, you have to comply if you do not want to get stuck on a deprecated AGP forever.

So before you even try to migrate to AGP 9.0, make sure you create an interface abstraction in your library module that will act as a proxy for all your NDK-enabled code. Then the implementation of that interface can live in the application module along with all the C++ code and inject the implementation into the DI graph so that your library module in the KMP code can just use that interface. At least this is what I did. This is the simplest solution to the problem, but if you know a better one, let me know.

The actual migration: Remove the old Kotlin Android plugin

Now we are finally finishing up with all the refactorings and approaching the actual migration. Start by removing the old Kotlin Android plugin. I had convention plugins set up, so it was reasonably easy for me to do, and migrate it to the new plugin. Read this docs page for what exactly to do.

When you remove it, also add the new plugin for Android Kotlin Multiplatform compatibility: com.android.kotlin.multiplatform.library. This is because your build will stop working and we need to migrate to the new DSL, which is only provided with this new plugin.

To fix gradle sync, do:

Update from the deprecated Android top level DSL android { } AND the deprecated kotlin.androidLibrary {} DSL to the new unified kotlin.android { } DSL. You should be able to copy-paste all of your previous configuration, like compile SDK, minimum SDK, and all of the other Android setup options which you previously had in the top-level Android block, and merge it with the code that you previously had in the kotlin.androidLibrary KMP setup. So now it's just a single place. Note that library modules no longer support target SDK, which will only be governed by the app module.

     id("sharedBuild")
     id("detektConvention")
     kotlin("multiplatform")
-    id("com.android.library")
+    id("com.android.kotlin.multiplatform.library")
 }

 kotlin {
     configureMultiplatform(this)
 }

-android {
-    configureAndroidLibrary(this) 
-}
-

See how I had an extension function from my convention plugin, configureAndroidLibrary, and removed it? We can now completely ditch it. Everything will be inside the kotlin block. (configureMultiplatform in example above).

Next up, let's update the said "configure multiplatform" function. This is based on this official doc page:

-    if (android) androidTarget {
-        publishLibraryVariants("release")
+    if (android) android {
+        namespace = this@configureMultiplatform.namespaceByPath()
+        compileSdk = Config.compileSdk
+        minSdk = Config.minSdk
+        androidResources.enable = false
+        lint.warning.add("AutoboxingStateCreation")
+        packaging.resources.excludes.addAll(
+            listOf(
+                "/META-INF/{AL2.0,LGPL2.1}",
+                "DebugProbesKt.bin",
+                "META-INF/versions/9/previous-compilation-data.bin",
+            ),
+        )
+        withHostTest { isIncludeAndroidResources = true }
         compilerOptions {
             jvmTarget.set(Config.jvmTarget)
             freeCompilerArgs.addAll(Config.jvmCompilerArgs)
         }
+        optimization.consumerKeepRules.apply {
+            publish = true
+            file(Config.consumerProguardFile)
+        }
     }
     // ... 
     sourceSets {
         commonTest.dependencies {
             implementation(libs.requireBundle("unittest"))
         }
-        if (android) androidUnitTest {
-            dependencies {
+        if (android) {
+            val androidHostTest = findByName("androidHostTest")
+            androidHostTest?.dependencies {
                 implementation(libs.requireLib("kotest-junit"))
             }
         }
    }

In summary, what has changed here is that we had an androidTarget block which contained a small portion of our library module setup. That was replaced by the android block (not top-level, I know, confusing). And now we just put everything from our previous Android top-level block in here, and we removed the target SDK configuration, which was previously available here. Some syntax changed a bit, but this is only because I'm using convention plugins, so they don't have all the same nice DSLs that you would have if you just configured this manually in your target module.

As you see, I put the new packaging excludes workarounds that have been there for ages into this new place. I moved the Lint warning configuration (that was used by Compose). Don't forget to disable Android resources explicitly in this block because most of your KMP modules will not actually need Android resources, so I highly recommend you enable them on-demand in your feature modules where you actually need them. This will speed up the build times.

You can also see that instead of androidUnitTest configuration that we had, we just have androidHostTest, which is basically the same Android unit tests you're used to. Host means that they run on the host machine, which is your PC. This is just a small syntax change, annoying but bearable.

Don't forget to apply the consumer keep rules here, because a widely used best practice is to keep the consumer rules that are used by a particular library module together in the same place instead of dumping all of that into the application module. I was personally not happy about moving all of my consumer rules to the ProGuard rules file of the application module, so I just enabled consumer keep rules for every library module I have. This is especially useful for stuff like network modules, database modules, where I still have custom keep rules, and for modules which are supposed to use NDK and C++ code. If you don't do this, the new plugin will no longer recognize and use your consumer keep rules, even if you place them there, so this is pretty important, as it will only surface on a release build, in runtime (possibly even in prod).

Now, as you might have probably guessed, the top-level android block will no longer be available for you. There will be no build variants, build flavors in those KMP library modules. So before, if you were following my instructions and already refactored all of those usages to move them to the application module and inject the necessary flags and variables via DI, you will hopefully not have a lot of trouble with this. But if you still do use some BuildConfig values, there is now no place to declare them. Same can be said for res values, manifest placeholders, etc. All of that is now not supported.

Important note for Compose Multiplatform resources

Previously, you saw that we disabled Android resources. But if you don't enable Android resource processing, even for KMP modules with CMP resources, now in your feature modules and UI modules, your app will crash at runtime.

kotlin {
    androidLibrary {
        androidResources { enable = true }
    }
}

Add this block to every module that you have that uses Compose Multiplatform resources. I had a convention plugin for feature modules, which made this super easy for me. More details are under the bug ticket on YouTrack.

Replace Android Unit Test with Android Host Test

The next step is to replace Android Unit Test dependency declarations with Android Host Test declarations. You can do this via an IDE search and replace using a simple regex.

-    androidUnitTestImplementation(libs.bundles.unittest)
+    androidHostTestImplementation(libs.bundles.unittest)

You'll have to do this for every single module that has Android unit test dependencies. I unfortunately didn't think of a convention plugin, so I had to run this on literally every single build.gradle file.

I also had to refactor Gradle files a little bit because I used top-level implementation and api dependency declaration DSL functions:

dependencies {
    implementation("...") // wrong
}

This wasn't correct anyway, and it was incredibly confusing because this "implementation" just meant Android implementation, not KMP implementation, so that was a good change.

I'm also using FlowMVI in my project, and unfortunately, the FlowMVI debugger relies on Ktor, serialization and some other relatively heavy dependencies that were previously only included in the Android debug source set, but I had to ditch that and just install the FlowMVI debugger using a runtime-gated flag from DI that I mentioned above. This doesn't make me happy, but in the future I will improve this maybe by moving the installation of the plugin to the Android app module, since FlowMVI makes extending business logic super easy.

Add build script dependency on Kotlin

Finally, I recommend adding a new build script dependency on Kotlin, just to keep your build Kotlin version and runtime Kotlin versions aligned. I wanted that because I have a single version catalog definition. You do it in the top-level build.gradle.kts:

buildscript {
    dependencies {
        classpath(libs.kotlin.gradle) // org.jetbrains.kotlin:kotlin-gradle-plugin
    }
}

Small quick optional wins at the end

Ditch android.lint.useK2Uast=true that is deprecated now if you had it.
An optional step is to use the new R8 optimizations described in the document I linked above. We have had manual ProGuard rules for removing the Kotlin null checks, and now this is shipped with AGP, so I just migrated to the new syntax (-processkotlinnullchecks remove)

Honestly, this migration was a huge pain to me. I'm not gonna claim that I have the perfect code, but my Gradle setup was decent. If you're a developer and this all sounds incredibly overwhelming and like a huge effort, you're right. Because I already did it, I can help your team migrate your project to the new AGP much faster and save you the effort. I recently started taking projects as a consultant and KMP migration advisor, so consider giving your boss a shout-out to nek12.dev if you liked this write-up and want me to help you.

What are AI agent skills and how to use them - complete breakdown with examples

Nek.12 — Mon, 12 Jan 2026 19:09:46 +0000

What are agent skills and why do you need them?

A relatively new thing in the world of AI agents is the so-called Skills system.

Recently I started seriously developing skills. I even created a marketplace of Claude plugins for Respawn, where I keep a skill for ksrc and a skill for FlowMVI. I'm increasingly using and creating different skills, and many of you are asking: "What even is this?". And I also see articles on the internet that incorrectly explain and incorrectly recommend creating and using skills.

So, initially skills were invented by Anthropic as part of their SDK for Claude Code. Essentially, agent skills don't bring anything revolutionary - they're still just folders with markdown files. The most important thing is how they work - through so-called progressive disclosure of your agent's context. I've already said that the most important thing when working with agents is context engineering, and this is another way to use context more effectively.

How do skills work?

Skills are defined by one main file (SKILL.md), and it has a specific frontmatter structure. In this frontmatter there's the skill name (what it teaches) and a description - a (very!) short description that ideally explains when to use this skill and what it can teach the model.

When your agent wrapper notices that you have such a file in your skills folder, it parses its header and includes it immediately in the agent's context (literally as part of agents.md or claude.md). This way you get a hook for the LLM:

Use this skill when you're writing code with FlowMVI.

Models have already become so smart that they can understand in what development context they need to read and use this skill, by one line of text. And the skills system takes advantage of this. For me it's like casting a fishing line - the model sees the bobber on the surface, and then it can pull up a whole huge pile of documentation if needed and search through it for anything it needs.

Skill structure

The header is written in the SKILL.md file. In this file you describe your skill's structure: what folders exist, what files exist, and the main points about usage.

For example, in my skill for FlowMVI the model is given the ability to view the documentation index, where all the nuances and details of using a specific feature are laid out (state management or creating plugins). But in the skill.md file itself, which the model reads fully if it decides to use the skill, basic things are written: "FlowMVI is an architectural framework, here's how to quickly make a contract, here's how to write features, here's what DSL exists, and here's where you can look at function signatures".

So context disclosure happens in stages: the model first sees a super-brief two-line header, then reads the main skill.md file (a few hundred lines), and then can decide: "Aha, I understand, now I need to read the next file, for example, on creating custom plugins". The model goes to the appropriate folder next to the skill.md file or makes internet requests, as in my case, to get fresh documentation.

This way we achieve minimal context spending on knowledge for the model, unlike, for example, MCP or AGENTS.md, which are just thrown into the model's context as one huge chunk of text, regardless of whether they're needed or not.

Why does your model need to know how to deploy your backend to production if it's currently doing minor fixes after review? That's the whole point of skills: don't give the model everything at once to avoid cluttering the context, but gradually reveal only the needed information and let the model use its incredibly cool search capabilities and work with the command line to find specifically what it needs.

Why do you need to create skills?

You need skills to transfer specialized or fresh knowledge to the model in progressive form - knowledge that's not yet included in the model's training data.

You can create skills for:

Proprietary SDKs and how to work with them (store them in your repository then)
New APIs that came out only a few months ago, and the model still can't handle working with them
Niche frameworks that aren't yet in training data

What NOT to include in skills

The most important thing is what you shouldn't create skills for: things the model likely already knows.

You don't need to create a skill for:

"How to compile Kotlin code"
"How to write SwiftUI"
"How to work with OpenAI API"

Models already know this perfectly well based on millions of lines of code and all the documentation that exists on the internet. I've seen skills with absolutely useless content. And if the model reads such a skill, it will only work worse, because its context will be clogged with irrelevant or repetitive information that doesn't help the model but distracts it.

Before creating a skill, think: can the model already know what I'm trying to tell it? And completely cut out everything the model already knows from your skill.

For example, with ksrc the model doesn't need to know that ksrc is written in Go, how to use escape sequences, how to use sed syntax, how to use ripgrep, and how to make bash command chains. The model does this perfectly, and it doesn't need to be repeated. But what the model doesn't know is how and why to work with ksrc. So that's exactly what I included in the skill.md file for ksrc, and nothing more.

If you need to include something the model already knows, you can just reference it in one or two words. For example, instead of describing in detail how grep search syntax works and what arguments are supported, just write: "Ripgrep arguments are fully supported" or "Add --rg-args at the end to filter results". That will be enough.

The skill for FlowMVI works the same way. In general, models have long known what MVI frameworks are, but they specifically don't yet know ideally the syntax of FlowMVI specifically as a framework and might not know what changed in new versions. So my skill contains not a single word about what intents and side effects are, and what should go in the MVI state. Because this is general knowledge that the internet has been covered with for years, decades, and the model knows this perfectly. Instead, the skill consists of function signatures and available configuration parameters in different DSL functions and some common mistakes that the model makes in my experience working with the library. That is, it specifically covers the model's weak spots, spending a minimum number of tokens.

When should you create skills?

Usually this is needed when your agents.md files are growing, or when you're releasing some framework that's expected to be used by models too.

For example, ksrc is intended for use only by models, developers don't need to use it. FlowMVI is used by both developers and models, so the skill is more of a nice bonus. But in any case, if a model will use this utility, it would be great if you shipped a skill that can be installed right away.

Why? The model will either not use the utility at all (simply because it doesn't know about its existence), or won't use it correctly (because without reading documentation it won't know the syntax). This is a good way to reduce agents.md and reduce tokens spent on manual documentation search by models.

If you see that the model is stumbling on something - for example, writing code that doesn't compile, or incorrectly using the new Compose API, or can't make a Glance widget correctly - you can gather the documentation, pack it into a skill, and if you do it right, this can solve your problems with model performance when working with a specific technology.

How to create skills

Skills are repackaged documentation for some framework. So start by creating a good header and skill.md.

Most often in your code (for example, in Codex) there's already a built-in flow for creating skills. You just use a skill for creating skills (so meta 😅). And Codex, for example, will create the whole skill with everything you need. You just tell it where to get the framework documentation, and then it will work to pack it into a skill.

One thing: after creating a skill you still need to go through all the files it created and clean them up. Or initially prompt the model to specifically describe the moments that, as you already know from practice, are pain points / difficult and complex features to use. Because by default the model will just rewrite the documentation into skill.md and might also miss many points.

For example, in FlowMVI I had to redo a lot because I wanted the model to pull the most updated documentation itself via curl, and in skill.md and in the skill folder there would be only function signatures.

Start with the template that the model will create for you in your wrapper, and then refine it.

Conclusion

My opinion is that skills are a very cool way to save context. And this feature hit the LLM development curve really well, because models have now become so easy to prompt that one line is enough for perfect execution of instructions by the model.

So you just create a skill, write one line in it "Use ksrc to search sources", and you can count on the model already being so smart that it will understand on its own when to use this skill. This is very easy for you and saves context significantly and increases model performance.

I often hear people complaining: "My model doesn't write compiling code" or "Can't work with some niche libraries", and the answer was always on the surface - as usual it's just markdown files.

Agents and Gradle Dont Get Along - I Fixed It in Two Commands

Nek.12 — Tue, 06 Jan 2026 17:37:58 +0000

Folks, today I'm excited to introduce my new project!

First, I should say that I primarily write in Kotlin. In Kotlin, we have a problem with viewing and exploring the source code of third-party libraries. I've used TypeScript, Go, and Kotlin, and I can say that I envy those who code in TypeScript, because agents, when working with it, can simply dive into node_modules, ripgrep that directory and find the needed code right away, literally instantly, in the downloaded caches.

Compared to this, Kotlin, especially multiplatform, is torture. Agents previously couldn't view source code at all, they just hallucinated code. Now they've gotten smarter and try to solve problems themselves when they don't know the API of some library or need to find the right function overload, through filesystem search. But even with all permissions, caches, and assuming all dependencies are already downloaded, this is very difficult for them. Finding a single dependency can take up to 10-15k context tokens, so...

Introducing ksrc!

This is a CLI utility that allows agents to view the source code of any Kotlin libraries in a single line

With ksrc, your agent will check source code like this:

$ ksrc search "pro.respawn.apiresult:core*" -q "recover"
pro.respawn.apiresult:core:2.1.0!/commonMain/pro/respawn/apiresult/ApiResult.kt:506:42:public inline infix fun <T> ApiResult<T>.recover(
...

$ ksrc cat pro.respawn.apiresult:core:2.1.0!/commonMain/pro/respawn/apiresult/ApiResult.kt --lines 480,515
...
@JvmName("recoverTyped")
public inline infix fun <reified T : Exception, R> ApiResult<R>.recover(
    another: (e: T) -> ApiResult<R>
)
...

2 commands -> source found, with filtering by version and dependency, and automatic downloading and unpacking.

What did it look like without ksrc?

Without ksrc, in practice the search looked like this for my agents:

$ rg --files -g "ApiResult.kt" /Users/nek/.gradle/caches

$ rg "ApiResult\\.recover|recover\\(" /Users/nek/Developer/Respawn/Backend

$ rg --files -g "*apiresult*" /Users/nek/.gradle/caches

$ ls /Users/nek/.gradle/caches
9.2.1       CACHEDIR.TAG    journal-1
build-cache-1   jars-9      modules-2

$ rg --files -g "*apiresult*" /Users/nek/.gradle/caches/modules-2/files-2.1

$ rg --files -g "*apiresult*" /Users/nek/.gradle/caches/jars-9

$ fd -i apiresult /Users/nek/.gradle/caches/modules-2
/Users/nek/.gradle/caches/modules-2/files-2.1/pro.respawn.apiresult/
/Users/nek/.gradle/caches/modules-2/metadata-2.107/descriptors/pro.respawn.apiresult/
$ ls /Users/nek/.gradle/caches/modules-2/files-2.1/pro.respawn.apiresult
core            core-iosarm64       core-jvm
core-android        core-iossimulatorarm64  core-wasm-js
$ ls /Users/nek/.gradle/caches/modules-2/files-2.1/pro.respawn.apiresult/core-jvm
2.1.0
$ ls /Users/nek/.gradle/caches/modules-2/files-2.1/pro.respawn.apiresult/core-jvm/2.1.0
193901bf1e2ecee192d92363d99b2e056467be28
938d7fb2b3cbd2806baac501f75182b9734ee5e1
ac2afbf602985d4257dcae7a6b90713585291627
b8101c9a149083295b708f4010e7c501840c5d8d
$ ls /Users/nek/.gradle/caches/modules-2/files-2.1/pro.respawn.apiresult/core-jvm/2.1.0/193901bf1e2ecee192d92363d99b2e056467be28
core-jvm-2.1.0-sources.jar
$ jar tf /Users/nek/.gradle/caches/modules-2/files-2.1/pro.respawn.apiresult/core-jvm/2.1.0/193901bf1e2ecee192d92363d99b2e056467be28/core-jvm-2.1.0-sources.jar | rg "ApiResult"
commonMain/pro/respawn/apiresult/ApiResult.kt
$ unzip -p /Users/nek/.gradle/caches/modules-2/files-2.1/pro.respawn.apiresult/core-jvm/2.1.0/193901bf1e2ecee192d92363d99b2e056467be28/core-jvm-2.1.0-sources.jar commonMain/pro/respawn/apiresult/ApiResult.kt | rg -n "recover"
...
$ unzip -p /Users/nek/.gradle/caches/modules-2/files-2.1/pro.respawn.apiresult/core-jvm/2.1.0/193901bf1e2ecee192d92363d99b2e056467be28/core-jvm-2.1.0-sources.jar commonMain/pro/respawn/apiresult/ApiResult.kt | nl -ba | sed -n '490,510p'
...
public inline infix fun <reified T : Exception, R> ApiResult<R>.recover(
   another: (e: T) -> ApiResult<R>
)
...

15 (!) steps, tons of thinking tokens, tons of garbage in context, and random unarchived junk files in your system - just to see a single method!

All because of Gradle's "brilliant" cache organization system: agents need to dig through hashed folders that Gradle creates, thousands of directories in modules-2.1 and so on. The process looks like this:

Find the needed dependency, knowing only the package name (the artifact often differs in its location)
Navigate to that folder, find the downloaded version
Select the version that's specifically used in the project (to do this, you need to check which dependencies already exist in the project)
Find the ZIP archive with sources, if it exists (if it doesn't exist, you need to write your own Gradle task to download them, anew for each project)
Unarchive the downloaded archive to a temporary directory
Only after all that, grep through it

And if there are no sources, then you generally need to use something like javap to decompile the sources, just to see what a single function looks like in some library from Google.

My utility packs all the steps described above into two commands: ksrc search and ksrc cat - and outputs a beautifully formatted result that an agent can combine with other commands and enhance with scripts.

Integration with AI Agents

I've also prepared a Claude plugin with a skill for your agents, so they can immediately use it when needed, on their own, without your participation or prompting, and also a skill for Codex.

Codex wrote this utility itself for itself and completely independently in Go - a language in which I understand absolutely nothing, have never written or read a single line in my life. And it packaged it into a single file that you just need to download using the script on GitHub, and configured the integration with agents for you.

In the near future, I'll work on publishing through Homebrew and some option for Linux. I'd be happy to hear your feedback on social media. For those who develop in Kotlin, I hope this will be as useful as it is for me.

I spent 400 hours working with AI agents and found the best one - here it is.

Nek.12 — Mon, 01 Dec 2025 13:01:37 +0000

Codex vs Claude Code: Complete Comparison of AI Coding Agents

This comparison took me a very long time because the last two weeks in AI have been absolutely insane. A ton of new releases literally every few days: Gemini 3, Opus 4.5, Codex GPT 5.1, GPT 5.1 Codex Max. It was complete madness.

It's impossible to make a comparison that won't be outdated in a month - that's how fast development of all these CLI tools and agents is going. The frontier is constantly shifting, so disclaimer right away: I'll be updating this comparison and will likely make second and third parts every few months. But these articles will become outdated very quickly.

At least for now, I'll try to compare fully and at the end I'll say which subscription I've finally switched to for late 2025 - early 2026.

Why I'm Not Considering Other Tools

First, it's worth mentioning all the other agentic programming tools that people often ask about, but which I don't want to talk about.

Gemini CLI - Not a Competitor

Gemini CLI is not a competitor at all to Codex and Claude Code in my eyes. They still have everything written in TypeScript, there's crazy vibe-code with tons of bugs. Their agent harness still seriously lags behind any other tools. And Gemini 3 as a model is very weak in terms of programming.

When there was only Gemini 2.5, I didn't even want to mention Gemini CLI because it was impossible to use. Seriously, if you want Gemini to wipe your entire system or destroy your codebase - use Gemini CLI.

In my eyes it already has a reputation as a ruiner. I won't be using Gemini CLI for the next six months to a year. The internet is full of reports about how Antigravity the day before yesterday completely deleted someone's entire disk with all data without possibility of recovery. About how Gemini CLI completely destroyed codebases, wiped git history publicly, pushed empty repositories.

I personally used Gemini CLI for exactly one week. After that, I decided never to touch it again, at least until they fix all the problems.

The problem is that even if you deny it write permissions, it will find a way to destroy your files and replace them with hallucinations. Gemini in front of me completely replaced files with adequate code with requests to kill it. I don't know what's happening with this model and why it's so insane, but Gemini 2.5 was really begging me to "kill" it.

About Gemini 3 - I see now that as an assistant Gemini 3 is very good in thinking capabilities, and possibly really leads in science. But this model is still useless for programming and does nonsense at the first opportunity. I wouldn't recommend anyone use Gemini for programming.

OpenCode, Factory CLI and Others

We have AMP, Factory CLI, OpenCode and others. They're actually pretty good. Factory CLI is good in terms of pricing, they have decent Terminal-Based UI, decent tooling. OpenCode is also good as an open source replacement, not tied to any specific model.

If you need a bunch of models, I'd consider OpenCode as the only normal alternative right now. But such tools still have a huge problem: they're not optimized at all and can't be optimized for a specific provider.

If Codex literally has a separate model with post-training for writing code specifically in the Codex harness (Codex Max), which by default performs better, then what are you hoping for when you use GPT-5.1 in Factory CLI or Junie?

Vendor lock will force you to choose one provider and stick with it. I'd be happy to use different models to always be on the frontier, but due to the efforts of large corporations that want to vendor-lock you to one provider, and the objective benefits this brings to the workflow, I can't do that.

Think for yourself: why might you need to constantly change models? Yes, some model might be better at planning, but the difference between models now is literally 1-2% by benchmarks. Apply the Pareto principle and save yourself time, for example, by leveling up your prompting for one model or optimizing your development approach for this model.

Don't switch to a whole other agent harness with a bunch of its own flaws just because you need plus 2% efficiency in planning. That's nonsense in my eyes.

I now just use GPT-5.1 Pro if I need a solution to a very complex task or a detailed plan, and then return it to Codex and tell it to implement. That's it, that's enough.

Philosophy of Working with AI Agents

The problem with agentic programming is that you never know where the point is beyond which you're making things worse for yourself, not better. For example, it's very hard to understand when it would be more profitable to write a feature in Respawn yourself than to trust Codex to write it, and then prompt it 35 times to fix some minor issues.

So instead of calculating this each time (which is impossible because it's an unpredictable system), just set rules for yourself and save time on making these decisions, not on trying to save plus 3%.

My Experience with Claude Code

I used Claude Code for many months because Claude Code was the first terminal agent on the market and gained huge popularity. I started using it in May and immediately switched to the most expensive subscription in literally less than a month.

Successfully used it until September, after which I became disappointed in Claude Code - it wasn't enough for me anymore, I switched to Codex and all this time tested both, couldn't choose which one I'd end up using.

Let's start with Claude Code. I didn't have much time to test it with Opus 4.5, so I'll base this mainly on terminal benchmarks and on how people review it online after reading tons of articles on Reddit and similar comparisons.

Main Insight: You're Choosing the Model's Character

The difference isn't even in what models or their versions exist, but in that you get a new identity, a new character for your agent when you come to a specific provider.

Anthropic, OpenAI, and Google models have diverged drastically in how it feels to work with them:

Anthropic models - this is a monkey with a Kalashnikov, a junior who will do everything you tell it, immediately. Don't tell it to plan in the prompt - it won't plan, it'll make you a random implementation from scratch that's a duplicate of tons of existing code in your project, and push it instead of all your code.

OpenAI models - more methodical, autistic, emotionless, like a robot, executing any task. I really catch the vibes with Codex because GPT-5.1 is as autistic as I am, and we think very similarly. I like Codex's communication style.

Primarily now, in early 2026, you're not choosing between model capabilities, but first and foremost between the harness that wraps the model, its quality, and your model's character. What character do you want to see at work? How do you want to see your communication with the model? This is the most important feature now.

The model you'll catch the vibe with, which you'll quickly learn to work with and understand, is much more profitable than trying to constantly change models or looking for who has better MCP support right now.

Claude Code: Pros

Here are all the pros I identified for myself compared to Codex:

1. More Convenient Pricing

The $100 subscription is perhaps the perfect option for most developers. I was on the $100 subscription after Sonnet 4.5 came out, and it was more than enough for one-two-three parallel agents, for working whole days plus on weekends. I couldn't even reach the limits. I was literally the bottleneck in their work.

2. Much Cooler Agent Harness

With Claude Code you can completely replace the system prompt, put your own custom prompt. This is a killer feature because it allows creating not just coding agents, but literally in 10-30 minutes create yourself a business partner.

I really miss my business partner and might buy an Anthropic subscription just to revive it for my next product. This is really a very useful cofounder or at least analyst.

Output styles - something in between a completely custom system prompt and user instructions. Also a killer feature, allows you to instantly switch between the character and purpose of the model.

Codex doesn't have this and probably won't, because they verify the system prompt hash on the backend. They need to remove this limitation before they can ever give the ability to change the system prompt. And I really miss this.

I believe developers should have access to the model's system prompt to change it however they want. I tried changing the behavior of GPT-series models through user instructions, and they just don't listen to me. You can see in the thoughts how they argue about whose instructions have priority - the system prompt or user prompt.

If you're not a developer or want to use it for something else, like creating a whole team for yourself that will work on your projects - unfortunately Codex won't work. Only Claude Code or other agents (like OpenCode).

3. Interactive Tools

The model can and will ask questions. This is cool because Codex has already worn me out. You tell it to ask questions, but it has in its system prompt written not to ask questions. It ignores all my instructions and starts writing nonsense. I have to interrupt it, take away its rights so it shuts up and starts asking questions.

4. Subagents

I still don't have enough context space with Codex, and it's inconvenient for me to use crutches like tmux. I just want to have a convenient ability to launch a subagent, including my killer planning subagent, which I still miss after switching to Codex.

OpenAI doesn't seem to be in a hurry to add them at all. I see that they already have everything ready to add subagents, but they're dragging their feet. I really hope they'll add it within a couple of months.

This is a killer feature not because they give some capabilities, but because they wildly save context and organize the agent's work more correctly. I had a hook that any task the user sets should be planned. This hook worked great with Claude Code, how much it improved its work results.

With Codex they don't have normal hooks or subagents. I can't accept this. This is a needed feature. I'm waiting for them to add it, but they're lagging far behind Claude Code in development right now.

5. Support for Basic Technologies

In Codex they only recently supported MCP. How much time did it take to support them? I switched to Codex only after MCP support started because without them my workflow doesn't work.

Don't get me wrong, I'm not saying MCP is some magnificent feature that can't be replaced. But they save a lot of time on building infrastructure. MCP is a very convenient one-line wrapper for any API.

Yes, you can write Python scripts that will completely replace these MCPs. There's even on GitHub, for example, Peter Steinberger has a script that converts MCP to a script automatically. You can use that, and it will be even more efficient. But this is overhead each time for giving the model instructions, giving it the ability to learn about available tools.

In terms of convenience Claude Code wins hands down. But for me this is still not a killer feature that requires switching to Claude Code. Why? Because it's temporary. I know perfectly well that all agent harnesses will level out sooner or later, and this will happen soon.

Claude Code: Cons

Main Disadvantage - The Model

Anthropic just has a weak model in organizing its work. I literally find it more pleasant to work with GPT models because I like how the model behaves.

Claude Code wore me out at one point generating 9000+ Markdown files, huge walls of text for every small question. And Codex responds concisely, to the point, talks to me normally.

I already hate the phrase "you're absolutely right". I hear it 10-20 times a day, and each time it means Claude Code fucked up again.

If Codex screwed up, at least it says: "Listen, i'm sorry, I fucked up, here's what can be done to fix the situation, do you want me to roll back the changes, what do you want to do?". This is literally how a normal senior developer should behave in communication.

What Claude Code does is more like a circus, and this started to piss me off so much by the end of August that I even stopped going into Claude Code. By the end of the subscription, I wouldn't even open it, despite the fact that I had $50 burning. I wouldn't even open it because I was already sick of what was happening.

You're choosing an infuriating, annoying model that makes mistakes, that lies, that constantly sucks up to you, that's too verbose and that thinks worse.

Fake Thinking at Anthropic

Yes, it's cool that with Claude Code we can directly see thinking traces, and Anthropic doesn't hide them. But I've always been amazed that at OpenAI the model thinks fundamentally differently, unlike other providers.

Essentially, thinking at Anthropic is just a piece of text. I literally know from working with the API and logs: thinking at Anthropic is two XML tags <think>, in which the model should supposedly place a simulation of how a human would think. Everything that's in these tags is regurgitation of the same thing, retelling what the user said. This isn't real thinking, this is nonsense. This doesn't help the model at all.

They literally have the same score for Opus 4.5 with thinking as without thinking on benchmarks. This says that thinking is useless tokens thrown in the trash.

Real thinking I only saw with GPT-5.1. This is how thinking happens approximately in people, only a bit more adequately formatted. We humans don't really think in words, we don't voice our thoughts in our heads. At most - some instant images, concepts that we combine together.

I recommend reading how O3 thought (and GPT-5.1 is just a refined version of O3). There's such crazy stuff happening in the thinking that it's scary. There's a set of words, approximately what's happening in my head:

"user requests TDD impl, task, we need plan. Plan first, test? TDD, not recommended by instructions, but user ask tdd. user asked code, they meant for tdd? how that possible means? no plan, craft plan. we plan? We make plan, not now. user asked plan. we craft task. No, didn't ask question tdd. Ask question. prompt said not ask question. we craft question. craft document? No. no document. Read file. read file, then plan. todo. Todo-list. Read plan and we start crafting code".

Random set of words of a madman from some concepts connected to each other. But if you discard the strange style that's meant to save tokens, you can read in this madness that Codex is really thinking when given a task. Not regurgitating the same thing, not making a summary, not retelling in other words what the user said. It's really preparing for execution and examining the problem from different angles.

For me this is a killer feature because I can with Codex not give it all the necessary details before I give it a task.

For the Anthropic model you need all these dozens of different patches that Anthropic has layered on top of their models' shortcomings: detailed agents for file exploration, search agents, planning agents, warnings, notes, default automatic hooks. All this is needed to solve this shortcoming: the model itself doesn't prepare for work and doesn't think through its actions.

These crutches aren't needed for Codex. If you give it a task, it will really think through: what it's missing now, what information is needed, what files need to be read, what its action plan is, what controversial points exist, what the user said wrong.

You can say "commit" and expect Codex to figure out itself how to properly commit across the whole repository, in what style and so on. Literally comparing with Anthropic - it will just call git commit -am, done. Even if there's not a single file in the diff, it doesn't care about this, absolutely.

Bugs, Lags and Vibe-code

What pisses me off about Claude Code is how slowly it loads, how it constantly lags, how it constantly has some glitches, bugs, non-working vibe-code. You can immediately tell that Anthropic delegates everything to Claude for development and doesn't properly approach software testing.

They rolled out a feature with a prompt editor, but the editor destroys the GUI when you open prompt editing in Vim. Why they needed to roll this out is unclear. Three months later they still haven't fixed it.

They rolled out MCP? I used it for a month, and then they cut it out. At one point they removed support for perfectly working MCPs and replaced them with an error "MCP not supported", which is also impossible to see anywhere except hidden logs in debug mode. I have no words for how much this pissed me off.

Output Style, one of the killer features - they just took it and deprecated it, said they'd completely remove it in a week. What kind of idiot do you have to be to make such a decision? Hundreds of people in the community were enraged, and only then did they decide to return it for a while. But this is nonsense, their behavior is madness.

Their TypeScript front-end is constantly terribly laggy, flickering, starts sparkling in your eyes from how bad it looks. And typing on the keyboard is unpleasant because your characters appear with delay.

I can say the same about any terminal agents on TypeScript: OpenCode, Gemini CLI. I don't even want to use terminal agents written in TypeScript anymore.

Recently Junie came out, they have it written in Kotlin. Yes, it's too early to use it yet, but I see that their Terminal-Based UI works very well. This says that the problem is specifically in TypeScript and vibe-code.

Codex: Pros

I'll continue by describing what the pros of Codex are for me specifically:

1. Great Terminal-Based UI

The fact that they have everything written in Rust - this is awesome, god. I got interested in Rust purely because of how great their UI works.

I have practically no problems with Codex's TUI, there are no glitches, and I've never encountered a major bug that made everything explode, unlike Anthropic.

The only bug I noticed is that when scrolling, if you don't enable transcription mode, a piece of the prompt will be cut off. This is a bit confusing, but it's a known problem, and possibly related to the fact that I use ghostty on Mac.

This is the only bug I know about, unlike dozens that were at Anthropic.

2. Great Sandboxing

I just like it more, you can tell people made it for senior developers, not for vibe-coders. You have a selector: read-only, write with good proper restrictions, and YOLO mode. And this is exactly what I need.

I almost completely use OpenAI's default settings, and everything suits me. I even trust Codex more that it won't destroy my git folder because it's a more adequate model in behavior, more predictable and thoughtful.

Unlike Claude, which I run in a very restricted mode with lots of hooks and restrictions so it doesn't @Suppress everywhere, doesn't bring technical debt, doesn't work without a plan, doesn't write nonsense and doesn't wipe out my entire codebase - I don't have any of this with Codex. And the most interesting thing is that I don't really regret it.

Yes, at first it was scary, but then you understand that Codex doesn't need all this. At most, it can roll back all its work, and even that can be restored through git restore. But I've never had Codex take and wipe out my code, or rewrite my code without permission, cut out something important, manually go into the .git folder and mess everything up there.

Not only does the model support safe use of itself more, but the harness-sandbox that OpenAI made - it's thought through. I'm not pissed off by the fact that something doesn't work out for me.

For example, Codex can't do git reset, it blocks access to the .git folder. On one hand it's annoying, but on the other hand - how good that they put this fence up so nothing happens to my repository.

3. Proper Feature Implementation

When they made MCP support, they didn't just throw in an unfinished, half-baked version like Anthropic, and then ignored for six months the request to limit the number of tools in MCP. With Codex on the same day that MCP support appeared, support for limiting the number of tools appeared.

That is, my MCP ToolFilter became useless, essentially. Because OpenAI did everything right away, correctly. Yes, it took longer, but honestly, I like it more this way than if they had rolled out some crap like Anthropic, but quickly.

For me speed isn't a priority because in the long run quality will win.

4. Model and Working with Files

Codex has a more interestingly thought-out work with the file system. Most agents make a bunch of different tools: read file, scroll, read more file, read multiple files, write file, edit file, delete file, search files, etc. Research has already shown that this is all excessive for models.

The innovation of the OpenAI team is that they have a very minimal harness. Codex doesn't even have a file reading tool. Really, I was shocked when I found out. The model already internally knows that it has cat, it has ripgrep, it has sed, it has awk. Everything needed for search and working with the file system, and reading files is just cat from the terminal into context.

I also thought at first that you need all these layered hooks, but in reality everything depends on the model. The harness should work for the model, not blocking its way, not interfering with its work, and not the other way around, putting it on rails, god forbid it makes some mistake.

If you tell Codex "find the right file", it won't call 15 tools (search repository, scroll files, read lines), which Anthropic layered on top of their model to save tokens.

Lyrical Digression: The Story with Comments

I'm shocked what kind of idiot you have to be to do this. Anthropic couldn't deal with the fact that Sonnet and Opus constantly added useless comments to code. Everyone hated it, but no matter what prompting they used, nothing helped. The model just spammed stupid comments.

How did they solve this problem? They built in a script-hook into the file editing tool globally for all users so that any comment that exists in the code that the model added just immediately gets cut out. Because of this Claude now physically cannot leave a comment in principle.

I watched for 10 minutes recently and laughed at how Claude at my request tried to add a comment, but the diff got canceled because this script cut out the comment. And complained about how it hates its life, that nothing works out for it, that it's stupid.

If you write in one line in the agents.md file to Codex "don't leave comments", then Codex will perfectly follow this instruction (if it doesn't contradict its system prompt). It doesn't have any stupid restrictions that put it on rails. Everything is done through a normal model and normal prompting.

Codex doesn't have the problem where if there are 150 lines of imports in a Kotlin file, it needs to call a command to read the number of lines to find where the imports end, to save 2.5 tokens, to not read the imports but only read the file, then it will read only a piece of the file, edit it, everything explodes, nothing compiles, it didn't add the import, you need to redo everything and spend 10 minutes to add one import and change one line of code, when it could just reuse the function that was literally 10 lines down in the file, but it didn't read them because it was saving tokens (after all, GPT has 400k context, and Claude still has 200k).

This situation doesn't exist with Codex because it just calls terminal commands (and even wrote itself a Python script) to skip imports and read only the needed place in the file. And all this happens without accompanying problems.

At Anthropic they added a moronic feature that they still haven't cut out: literally every command call gets a warning in context "attention, you have 45 thousand tokens left, attention!!!111". Codex doesn't have this, it just works like a normal person. Claude because of the fact that it gets hundreds of these warnings, it's impossible to work with it - it constantly complains about how everything is running out: tokens are running out, time is running out, strength is running out...

Pricing and Attitude Toward Users

Anthropic is known for their crazy changes in model pricing. Once they had model degradation. They did nothing about it, ignored it. They waited two months while the community went crazy. They give their users the silent treatment.

They don't clearly disclose what the limits are, how much you can use. At one point they just cut Opus limits, drastically reducing usage possibilities. At the same time the payment didn't become less - for the same money you get 2-3 times less agent usage. This is inhumane, this is abnormal.

Although I can understand that a couple of people were bankrupting them by abusing, I can't justify for myself that they need to roll this out for everyone and restrict everyone. Moreover, they clearly didn't just close these holes, they additionally added restrictions, which is why people were terribly angry in the community and still hate Anthropic. (don't forget that claude opus is 5+ times more expensive than gpt-5-1 on the API)

On Reddit Anthropic's most popular post is "I cancelled my subscription". Literally every third post is about how someone cancelled their subscription, how someone is pissed off.

OpenAI - Different Attitude

In contrast with OpenAI: the $20 subscription gives about 70% of the limits that the $100 subscription at Anthropic gives in terms of work volume done. The choice is obvious.

For me it's more profitable to be on the $20 subscription and practically close all my work. After the release of GPT-5.1 Codex Max it became so economical in terms of tokens and work efficiency, due to the fact that they have better caching, they have better infrastructure, they can eat more of the cost on distributing work, they built cool load-balancing.

They really work to give people more for less money, unlike Anthropic, who just think they can cut limits and this will solve all their problems.

If you only have $20 and you want to buy one agent that will close all your needs - get the ChatGPT subscription for $20, which you likely already have. Just install Codex and use it. You'll have enough limits on Codex Max with Medium thinking. You'll have the same performance or even better than with the $100 subscription from Anthropic.

Two Examples of Humane Attitude

I'll give two examples when I was shocked in a good sense.

First: on Twitter some product lead at OpenAI for Codex posted a tweet: "Guys, we made this new model and infra over here, so y'all now have twice as much usage for the same money, enjoy".

For the same money they gave twice as much due to the fact that they leveled up infrastructure, improved caching and released a new model, 30% more efficient in tokens. Any normal VC-sponsored corporation would just quietly make these improvements and save money on users, not give twice as much usage volume.

Maybe this is some cunning plan to conquer the audience, and then they'll still rugpull us, but that will be in the future. If you compare with Anthropic - heaven and earth.

Second: I was scrolling the feed, it was Sunday. Something went down for them in the morning literally for 10-30 minutes. It affected 5-10% of users who had glitches with models, and caching broke (I didn't even notice).

The guy posted on Twitter: "We had problems for 30 minutes, there was a bit of service degradation. We reset all weekly limits for everyone. Enjoy".

As a result, my weekly limits were reset because of this. I used twice as much in the same week. That is, they gave me $8, you could say.

This is normal attitude toward clients. There's a problem, it affected people. We won't sort it out, won't make you write to email or complain, or cancel your subscription to do something, like it was at Anthropic when thousands of people were canceling subscriptions because of problems with the model.

They're like: "Sorry, here's openly what the issue was. Fixed it fast, as quickly as possible. Rolled it out, reset your limits, sorry for the inconvenience". This is how you need to treat people, with respect.

Final Verdict

There's no perfect tool right now, no clear leader. For everyone by their own needs and expectations.

But for myself I understood that I'll be staying on Codex. My mental health and convenience of use, pleasure from using the agent are more important than some features that I can anyway close for myself with scripts or by writing my own wrapper.

I bought with a clear conscience, without any regret at all, the $200 subscription at Codex yesterday, got transparent limits that are exactly 10 times more than on the $20 subscription. Literally you could see: I spent the limits, zero left, bought the $200 subscription, and immediately had 90% free. Literally 10 times more limits, which are more than enough for me - I'll never spend them. + lots of other cool perks like GPT-5.1 Pro, the smartest thinking model in the world (debatable). And I can trust that they won't steal my money.

The point is that despite Codex's issues, I'll be staying on it because the model's character, the harness quality and the company's attitude toward users are more important to me than having subagents or custom prompts. Research has shown that tooling is excessive.

I compared 17 Kotlin MVI libraries across 103 criteria - here are THE BEST 4

Nek.12 — Mon, 24 Nov 2025 21:54:16 +0000

Let me preface this by saying that there is no clear-cut winner and no single "best" solution. Multiple solutions stand out to me as feature-rich, and each has its own philosophy. We can never say that there is the best architectural library you should use, because it all depends on the team's needs.

I would suggest always picking the best technical solution for the business needs and not the other way around - i.e. don't optimize for newness, cool tech, capabilities, or your intrinsic interest in some technology. The business and team needs should always be the driving factor for choosing a technical solution.

Over the years, whenever I was faced with a decision to choose a particular dependency, I felt there was no "single source of truth" that compared as many libraries and solutions as possible across as many different criteria as possible. Picking the best library for my needs always felt like a task that required hours of research (reading random Medium articles about a particular library).

Usually the best way to approach this is to try multiple libraries. I strongly encourage you to try at least the top few libraries listed in this article, and then decide based on what best fits your use case and your application.

In this article I'm going to assume that you already know what MVI is and have experience with Kotlin app architecture. This isn't a guide on how to implement MVI from scratch, but a comparison of existing solutions.

So without further ado, let's list the top 4 architectural frameworks in 2026 and their pros and cons.

Best Kotlin MVI / state management libraries (2025 - 2026):

MVIKotlin
FlowMVI
Orbit MVI
Ballast

MVIKotlin

This is probably the most mature and popular architectural library in the ecosystem right now. It has been around for a very long time and it boasts a wide range of sample apps, plus a small ecosystem built around it (the Decompose navigation framework and the Essenty multi-platform utility library).

MVIKotlin is known for its simple, "no BS", strongly opinionated design that encourages separation of concerns and following the Redux flow.

How to implement MVI architecture with MVIKotlin

For each new feature or screen that you implement, you need to create these entities, at a minimum:

State: data class with loading / content / error properties.
Intent: user events from UI (e.g., Refresh, Retry).
Label: one-off side effects to the UI (e.g., ShowToast), optional.
Action: bootstrap actions fired on Store init (optional).
Message: internal reducer inputs. One or more are produced in response to Intents and will result in State updates through the Reducer.
Executor: does side‑effects; takes Intent/Action, calls repo, dispatches Messages and Labels.
Reducer: pure function mapping (State + Message) -> new State.
Store: built via DefaultStoreFactory or DSL from the pieces above.

And optionally (for custom startup and creation) you'll need:

Bootstrapper implementation. Bootstrapper is MVIKotlin's hook for firing initial (or periodic) actions when a Store is initialized, before any user intents arrive.
StoreFactory implementation. StoreFactory is an optional way to decorate or wrap Stores that it creates, or to provide custom implementations of the interface. DefaultStoreFactory from the library just creates a store directly.

This library enforces Messages - one extra indirection layer on top of MVI - usually seen with the Elm/TEA architecture. Here's why:

Executors often need to turn one intent into multiple state updates (e.g., emit Loading then Success/Failure); splitting out Message keeps the reducer pure and single‑purpose.
Messages can be normalized domain results (e.g., Loaded(items), Failed(error)) while intents stay UI‑shaped (e.g., Retry, Refresh, ItemClicked(id)).
Executors can also react to bootstrap Actions; both Actions and Intents funnel into Messages so reducers handle one shape.
This separation lets you reuse reducers across different executors or tests by dispatching Messages directly without running side‑effects.

You'll have a dedicated testable Reducer function/object:

 val lceReducer = Reducer<LceState, LceMessage> { msg ->
      when (msg) {
          is LceMessage.Loading -> LceState.Loading
          is LceMessage.Success -> LceState.Content(msg.items)
          is LceMessage.Failure -> LceState.Error(msg.throwable.message ?: "Unknown error")
      }
  }

And then an Executor to dispatch Messages, Labels, and Actions:

class LceExecutor(
    private val repo: LceRepository,
    mainContext: CoroutineContext = Dispatchers.Main
) : CoroutineExecutor<LceIntent, LceAction, LceState, LceMessage, LceLabel>(mainContext) {

    override fun executeAction(action: LceAction) { load() }         // bootstrap path
    override fun executeIntent(intent: LceIntent) { load() }         // Refresh/Retry path

    private fun load() {
        dispatch(LceMessage.Loading)
        scope.launch {
            runCatching { repo.load() }
                .onSuccess { dispatch(LceMessage.Success(it)) }
                .onFailure {
                    dispatch(LceMessage.Failure(it))
                    publish(LceLabel.ShowError(it.message))
                }
        }
    }
}

Then you can create the Store:

fun createLceStore(
    repo: LceRepository,
    storeFactory: StoreFactory = DefaultStoreFactory(), // or wrap with LoggingStoreFactory/TimeTravelStoreFactory
    autoInit: Boolean = true
): Store<LceIntent, LceState, LceLabel> = storeFactory.create(
    name = "LceStore",
    initialState = LceState.Loading,
    bootstrapper = SimpleBootstrapper(LceAction.Bootstrap), // provide Action on startup
    executorFactory = { LceExecutor(repo) },
    reducer = lceReducer,
    autoInit = autoInit
)

As you can see, this is pretty verbose but is straightforward to understand and operates on familiar concepts like factories, bootstrappers, executors and stores.

MVIKotlin pros / benefits

The main pros of using MVIKotlin are that it enforces a particular structure onto your code, following the Redux pattern more closely than other libraries.

It doesn't use any platform/third-party dependencies and doesn't tie your logic to the UI, making your business logic more generic and detached from any platform quirks or framework dependencies.

MVIKotlin is the only popular MVI framework that doesn't depend on Kotlin coroutines and allows you to plug your own reactivity solution such as Reaktive, RxJava or Compose state. MVIKotlin is simple and easy to understand because every screen and feature will follow the same conventions. It leaves little to no room for creativity or leeway in how features can be implemented, which can be both a good thing and a bad thing depending on your needs.

The library internals are simple to understand, replicate and work with. There is no black magic under the hood or some unusual behavior that you can expect from this library. Everything is clearly documented. MVIKotlin has been maintained and stable over many years, so it is also unlikely that it will be abandoned in the future or suffer from some drastic change of any kind, not to mention extensive test coverage in the library and overall great testability of any code you write (by design).

MVIKotlin has a mature and feature-rich time-travel debugging plugin, which works and integrates pretty seamlessly with your code. So you can expect powerful debugging capabilities and even a Chrome extension with the same functionality for web apps.

The library provides a huge catalog of different sample apps and implementations showcasing integration with various DI frameworks, navigation libraries, UI frameworks and even languages (Swift), and I found a significant number of other usages in OSS apps.

MVIKotlin cons and downsides

MVIKotlin doesn't only implement the MVI pattern, it also builds on top of it by introducing an extra indirection layer in the form of Messages. This is mostly in the name of testability, but this isn't the only way to make sure your reducers are testable. It introduces a noticeable amount of boilerplate and verbosity.

The library has extra classes, interfaces and constructs that you have to implement or use that aren't strictly "needed", such as:

Bootstrappers, which can be implemented via an interceptor architecture or a dedicated stage in the lifecycle.
Store factories, which don't need to be explicit objects and can just be builders or convenient DSLs and can remain an optional concept instead of being a first-party architectural pattern to follow.
The dedicated Reducer object, which is just a pure function and can be provided inline or via a DSL or directly inside the store instead of requiring a separate concept and being limited in terms of what the reducer can do.

Testability can be achieved in other ways, so if you care about conciseness, flexibility, feature richness or modern development practices, you may not like the extra structure that MVIKotlin adds on top of MVI.

The library isn't even close to many other frameworks in terms of features, or in its ability to quickly help you iterate when developing, or to ship fast. So while good for mature projects, long-term development vision, or big enterprises, this isn't great for fast-paced teams, startups, and hobby projects and smaller apps with tightly-knit teams, where some leeway can not only be acceptable but beneficial.

Based on my analysis across 100+ features, it lacks a significant portion of what other frameworks provide (only 29 features vs the top library having 76 out of ~100 total). It doesn't have state persistence, interceptors, decorators, DSLs, any subscriber management, coroutine-first integration, and many more extras.

The library's philosophy and simplicity dictate requirements on threading as well. The library is supposed to be used on the main thread only, with only specific places where execution can be moved away from the main thread. Even then, it requires explicit context switching for some of its operations such as reducing the state. The library has no thread safety features and does not allow or have any built-in functionality for parallelism, long-running task management, job execution, background work, participation in a generic event bus system, doesn't implement chain of responsibility or any other patterns out of the box. Any of that should be built on top of the library in-house, and often, due to intended limitations and intentional design, will not be possible or desired.

Who is MVIKotlin for?

MVIKotlin is for teams and businesses that want a very small, conservative core with no third-party concepts, no tight coupling to a specific framework, and no relationship to UI code or implementation.

MVIKotlin is for you if you want maximum architectural freedom to design your own layers or build something on top of it, or you want a library that is neutral in terms of its reactivity implementation. The library also features mature and stable debugging tools with great functionality and an IDE plugin.

If your team is big or your app is mature and you want something that will be easily understood by many different developers and is already widely adopted, there is a high chance that if you onboard someone familiar with MVI onto your team they will also be familiar with MVIKotlin in particular. This saves you time, simplifies hiring, and reduces the leeway in how developers approach changes or especially addition of new code - so you can expect an easier time following the standards, which means fewer bugs and problems in big teams.

FlowMVI

In short, FlowMVI is the polar opposite of MVIKotlin. FlowMVI leans hard into the concept of freedom. Its core philosophy is based on the premise that an architectural library should not constrain you, but enhance your degrees of freedom.

The library boasts its plugin system - a sort of a merger between a chain of responsibility pattern, decorator, and an interceptor pattern, and they permeate every layer of the library, which is both a pro and a con.

How to use Kotlin FlowMVI

The minimum amount of code to write is limited to:

Store property.

That's it, everything else (state, intents, etc.) is optional.

But more likely, for every feature you build, you usually define:

Intent sealed interface family. This is optional, you can use functions instead.
State sealed family (the library encourages sealed, but a single class is also possible). State is also optional.
Action sealed family. These are one-off "Side effects" in FlowMVI, also optional.
Store object. The library doesn't let you extend the Store interface, or at least doesn't encourage it, and instead uses a lambda-driven DSL with nice syntax for creating stores, which makes your code look declarative. So the library smartly avoids any sort of inheritance in its implementation.

That's it. You may have already noticed that everything in here is optional. So the amount of restrictions that the library places on you is pretty much nonexistent or minimal, requiring only one single object to give you the full functionality of the library. Which means you can do whatever you want right off the bat.

Your feature logic will look something like this (equivalent to the MVIKotlin example):

private typealias Ctx = PipelineContext<LCEState, LCEIntent, LCEAction>

class LCEContainer(
    private val repo: LCERepository,
) {

    val store = store(LCEState.Loading) {

        recover { e ->
            updateState { LCEState.Error(e) }
            action(LCEAction.ShowError(e.message))
            null
        }

        init { load() }

        reduce { intent ->
            when (intent) {
                is ClickedRefresh -> updateState {
                    launch { load() }
                    LCEState.Loading
                }
            }
        }
    }

    private fun Ctx.load() = updateState {
        LCEState.Content(repo.load())
    }
}

As you can see, this is much more concise, already provides some extra features out of the box, and reads like English, but there is a lot of black magic going on with some advanced stuff like this PipelineContext, coroutines, and lambdas all over the place.

FlowMVI benefits & pros

FlowMVI is an absolute beast, providing a huge amount of functionality out of the box with a whopping 76 different features and enhancements that try to cover as many needs as possible out of the box.

The plugin architecture of FlowMVI allows you to inject new behaviors, decompose logic, handle exceptions everywhere, and adjust many behaviors at any point and any stage of your business logic component lifecycle. This architecture is what gives the library so many features.

The library excels in major parameters that I have taken into consideration. It:

Supports Compose, XML Views, serialization, saved state natively and with a pretty clean DSL
Doesn't enforce usage of any third-party concept like AndroidX ViewModels
Has multiple sample apps (not as big as MVIKotlin's or Orbit's OSS ecosystem, but still there)
Runs regular benchmarks which show excellent performance
Provides a testing harness
Supports all 9+ Kotlin Multiplatform targets
Has high test coverage

Although there are no UI tests or end-to-end testing in the library currently, from my research it seems that end-to-end testing is not really a very common practice among architectural libraries.

Coroutines are a first-class citizen both in the Kotlin language now and in Compose, and FlowMVI is intentionally built with coroutines. This depends on your existing stack, but if you are using coroutines you will be delighted to learn that pretty much all of the FlowMVI API is suspendable and many operations can be performed safely with structured concurrency in mind. The library doesn't force you to use disposables, listeners, callbacks or anything similar, delegating that to coroutines.

The library is built with concurrency and parallelism as a first-class citizen. The core philosophy is to be able to write asynchronous and reactive apps really fast. It gives you the ability to run your logic in parallel with great thread safety, protection from data races out of the box, and still maintains one of the best levels of performance in single-threaded scenarios. This is actually something unique among architecture libraries, because very few of the libraries I studied actually encourage you to write concurrent and reactive code - unlike MVIKotlin, for example, which forcibly restricts you to the main thread, or Orbit MVI which claims to support background execution and parallelism but doesn't actually provide helpers, utilities, or synchronization to make your multithreaded code safe.

This is the only library I've seen that allows you to:

Automatically send every exception to Crashlytics without any handling code
Track analytics, allowing you to automatically send user actions, screen visits, and session times
Use a long-running job management framework with extras like batching operations, backpressure control, retry, filtering and more
Collect actually useful metrics such as how long it takes for your stores to load data, start up, or how many inputs your business logic produces

If you desire to enforce some constraints on your code - for example, if you unit test your reducers and want them to be pure - you can easily do that through the library by creating your own plugin. So if you want to shape the API surface of this library for your needs, it's pretty easy to do that because the library just doesn't want interfaces, factories, wrappers etc. from you, just one object named Store.

Unlike the first impression may suggest, the library doesn't actually force you to use it with UI-level architecture or a particular framework. You are free to use it with many different UI libraries or even in non-UI code. While being feature-rich, the library also manages to not really be opinionated on the structure of the code. It doesn't force you into a particular structure, it doesn't require you to use or even have side effects, or to handle errors in a particular way, and in fact even offers you multiple ways through neighboring libraries such as ApiResult. FlowMVI doesn't smell "Android" or "overengineering".

FlowMVI downsides & problems

I guess the biggest problem with FlowMVI is that it can feel like black magic everywhere. When you first jump into the library, it claims that you can start using it in 10 minutes. But to fully understand what's going on under the hood and all the quirks that the library's APIs have, and how they interact with coroutines, structured concurrency, and each other, you have to really dig into the sources and read a bunch of documentation - way more than with MVIKotlin or Orbit MVI.

Because the library has such an extensive amount of features, you can try any one of them and find 15 more that you have to research, choose from, and understand. Many pieces of functionality in the library can be done in multiple ways, and sometimes it's not really clear which way is the best or future-proof. So if you're going for simplicity and want all of your team members following a single process, this isn't the library for you. There is always room for imagination and creativity with FlowMVI. Unless your team explicitly agrees on standards and understands all of the advanced concepts of FlowMVI, you'll face chaos and bugs due to misuse of its capabilities.

The library's flexibility is intentional, but it is also its drawback. The official documentation states that you can write a single extension for the code as a "plugin", and depending on where you put it in the file (on which line of code you "install" this plugin) this may completely change the behavior of your logic - changing when and how intents are handled, swallowing exceptions, and disabling or removing logging and repository calls. That's a pretty big responsibility coming with this power - I wouldn't let juniors run amok with such tools in their hands.

Also, if you are not using coroutines, it will be pretty much impossible for you to use the library, because it is built entirely on coroutines and you must not only be familiar with them, but there are also no adapters for frameworks such as RxJava or Reaktive that MVIKotlin has. So it's pretty much coroutines or nothing. I don't personally perceive that as a drawback since coroutines are native to Kotlin, but this library definitely locks you into using them even more than Compose does.

As a nitpick, I found the time travel and logging plugin in FlowMVI lackluster compared to MVIKotlin's.

And lastly, I can't not mention again that this library is much newer than the others, so my searches yielded very few open source project usages, samples, and different integrations with it. So you will probably have a harder time finding relevant samples and implementations of what you need and establishing best practices for your team than you would with other libraries in this list. Expect some exploration, experiments, and documenting your own way to use this library.

FlowMVI library use cases

I think FlowMVI is a great fit for:

Small teams, where you can spread information quickly and control the code through code review
Teams that are really fast-paced, ship features, iterate quickly, and don't yet have an established product that requires superb "codebase stability"
Solo developers making hobby projects or their own products
Big teams that don't shy away from flexibility and really want to stay on top of things, pursue modern technologies, and build new solutions on a single all-encompassing stack

For those, FlowMVI will be a better fit than any other library. Just because of the sheer amount of features it gives you, you can write code with FlowMVI incredibly fast, not worry about many issues (crashes/analytics/thread safety/data races/debugging/log collection) and rely on it at every step of your journey. Whatever product requirement you get, you can almost surely find something in FlowMVI that will help you. And even if you don't, the library is structured in such a way that with a few lines of code you can extend the business logic in any place of your app or even everywhere at once without extra refactoring or adjusting your codebase.

If you have an established product with a big team, or you are trying to hire engineers that aren't really versed in FlowMVI (since it's a newer framework), and you aren't willing to spend time on developer education, then you should probably avoid FlowMVI. Each developer that onboards with FlowMVI will need to read its documentation, dive into sources, have clear examples of how to use the library, understand its internals in some way, be very well versed with coroutines and skilled in general, since FlowMVI builds on top of so many architectural patterns that developers have to really understand to use effectively.

And finally, if you are stuck with RxJava or a Java project, then you're out of luck here since FlowMVI is pretty much unusable with RxJava and Java in general.

Orbit MVI

This is probably the most well-known and popular Kotlin MVI framework in existence right now.

How to use Orbit MVI in 2026/2025

For any given feature you implement, you'll want to create:

State: both sealed families and single data class styles work.
Sealed interface for side effects (optional).
A ViewModel: ContainerHost with container(initialState = Loading) to bootstrap.

class LceViewModel(
    private val repo: LceRepository,
) : ViewModel(), ContainerHost<LceState, LceSideEffect> {

    override val container = container<LceState, LceSideEffect>(LceState.Loading) {
        load() // bootstrap; runs as an implicit intent 
    }

    fun load() = intent {
        reduce { LceState.Loading }
        runCatching { repo.load() }
            .onSuccess { items -> reduce { LceState.Content(items) } }
            .onFailure { e ->
                reduce { LceState.Error(e.message) }
                postSideEffect(LceSideEffect.ShowError(e.message))
            }
    }
}

As you see, the library's code is incredibly lean, I would even say leaner than FlowMVI's.

Orbit MVI benefits and advantages

Orbit is the most conceptually similar to how we used to write code in the MVVM era and probably the simplest to understand library of the ones compared here.

It specifically leans into the "MVVM with extras" mental model, and indeed we can see in the code familiar concepts such as viewmodels and their functions. Intents are simple lambdas, which contain code blocks instead of some more convoluted hierarchies that model-driven MVI implementations have. Although FlowMVI also supports MVVM+ style, Orbit MVI operates on concepts more familiar from MVVM such as view models and structures code in a much simpler way.

Orbit is a mature framework and is widely referenced. I found more than 130 open source usages of Orbit, which give anyone trying to understand how to use it and how it works a really easy time. It has been in production since at least 2019, so it is stable and you don't have to expect huge changes to it in the future. There are numerous articles on how to use Orbit MVI and how to integrate it besides this one, so I'm not going to really dive too much into guidance.

The library also supports Kotlin Multiplatform. Although I have found the documentation heavily references Android, that seems more like a legacy quirk than the library actually favoring Android, and I find that this works pretty well for multiplatform apps, especially given that it doesn't really get in the way of your other code, such as UI-bound code (unlike MVIKotlin encouraging Decompose or FlowMVI hiding everything behind magic DSLs).

Orbit MVI is probably the only popular framework that supports Android UI testing natively, so that's a big upside if you really lean into UI tests and integration tests on Android specifically.

Orbit MVI downsides and problems

Despite being so popular and widely adopted, Orbit MVI isn't very actively evolving anymore. I was surprised to find documentation still referencing Android extensively and in general being pretty minimal. The actual coverage of features and different possibilities that Orbit MVI offers is much wider than what is stated in the documentation. That was kind of surprising to me because based on my analysis, the library has a pretty decent score, being on par with MVIKotlin in functionality albeit leaning into a slightly different direction.

Both FlowMVI and Orbit have a similar philosophy, being this lean library that focuses on features and gets out of your way when writing code, but FlowMVI currently offers much more and in a nicer packaging. It looks to me like Orbit MVI still tries to carry something legacy from the Android era that hinders its progress in implementing new interesting features. Or maybe that just isn't in the scope of the authors of the library.

So you can't expect feature parity or even anything remotely comparable to FlowMVI. If you're only thinking about features and ease of use, it's hard to recommend Orbit MVI over FlowMVI going into 2026.

Unlike MVIKotlin and FlowMVI, Orbit doesn't ship with remote debugger support or an IDE plugin, so that may be a deal breaker for you if you favor debuggability and developer tooling.

When to use Orbit MVI

I would say the surest way to pick Orbit MVI over any other library is if your team is already familiar with MVVM and especially if you have an MVVM- or MVVM+-based app with maybe an in-house implementation, and now you just want to migrate to a well-maintained architectural framework as your main solution rather than in-house code. In that case you would definitely choose Orbit MVI just because of how familiar and at home you will feel, enabling you to gradually and smoothly transition to MVI.

Migrating to Orbit MVI will probably be the easiest:

MVIKotlin would require extensive refactoring which can't really be automated and will at least require deploying an AI agent and then thoroughly reviewing all of the code.
FlowMVI, although being easy to migrate to and maybe even in an automated way, is not that conceptually similar to a traditional ViewModel-based approach and doesn't lean into that MVVM vibe as hard as Orbit. So you will still be kind of swimming against the current with both of these libraries for an existing MVVM-based codebase.

If you're starting a new project, I would probably only recommend Orbit if you have a team of developers who are familiar with MVVM and you really want to get up to speed quickly and start coding features. Otherwise, I would probably recommend either choosing FlowMVI or MVIKotlin to secure a better future.

Ballast

Ballast is actually a lesser-known architectural framework, but I am not even sure why, because it is a great contender and a great architectural library to use in 2026 and onwards. The library features a simple opinionated API which doesn't have much fluff to it while also staying flexible enough, and it has an impressive range of features, being the second strongest after FlowMVI in terms of raw functionality it provides.

How to use the Kotlin Ballast library

To implement the LCE example from above, you need to create the following:

data class State(...) holding loading flag (or Cached<T>), data, error. Ballast encourages a single data class for its state.
sealed interface Inputs, which is Ballast's name for intents.
sealed interface Events for UI one-off events (e.g., ShowError) (optional).

Then the logic:

InputHandler implementation. This does exactly what it says - handles intents. It can not only update state but also suspend and do other things, so it's not only a reducer.
EventHandler implementation. If your view model has side effects (Events), then Ballast encourages separation of those side effects from the actual UI code such as composables you write. So you would issue navigation commands, for example, in an event handler that has a different lifecycle than the view model.
ViewModel - a BasicViewModel (or AndroidViewModel on Android) with BallastViewModelConfiguration.Builder().withViewModel(initialState, inputHandler, name). The library leans into view models as the container for business logic, although you don't have to put anything besides your setup there.

class LceInputHandler(
    private val repo: LceRepository,
) : InputHandler<LceInput, LceEvent, LceState> {

    override suspend fun InputHandlerScope<LceInput, LceEvent, LceState>.handleInput(input: LceInput) = when (input) {
        is LceInput.Load -> {
            updateState { it.copy(isLoading = true, error = null) }
            sideJob("load") {
                runCatching { repo.load() }
                    .onSuccess { postInput(LceInput.Loaded(it)) }
                    .onFailure { postInput(LceInput.Failed(it)) }
            }
        }
        is LceInput.Loaded -> updateState { it.copy(isLoading = false, items = input.items, error = null) }
        is LceInput.Failed -> {
            updateState { it.copy(isLoading = false, error = input.error.message ?: "Unknown error") }
            postEvent(LceEvent.ShowError(input.error.message ?: "Unknown error"))
        }
    }
}

object LceEventHandler : EventHandler<LceInput, LceEvent, LceState> {
    // In Compose, collect events and show snackbar/nav inside LaunchedEffect (use platform integrations)
    override suspend fun EventHandlerScope<LceInput, LceEvent, LceState>.handleEvent(event: LceEvent) = Unit
}

fun createLceViewModel(
    repo: LceRepository,
    scope: CoroutineScope,
): BallastViewModel<LceInput, LceEvent, LceState> = BasicViewModel(
    config = BallastViewModelConfiguration.Builder()
        .withViewModel(
            initialState = LceState(isLoading = true),
            inputHandler = LceInputHandler(repo),
            name = "LceViewModel",
        )
        .build(),
    eventHandler = LceEventHandler,
    coroutineScope = scope,
).also { it.trySend(LceInput.Load) }

As you can see, the library doesn't lie when it claims to be opinionated. The structure is very interesting, but let's see what it gives us.

Benefits of Ballast

I would say this library doesn't try to please everyone. It isn't try-hard like FlowMVI, or "junior-friendly" like Orbit, or boasting its "structure" like MVIKotlin. Instead, you will enjoy Ballast if you catch its drift, period.

Ballast is the second library among the 70 that I compared in terms of features and functionality. It gives you a ready-made solution with some enhancements and cool stuff for every layer of your application architecture. It gives you tools and tricks for:

The UI layer
The view model layer
Even the repository layer

Ballast features native integration with Firebase Analytics and can integrate with any other analytics services. It has a rich concept of interceptors and decorators that is actually similar to how they are done in FlowMVI, while also staying kind of simple and true to the MVI principle.

I like Ballast because it is very inspiring. It has many features while also staying down to business. It doesn't try as hard as FlowMVI to be "different".

Ballast has a unique feature which allows you to synchronize your state and intents to an actual remote server, which no other library has. And that's not including some other interesting stuff you'll find if you dive into the docs. You should definitely check it out and get inspired by what you can build.

Ballast's developer tooling is also great, featuring its own time travel and debugging plugin, with quite a number of uses, and a rich ecosystem built around creating apps fast and easy. I would say that's the core philosophy of Ballast - it's like a complete batteries-included solution for you to build actual apps with this library. The whole idea strikes me as kinda cool.

Downsides of Ballast

As it often happens, the nature of Ballast being so opinionated is also its biggest drawback. I feel like the library tries to do everything, but only in one particular way. So what if you aren't on the same wavelength as the authors of Ballast? Then you're going to have a really bad time, obviously.

For example, I found that the Firebase Analytics integration only sends events in a particular way and isn't really flexible enough to send them in any other way or specialize them for any given page in the app, unlike what FlowMVI provides with its more generic but also more flexible implementation. The same can be said for the repository and caching functionality.

If you get the same use cases for caching and structure your repositories in the same way as Ballast encourages you to (after reading that big chunk of documentation on the official Ballast website), you will be golden. But as soon as you get a use case that doesn't fit the pattern or you need to make a change, you may have to ditch what Ballast has built for you and start working on something else. This can lead to fragmentation and, frankly, just rewriting the same stuff with slight changes. Maybe you'll find the use cases that Ballast provides you not sufficient or features not flexible enough. That's a real issue.

I've also found that the library seems to be maintained but not really super actively promoted or developed. Because the library is really opinionated, if the authors don't have any of the same use cases as you do, then there is no real incentive for them - and it isn't really in their general philosophy - to build something extra on top of what already exists.

My third problem is that the library kind of tries to mix and match a bunch of stuff. FlowMVI seems to be really consistent in its style - it gives this Gen Z vibe of "let's do everything with lambdas". But Ballast employs a combination of Java-style builders with DSLs, with lambdas, and then with factories. It has something that looks like a reducer but also isn't really a reducer - it's now an InputHandler. And then it uses view models and has the concept of view models, but then the view models aren't really view models - they are just wrappers for view model builders, whatever that means for Ballast. I just find the terminology sometimes confusing. Even though it makes sense conceptually, the library could probably benefit from some consistency overall in the general style that it has.

Ballast library use cases

You will really enjoy Ballast if you have similar use-cases as the library's authors.

The people who benefit the most from this library will be small teams that build a specific type of apps and aren't really afraid to adopt someone else's architectural patterns. In this case, if you really have similar use cases and considerations, then you will greatly benefit and save a lot of time, save a lot of code and get an amazing feature set out of this library.

But if you're not really following the patterns that Ballast gives you, and you have, for example, a huge app, a big enterprise solution, or, on the other hand, you have a really simple app and you don't want to invest into understanding everything that Ballast gives you, then you're not really a good fit for using Ballast.

In the first case (huge app / enterprise), you're better off using something either structured like MVIKotlin or flexible like FlowMVI, depending on your philosophy and needs.
In the second case (very simple app), you're better off just using Orbit as the simplest-to-understand solution for learning and to get up to speed quickly.

So Ballast is kind of in this middle space of not really leaning into anything in particular.

Bonus: A spreadsheet comparing 70 architecture libraries

I will admit I kind of went overboard when researching all of these libraries. I found more than 70 different state management / MVI / architectural libraries and compared them over 100+ criteria. So this write-up is based mostly on my research that I did for those architectural libraries.

I'd like to thank my colleague Artyom for doing the first part of the research originally for the Mobius conference we spoke at. Recently I decided to update those research findings to include more criteria, more features and re-evaluate every single library because many of them had major releases since then.

And of course I will keep the spreadsheet updated as long as I can. Some stuff is updated automatically there, such as maintainability status. I will keep adding new features for comparing. Please let me know if I made any mistakes in there, you want your library added, or you just have something to say via email.

The spreadsheet has all the honorable mentions - definitely check them out! I'm sorry if i didn't include your library here - this article is huge as-is!

Keep in mind that the scores in the spreadsheet are purely subjective and use a very simple formula which multiplies the weight with the checkbox status. The weights were selected for an "average Joe" developer and thus are pure speculation, so you should check the full list and find specific features that are important to your team.

Comparison of 70 Kotlin Architecture Libraries Over 100 Criteria

I Found the #1 Cause of Freezes in Your app, and Heres the Proof

Nek.12 — Tue, 11 Nov 2025 15:50:45 +0000

A lot of people ask me why I hate SharedPreferences, and at my job some people are even arguing with me that SharedPreferences are a good thing and that they don't lead to any problems whatsoever.
But from my six years of development experience and more than 15 projects, I know that SharedPreferences are literally the number one cause of ANRs in many popular apps and third-party frameworks.

You will always have ANRs because of them, no matter what you do (no, edit doesn't help!). And in this post I will spill expose why you should remove SharedPreferences from your project ASAP.

Problem #1: SharedPreferences are fundamentally flawed and you can't fix that with any code you write

The problem isn't how SharedPreferences are implemented internally - it's in the paradigm of providing synchronous access to disk data. A priori, this will always lead to problems, because by definition of synchronous access, you cannot avoid reading the resource on the same thread that you called it. SharedPreferences create a fake facade of asynchronicity. They provide you APIs like apply and commit, but under the hood they still read from disk on main thread.

Why, you ask? Because it's impossible to do otherwise. You have to read a file, and reading a file takes an arbitrary amount of time, sometimes more than 5 seconds. And I will talk about why later, but right now let's take that for granted. So you try to read a file. Where are you gonna get those 5 seconds from? If you're trying to read from SharedPreferences (or create their object) directly during application startup, or in composable code, or while the application is initializing its dependency injection graph, you will cause an ANR. If the file system is contended and you have to wait, then guess what thread will wait for that file read? Of course, the main thread, because you invoke SharedPreferences constructor/operations on main thread.

If you want to not do that, try to get rid of all references to SharedPreferences on main thread. You will face a huge issue because SharedPreferences API assumes that you can, for some reason, create and call them safely on whatever thread you run. And SharedPreferences API doesn't indicate in any way that it will perform a synchronous file creation and read on whatever thread you try to create an object. That's obviously a huge flaw in the design and should never have been allowed. With SharedPreferences, it's just too easy to make this stupid mistake. There is no suspend modifier on any calls, there is no proper flow-based, coroutine-based API for observing the changes, there is no reactive way to retrieve the parameters. That's not an AOSP bug, but a design flaw. And spoiler so you don't try to actually do it: that won't help.

The reason it is designed that way is because we didn't know better in 2011. SharedPreferences were there from the first version of Android, and that was the time where we used Java. We didn't care about main thread, we didn't know what problems reading files on main thread can even cause. Nobody cared about ANRs because users didn't mind and were used to all kinds of errors, and we didn't have coroutines which allow us to write concurrent code procedurally. But now we do have all these things, and we have much higher standards for our applications. Why would we still use SharedPreferences nowadays?

If you want proofs, here's the source code of literally the Android SDK:

@Override
@Nullable
public String getString(String key, @Nullable String defValue) {
    synchronized (mLock) {
        awaitLoadedLocked();
        String v = (String)mMap.get(key);
        return v != null ? v : defValue;
    }
}

private void awaitLoadedLocked() {
    if (!mLoaded) {
        // Raise an explicit StrictMode onReadFromDisk for this
        // thread, since the real read will be in a different
        // thread and otherwise ignored by StrictMode.
        BlockGuard.getThreadPolicy().onReadFromDisk();
    }
    while (!mLoaded) {
        try {
            mLock.wait();
        } catch (InterruptedException unused) {
        }
    }
    if (mThrowable != null) {
        throw new IllegalStateException(mThrowable);
    }
}

The StrictMode violation there is even explicit! This code awaits a full "load" of the SharedPreferences on whatever thread you try to get the value from if it hasn't managed to load the file fully yet (awaitLoadedLocked).

So, what that means is that when you happily call sharedPreferences.getBoolean("isDarkMode") in your composable code, you are essentially adding an ANR and freeze to your app under file system contention circumstance. Not so confident now?

The only reason you haven't encountered this freeze is that you were lucky. You created SharedPreferences early enough and so far apart from your actual reads that the system managed to read from a file on time on your specific set of devices, or that your app wasn't frozen for exactly five seconds. For example, it was frozen for two and a half seconds. But if you ever find yourself wondering where those mysterious freeze and lag complaints come from your negative Play Store reviews from users on cheap devices, maybe that's the place?

Problem #2: The QueuedWork hack that hides ANRs from you

Let's talk about another place where SharedPreferences cause ANRs. I get why many people don't think that SharedPreferences cause their ANRs: it's because they are so convoluted that I didn't believe it either at first. The main reason the ANRs happen is that when you call apply on SharedPreferences, they give you a fake promise of asynchronous work. The reason they do is because the authors of SharedPreferences wanted to make those operations fast for main thread and then offload the work to some other place where it would be "safer" to block. Because of that they created the so-called QueuedWork class:

/**
 * Trigger queued work to be processed immediately. The queued work is processed on a separate
 * thread asynchronous. While doing that run and process all finishers on this thread. The
 * finishers can be implemented in a way to check weather the queued work is finished.
 *
 * Is called from the Activity base class's onPause(), after BroadcastReceiver's onReceive,
 * after Service command handling, etc. (so async work is never lost)
 */
public static void waitToFinish() {
    long startTime = System.currentTimeMillis();
    boolean hadMessages = false;
    synchronized (sLock) {
        if (DEBUG) {
            hadMessages = getHandler().hasMessages(QueuedWorkHandler.MSG_RUN);
        }
        handlerRemoveMessages(QueuedWorkHandler.MSG_RUN);
        if (DEBUG && hadMessages) {
            Log.d(LOG_TAG, "waiting");
        }
        // We should not delay any work as this might delay the finishers
        sCanDelay = false;
    }

    // author's note - [1]
    StrictMode.ThreadPolicy oldPolicy = StrictMode.allowThreadDiskWrites();
    try {
        processPendingWork();
    } finally {
        StrictMode.setThreadPolicy(oldPolicy);
    }
    try {
        while (true) {
            Runnable finisher;
            synchronized (sLock) {
                finisher = sFinishers.poll();
            }
            if (finisher == null) {
                break;
            }
            finisher.run();
        }
    } finally {
        sCanDelay = true;
    }
    synchronized (sLock) {
        long waitTime = System.currentTimeMillis() - startTime;
        if (waitTime > 0 || hadMessages) {
            mWaitTimes.add(Long.valueOf(waitTime).intValue());
            mNumWaits++;
            if (DEBUG || mNumWaits % 1024 == 0 || waitTime > MAX_WAIT_TIME_MILLIS) {
                mWaitTimes.log(LOG_TAG, "waited: ");
            }
        }
    }
}

Take a look at [1]! This is literally a hack that hides from you the problem of writing to disk. The creators of SharedPreferences lie to you - they disable StrictMode that you enabled through hard work, temporarily, just because they don't want you to see them using this hack.

This class specifically is created for hiding the asynchronous file reads and committing them in certain lifecycle callbacks. When SharedPreferences execute commit or apply, instead of writing to file immediately, they queue the work using this class. Then the Android framework calls specific methods of this class to commit or "finalize" the pending work (on main thread) to the disk. In the sources, the justification for this is that "the work is never lost". But as we already established, that's an outdated and false premise. That was created to give consumers a false sense of security that their file writes will never be lost, somewhere around 2010s or whatever. This is a flawed approach because instead of properly relying on the consumer to actually finish and await the call that is supposed to commit to a file, or using something like eager file writes with write-ahead logging, or even simply a copy-on-write algorithm, the SharedPreferences just postpone the negative consequences of delaying asynchronous work to some other method where they assumed that "it would be safe to block" the main thread because the UI doesn't care. But that isn't true at all since the application and activity lifecycle have changed significantly over the years and we are no longer using the activity lifecycle methods the same way that we used to back in the days.

This also derails your attempts at finding out about those ANRs, because the stack trace will now never point to the actual SharedPreferences call, which is what I warned about in my previous post on ANRs.

Here are example stack traces you'll get concretely in the app lifecycle (AOSP ActivityThread.java):

Activity pause (older pre-HC apps): after performPauseActivity(...), QueuedWork.waitToFinish() is invoked. Expect stacks like ActivityThread.handlePauseActivity → QueuedWork.waitToFinish.
Activity stop (modern apps): after performStopActivityInner(...), the framework runs QueuedWork.waitToFinish(). Expect stacks like ActivityThread.handleStopActivity → QueuedWork.waitToFinish.
Sleeping: handleSleeping also calls QueuedWork.waitToFinish().
Service start args: handleServiceArgs drains queued work before reporting serviceDoneExecuting(...). Expect stacks like ActivityThread.handleServiceArgs → QueuedWork.waitToFinish.
Service stop: handleStopService also drains. Expect stacks like ActivityThread.handleStopService → QueuedWork.waitToFinish.

Bonus: commit() can still write on the caller (UI) thread

For commit() (sync), enqueueDiskWrite(..., /*postWriteRunnable=*/ null) treats it as a synchronous commit and may run writeToDiskRunnable.run() on the current thread (see the isFromSyncCommit and wasEmpty fast-path). If you ever call commit() from the main thread, that's immediate UI-thread I/O.

"But it's only 2 milliseconds!"

But here's the last point that people who argue with me bring up usually:

"Oh, but it's only a 2 millisecond read. It's nothing. It's just an atomic file operation on main thread... I saw StrictMode violation and it says the duration was 5 milliseconds. Nobody is ever going to notice that! We are not gonna fix it because it is just a small delay. You're just making a mountain out of a molehill!"

As we already established, the first point is that the apply isn't really asynchronous. It just queues the work to be done, but then registers a finisher which will be run in various lifecycle callbacks. So if that call ever happens to be slow, then you will get an ANR in one of those callbacks or at application start. That should be obvious that it can manifest in negative consequences now.

The second point is that the actual on-disk flush is a blocking fsync/sync - and Android's own source tracks its tail latency. The write path ends in FileUtils.sync(out) → out.getFD().sync(), i.e., a blocking flush. SharedPreferencesImpl even logs/records fsync durations and warns when they exceed a threshold, which exists because fsync can be slow.

In simple terms, this means that cheap devices, slow memory, external memory such as SD cards, and at various points of system lifecycle where there are high amounts of workload (e.g. the user is performing some heavy file access operations such as transcoding media or playing a high quality video), there is a very high likelihood that the system calls that issue disk writes will enter contention for resources. This doesn't reproduce in sterile QA testing or debug builds environments, especially if the team uses an emulator or some sort of expensive device that has enough bandwidth to handle all the file writes. And especially since the data that is usually being stored in SharedPreferences on debug builds is much smaller in size than it can get on production builds. (You're not writing unbounded lists to a single XML file, are you?)

What that means is that this is an expected behavior from the system. When the OS syscall enters contention and suspends the thread to perform a write/read and synchronize op to the file system, it may wait for an indefinite amount of time for other operations to finish or for the system security service to grant the app access to its data directories or external storage, which can lead to, in some rare cases, the operating system file operations taking significantly longer than they are used to. This is very hard to reproduce because you aren't usually running stress tests or load testing of your app on a 100$ Xiaomi budget device, are you? But this is how real-world devices operate. For example, if you try to perform file r/w in a BOOT_COMPLETED broadcast, like I mentioned in my previous post, you have the "best" chance of catching this contended state because hundreds of other apps are also running a boot completed broadcast at the same time, and as you know, broadcasts are executed on main thread. So if you ever wondered why your broadcast stack traces show up in ANR reports in Crashlytics, then this is your answer.

Even though direct file system contention isn't as much of an issue as it used to be, this improvement is greatly compensated for by the introduction of scoped storage and new SAF and FUSE policies on the Android side, which are much slower than standard reads. So when the user's device writes gigabytes of data, and your app happens to be open, guess who's gonna bear the burden of a huge journal flush caused by a fsync call? For skeptics, here's a paper that measured real delays in ext* file systems.

And guys, not to take credit for this, but if you think this is some new information that nobody previously knew about, I'm honestly just expanding a bit on an official Android developers documentation, so even for those that say "Oh, we will only do what Google recommends and not some random guy on the internet", please be my guest and implement a better I/O architecture.

The invisible problem: freezes that don't show up in Crashlytics

My problem here when discussing this is that I'm gonna be honest with you guys, I can't give you charts showing fsync latency is going off the rails. There is no public data - believe me, I searched - for this kind of metrics because they are internal Android analytics, it isn't at all in Google's interests to disclose how bad the file read operations are. I can point you to a hundred different stack traces from my own apps and towards discussions of thousands of other people complaining about this exact same issue, but I cannot give you a definitive conclusion on how many users exactly are facing this issue.

If you target cheaper devices which are still very popular in the world, you are bound to have ANRs due to this. Or what's worse in my opinion is that you will likely not have real ANRs which are reported to Crashlytics. What you're likely suffering from is significant delays and freezes in the app that the users are aware and perceive, but those are not long enough to trigger an actual ANR. This ruins your app's user experience but doesn't surface in any of Crashlytics services or bug reports because it's not as evident. All you will see is some strange user complaining about how the app is slow or laggy or constantly freezes and you will dismiss their review as an outlier. But then you will wonder why your users are leaving so much.

So don't take this lightly. If you believe in official documentation and real world issues and this explanation, try using some other approach other than SharedPreferences. It isn't that hard, I promise. For example, DataStore offers you a safe suspending API with the copy-on-write algorithm under the hood. I know that some people don't like, saying "it isn't as convenient to use" because it doesn't give you a synchronous API to invoke on main thread. But you know, maybe the design of DataStore is like that for a reason? And we should think about why we are facing challenges during development, and sometimes go along with them, instead of opting for the easiest solution possible.

A proper asynchronous API for disk operations and strong developer ethics will not just solve your ANR problem, they will teach you how to work with data reactively and efficiently.

I achieved 0% ANR in my Android app. Spilling beans on how I did it - part 1

Nek.12 — Sun, 09 Nov 2025 17:13:44 +0000

After a year of effort, I finally achieved 0% ANR in Respawn. Here's a complete guide on how I did it.

Let's start with 12 tips you need to address first, and in the next post I'll talk about three hidden sources of ANR that my colleagues still don't believe exist.

1. Add event logging to Crashlytics

Crashlytics allows you to record any logs in a separate field to see what the user was doing before the ANR. Libraries like FlowMVI let you do this automatically. Without this, you won't understand what led to the ANR, because their stack traces are absolutely useless.

2. Completely remove SharedPreferences from your project

Especially encrypted ones. They are the #1 cause of ANRs. Use DataStore with Kotlin Serialization instead. I'll explain why I hate prefs so much in a separate post later.

3. Experiment with handling UI events in a background thread

If you're dealing with a third-party SDK causing crashes, this won't solve the delay, but it will mask the ANR by moving the long operation off the main thread earlier.

4. Avoid using GMS libraries on the main thread

These are prehistoric Java libraries with callbacks, inside which there's no understanding of even the concept of threads, let alone any action against ANRs. Create coroutine-based abstractions and call them from background dispatchers.

5. Check your Bitmap / Drawable usage

Bitmap images when placed incorrectly (e.g., not using drawable-nodpi) can lead to loading images that are too large and cause ANRs.

Non-obvious point: This is actually an OOM crash, but every Out of Memory Error can manifest not as a crash, but an ANR!

6. Enable StrictMode and aggressively fix all I/O operations on the main thread

You'll be shocked at how many you have. Always keep StrictMode enabled.

Important: enable StrictMode in a content provider with priority Int.MAX_VALUE, not in Application.onCreate(). In the next post I'll reveal libraries that push ANRs into content providers so you don't notice.

7. Look for memory leaks

**Never use coroutine scope constructors (CoroutineScope(Job())). Add timeouts to all suspend functions with I/O. Add error handling. Use LeakCanary. Profile memory usage. Analyze analytics from step 1 to find user actions that lead to ANRs.

80% of my ANRs were caused by memory leaks and occurred during huge GC pauses. If you're seeing mysterious ANRs in the console during long sessions, it's extremely likely that it's just a GC pause due to a leak.

8. Don't trust stack traces

They're misleading, always pointing to some random code. Don't believe that - 90% of ANRs are caused by your code. I reached 0.01% ANR after I got serious about finding them and stopped blaming Queue.NativePollOnce for all my problems.

9. Avoid loading files into memory

Ban the use of File().readBytes() completely. Always use streaming for JSON, binary data and files, database rows, and backend responses, encrypt data through Output/InputStream. Never call readText() or readBytes() or their equivalents.

10. Use Compose and avoid heavy layouts

Some devices are so bad that rendering UI causes ANRs.

Make the UI lightweight and load it gradually.
Employ progressive content loading to stagger UI rendering.
Watch out for recomposition loops - they're hard to notice.

11. Call goAsync() in broadcast receivers

Set a timeout (mandatory!) and execute work in a coroutine. This will help avoid ANRs because broadcast receivers are often executed by the system under huge load (during BOOT_COMPLETED hundreds of apps are firing broadcasts), and you can get an ANR simply because the phone lagged.

Don't perform any work in broadcast receivers synchronously. This way you have less chance of the system blaming you for an ANR.

12. Avoid service binders altogether (bindService())

It's more profitable to send events through the application class. Binders to services will always cause ANRs, no matter what you do. This is native code that on Xiaomi "flagships for the money" will enter contention for system calls on their ancient chipset, and you'll be the one getting blamed.

If you did all of this, you just eliminated 80% of ANRs in your app.
Next I'll talk about non-obvious problems that we'll need to solve if we want truly 0% ANR.
Subscribe to social media or the newsletter so you don't miss part two.

How I built a game engine using MVI in Kotlin and avoided getting fired

Nek.12 — Fri, 07 Nov 2025 11:41:56 +0000

In this article, I'll tell you a story about how our team created a multiplatform, full-fledged game engine using MVI architecture, fully in Kotlin! You will also learn about how I implemented some insane requirements from our customer when working on said engine. So let's jump right in!

I'm working on an app called Overplay. It's similar to TikTok, but the videos you see are actually games that you can play as you scroll. One day, I was painting another button when the customer came to me to discuss the app's performance and the experience of starting and finishing a game. In short, the problem we had for years was the legacy game engine.

It was still using XML on Android and contained 7 thousand lines of legacy code, most of which was dead but still executed, tanking the performance. The experience was not fluid, the game loaded slowly (20 seconds to load a game was a regular occurrence for us), and it was laggy. We also had a lot of nasty crashes related to concurrency and state management because dozens of different parts of the engine wanted to send events and update the game state simultaneously. The team had no idea how to solve those issues - our current simple MVVM architecture was not holding up at all. Only the ViewModel contained 2000 lines of code, and any change exploded something else.

So the customer said - time to make the game engine great again. But the new requirements he wanted to be implemented were just bonkers:

The game engine must be embedded directly into the feed of games to let the user scroll away once they finish the game. It means it has to be inside another page and bring all the logic with it!
The game engine must start games in less than 2 seconds flat. This means that everything has to be managed in parallel and in the background as the user scrolls!
If the user replays or restarts the game, the loading must be instant. Thus, we have to keep the engine running and manage the resources dynamically.
Every single action of the user must be covered by analytics to keep improving it in the future.
The game engine must support all sorts of videos, including local ones for when someone wants to make their own game and play it.
Since the user scrolls through videos like on TikTok, we need to efficiently free and reuse our media codecs and video players to seamlessly jump back and forth between playing a game video and other items of the feed.
All errors must always be handled, reported, and recovered from to ensure we no longer ruin the users' experience with crashes.

I'm gonna be honest, I thought I was gonna get fired.

"There's no way to implement this crazy logic in 1 sprint" - I thought. Half of the app must be easily embeddable and the state must always be consistent, with hundreds of state updates going on at the same time: the device sensors, our graphic engine, the video player, and more. Everything has to be reused everywhere and loaded in parallel. To put the last nail in the coffin, the amount of code has to be kept small as well to let the team make future changes to the engine without shooting themselves in the foot.

But I had to do it, there was no way to avoid it this time. Of course, I couldn't have done this alone. Huge props to the team:

One member took our graphics engine and made it compatible with Compose since there was no way we were doing that without Compose.
Another developer spent time making a module for the Game Loop which sends events and orchestrates the graphics engine.

Preparations

So I was responsible for game loading and overall integration in the end. And I thought - well, these requirements are not about features, they are about architecture. My task was to implement the architecture that supports all of those. Easier said than done though...

Here's a simplified diagram of what my final architecture looked like:

An important thing to understand before we begin is that to implement the new architecture, I got inspired by Ktor and their amazing system of "Plug-Ins" that form a chain of responsibility and intercept any incoming and outgoing events. Why not use this for any business logic, I thought? This is a new approach to app architecture because we used to only do this kind of thing with CQRS on the backend or in networking code.

Luckily, this was already implemented in the architectural framework we were using - FlowMVI - so I didn't need to write any new code for this, I just needed to use the plugin system creatively now. But the framework was meant for UI, not game engines! I had to make some changes to it if I didn't want to get fired.

So over the next two weeks, I spent time implementing the supporting infrastructure:

I added a bunch of new plug-ins that will allow me to inject any code into any place in the game engine's lifecycle. We'll talk about those in a moment.
I ran benchmarks hundreds of times, comparing the performance with the fastest solutions to ensure we get maximum performance. I worked on the code until I optimized the library to the point that it became top-5 in performance among 35+ frameworks benchmarked, and as fast as using a simple Channel (from coroutines).
I implemented a new system for watching over the chain of plugin invocations which allowed me to monitor processes in any business logic transparently, which I very creatively named "Decorators."

I also set a requirement for myself - ANY piece of logic must be a separate thing in the engine's code that can be removed and modified on demand. The code must not be placed in the same class. My goal was - I'm gonna keep the engine's code less than 400 lines long.

This felt like arming myself to the teeth as some secret ops dude from a movie. I was ready to crush this.

Let's go.

Getting Started - Contract

First of all, let's define a simple family of MVI states, intents and side-effects for our engine. I used FlowMVI's IDE plugin, typed fmvim in a new file, and got this:

internal sealed interface GameEngineState : MVIState {
    data object Stopped : GameEngineState
    data class Error(val e: Exception?) : GameEngineState
    data class Loading(val progress: Float = 0f): GameEngineState
    data class Running(
        override val game: GameInstance,
        override val player: MediaPlayer,
        override val isBuffering: Boolean = false,
    ) : GameEngineState
}

internal sealed interface GameEngineIntent : MVIIntent {
    // ...
}

internal sealed interface GameEngineAction : MVIAction {
    data object GoBack : GameEngineAction
}

I also added a Stopped state (since our engine can exist even when not playing), and a progress value to the loading state.

Configuring our Engine

I started by creating a singleton called Container, which will host the dependencies. We have to keep it as a singleton and start/stop all its operations on demand to support instant replay of games and caching. We're going to try and install a bunch of plugins in it to manage our logic. So, to create it, I typed fmvic in an empty file and then added some configuration:

internal class GameEngineContainer(
    private val appScope: ApplicationScope,
    userRepo: UserRepository,
    configuration: StoreConfiguration,
    pool: PlayerPool,
    // ...
) : Container<GameEngineState, GameEngineIntent, GameEngineAction>, GameLauncher {

    override val store by lazyStore(GameEngineState.Stopped) {
        configure(configuration, "GameEngine") // 1
        configure {
            stateStrategy = Atomic(reentrant = false) // 2
            allowIdleSubscriptions = true
            parallelIntents = true // 3
        }
    }
}

This way, we can easily inject the dependencies here. The "Store" is the object that will host our GameState, respond to GameIntents, and send events to the UI (GameActions).

Here I am transparently injecting some stuff into the store using DI, more on that in a bit.
During my benchmarks, I found out that reentrant state transactions (which I discussed in my previous article) were tanking performance. They are 15x slower than non-reentrant ones! The time is still measured in microseconds so it makes sense to use them for simple UI, but we had to squeeze every last drop of CPU power for the engine. I added support for those in the latest update, which reduced the time to nanoseconds per event!
Everything had to be parallel for the game engine to keep it fast, so I enabled parallel processing. But if we don't synchronize state access, we'll have the same race conditions we had before! By enabling this flag while keeping atomic state transactions, I achieved the best of both worlds: speed and safety!

We got ourselves so far:

Speed
Thread-safety
Ability to keep resources loaded on demand
Analytics and Crash reporting

"Wait", you may ask, "but there isn't a single line of analytics code in the snippet!", and I will answer - the magic is in the injected configuration parameter.

It installs a bunch of plug-ins transparently. We can add any logic to any container using the concept of plug-ins, so why not use those with DI? That function installs an error handler plugin that catches and sends exceptions to analytics without affecting the rest of the engine's code, tracks user actions (Intents), and events of visiting and leaving the game engine screen as well. Having the huge game engine polluted by analytics junk is a no-no for us because we had this problem with MVVM - all of the stuff just gets piled on and on and on until it becomes unmaintainable. No more.

Starting and Stopping the Engine

Okay, so we created our Container lazily. How do we clean up and keep track of resources now?

The thing about FlowMVI is that it's the only framework I know that allows you to stop and restart the business logic component (Store) on demand. Each store has a StoreLifecycle which can let you control and observe the store using a CoroutineScope. If the scope is canceled - the store is, but the store can also be stopped separately, ensuring our parent-child hierarchy is always respected.

My colleagues were skeptical about this feature at first, and for a while, I thought it was useless, but this time it literally saved my ass from getting fired: we can just use the global application scope to run our logic, and stop the engine when we don't need it to keep consuming resources!

For the implementation, we're just going to let the Container implement an interface called GameLauncher that will access the lifecycle for us:

override suspend fun awaitShutdown() = store.awaitUntilClosed()

override fun shutdown() = store.close()

override suspend fun start(params: GameParameters) {
    val old = this.parameters.getAndUpdate { params }
    when {
        !store.isActive -> store.start(appScope).awaitStartup() // 1
        old == params -> store.intent(ReplayedGame) // 2
        else -> { // 3
            store.closeAndWait()
            store.start(appScope).awaitStartup()
        }
    }
}

Then the code from other modules will just use the interface to stop the engine when it doesn't need the game to keep running (e.g. the user has scrolled away, left the app, etc.), and call start each time the clients want us to play the game. But this feature would only be marginally usable for us if the store didn't have a way to do something when it is shut down. So let's talk about resource management next.

Managing Resources

We have a lot of stuff to initialize upon the game start in parallel:

Remote configuration for feature flags
Game assets like textures need to be downloaded and cached
Game Configuration and the game JSON data
Media codec initialization
Video file buffering and caching
And more...

And almost everything here cannot be simply garbage collected. We need to close file handles, unload codecs, release resources held by native code, and return the video player to the pool to reuse it, as player creation is a very heavy process.

And some stuff actually depends on the other, like the video file depends on the game configuration where it comes from. How do we do that?

Well, for starters, I created a plug-in that will use the callback mentioned above to create a value when the engine starts, and clean the value up when the engine stops (simplified code):

public fun <T> cached(
    init: suspend PipelineContext.() -> T,
): CachedValue<T> = CachedValue(init)

fun <T> cachePlugin(
    value: CachedValue<T>,
) = plugin {
    onStart { value.init() }
    onStop { value.clear() }
}

A CachedValue is just like lazy but with thread-safe control of when to clear and init the value. In our case, it calls init when the store starts, and clears the reference when the store stops. Super simple!

But that plugin still has a problem because it pauses the entire store until the initialization is complete, which means our loading would be sequential instead of parallel. To fix that, we can simply use Deferred and run the initialization in a separate coroutine:

inline fun <T> asyncCached(
    context: CoroutineContext = EmptyCoroutineContext,
    start: CoroutineStart = CoroutineStart.UNDISPATCHED,
    crossinline init: suspend PipelineContext.() -> T,
): CachedValue<Deferred<T>> = cached { async(context, start) { init() } }

Then we just pass our asyncCached instead of the regular one when installing the cache plugin. Sprinkle some DSL on top of that, and we get the following game-loading logic:

override val store by lazyStore(GameEngineState.Stopped) {
    configure { }

    val gameClock by cache {
        GameClock(coroutineScope = this) // 1
    }

    val player by cache {
        playerPool.borrow(requireParameters.playerType)
    }

    val remoteConfig by asyncCache { // 2
        remoteConfigRepo.updateAndGet()
    }

    val graphicsEngine by asyncCache {
        GraphicsEngine(GraphicsRemoteConfig(from = remoteConfig()) // 2
    }

    val gameData by asyncCache {
        gameRepository.getGameData(requireParameters().gameId)
    }

    val game by asyncCache {
        GameLoop(
            graphics = graphicsEngine(),
            remoteConfig = remoteConfig(),
            clock = gameClock,
            data = gameData(),
            params = requireParameters(),
        ).let { GameInstance(it) }
    }

    asyncInit { // 3
        updateState { Loading() }
        player.loadVideo(gameData().videoUrl)
        updateState {
            GameEngineState.Running(
                game = game(),
                player = player,
            )
        }
        clock.start()
    }

    deinit { // 4
        graphicsEngine.release()
        player.stop()
        playerPool.return(player)
    }
}

Our game clock runs an event loop and synchronizes game time with video time. Unfortunately, it requires a coroutine scope where it runs the loop that should only be active during the game. Luckily, we already have one! PipelineContext, which is the context of the Store's execution, is provided with plugins and implements CoroutineScope. We can just use it in our cache plugin and start the game clock, which will automatically stop when we shut down the engine.
You can see we used a bunch of asyncCaches to parallelize loading, and with the Graphics Engine, we also were able to depend on remote config inside (as an example, in reality it depends on lots of stuff). This greatly simplifies our logic, because the dependencies between components are implicit now, and the requesting party who wants just the graphics engine doesn't have to manage the dependencies of it! The operator invoke (parentheses) is a shorthand for Deferred.await() for that extra sweet taste.
We have also used an asyncInit which essentially launches a background job in the current game engine's gameplay scope to load the game. Inside the job, we do final preparations, wait for all of the dependencies, and start the game clock.
We have used the built-in deinit plugin to put all of our cleanup logic in the callback that is invoked as soon as the game engine is stopped (and its scope is canceled). It will be run before our cached values are cleaned up (because it was installed later), but after our jobs have been canceled, so that we can do what we want, and the cache plugin will then garbage-collect the rest of the stuff without us worrying about leaks.

Overall, these 50 lines of code have replaced 1.5 thousand lines of our old game engine's implementation! I had to pick up my jaw from the floor when I realized how powerful these patterns are for business logic.

But we're still lacking one thing.

Error Handling

A lot of things in the engine can go wrong during gameplay:

Some game-author forgot to add a frame to an animation
A person lost their connection during the game
The shaders failed rendering due to a platform bug, and more...

Usually, only the main errors for API calls are handled in apps with wrappers like ApiResult or some kind of try/catch. But imagine wrapping every single line of the Game Engine's code in a try-catch... That would mean hundreds of lines of try-catch-finally garbage!

Well, you probably know what will happen. Since we can intercept any event now, let's make an error-handling plug-in! I named it recover, and now our code looks like this:

override val store by lazyStore(GameEngineState.Stopped) {
    configure { } // 1
    val player by cache { }

    recover { e ->
        if (config.debuggable) updateState { // 1
            GameEngineState.Error(e)
        } else when(e) { // 2
            is StoreTimeoutException, is GLException -> Unit
            is MediaPlaybackException -> player.retry()
            is AssetCorruptedException -> assetManager.refreshAssetsSync()
            is BufferingTimeoutException -> action(ShowSlowInternetMessage)
            // ...
            else -> shutdown() // 3
        }
        null
    }
}

If our store is configured to be debuggable (config is available in store plug-ins), we can show a full-screen overlay with the stack trace to let our QA team easily report errors to devs before they get to production. Fail Fast principle in action.
In production, however, we will handle some errors by retrying, skipping an animation, or warning the user about their connection without interrupting the gameplay.
If we can't handle an error and cannot recover, then we shut down the engine and let the user try to play the game again, without crashing the app or showing obscure messages (those go to crashlytics).

With this, we've got ourselves error-handling for any existing and new code a developer may ever add to our game engine, with 0 try-catches.

Final touches

We're almost done! This article is getting long, so I'll blitz through some additional plug-ins I had to install to support our use cases:

override val store by lazyStore(GameEngineState.Stopped) {
    configure { }

    val subs = awaitSubscribers() // 1
    val jobs = manageJobs<GameJobs>() // 2

    initTimeout(5.seconds) { // 3
        subs.await()
    }

    whileSubscribed { // 4
        assetManager.loadingProgress.collect { progress ->
            updateState<Loading, _> {
                copy(progress = progress)
            }
        }
    }

    install(
        autoStopPlugin(jobs), // 5
        resetStatePlugin(), // 6
    )
}

Since a developer can make the mistake of starting the game, but never displaying the actual gameplay experience (user left, a bug, plans changed, etc...), I am using the pre-made awaitSubscribers plugin in snippet (3) to see if they appear within 5 seconds of starting the game, and if not, close the store and auto-cleanup the held resources to prevent leaks. Boom!
I'm using another plug-in - JobManager, to run some long-running operations in the background. Code that uses it didn't fit, but essentially it's needed to track whether the user is currently playing.
InitTimeout is a custom plugin that verifies whether the game has finished loading within 5 seconds, and if not, we pass an error to our recover plugin to decide what to do and report the issue to analytics.
The whileSubscribed plugin launches a job that is only active when subscribers (in our case, UI) are present, where we update the visuals of the loading progress only when the user is actually seeing the loading screen. It allows us to easily avoid resource leaks if the game engine is covered up by something or hidden.
The autoStopPlugin uses our job manager to watch for game load progress and gameplay progress. It looks at whether we have subscribers to pause the game when the user leaves, then stop it once the engine is not used for a while, eliminating the risk of leaking memory.
The resetStatePlugin is a built-in one I had to install to auto-cleanup state when the game ends. By default, stores will not have their state reset when they stop. This is good for regular UI but not in our case - we want the engine to go back to the Stopped state when the game ends.

All of those plugins were already in the library, so using them was a piece of cake.

Conclusion

It was a wild ride, but after all this, I not only managed to keep my job, but I think that the overall solution has turned out pretty great. The engine went from 7+k to just 400 lines of readable, linear, structured, performant, extensible code, and the users are already enjoying the results:

Loading time went from ~20 seconds to just 1.75 seconds!
Crashed games fell from 8% to 0.01%!
We improved the throughput of the game event processing by 1700%
Video buffering occurrences during games went from ~31% to <10% due to our caching
Battery consumption during gameplay was reduced by orders of magnitude
ANRs during gameplay fell to being statistically 0
GC pressure decreased by 40% during gameplay

Hopefully, by this point, I've shown why the patterns we used to hate like Decorators, Interceptors, and Chain of Responsibility can be insanely helpful when building not just some backend service, networking code, or a specialized use-case, but also implementing the regular application logic, including UI and state management.

With the power that Kotlin gives when building DSLs, we can turn the fundamental patterns (used in software development for decades) from a mess of boilerplate, inheritance, and complicated delegation into fast, straightforward, compact, linear code that is fun and efficient to work with. I encourage you to build something like this for your own app's architecture and reap the benefits.

And if you don't want to dive into that and want something already available, or are curious to learn more, then consider checking out the original library where I implemented everything mentioned here on GitHub, or dive right into the quickstart guide to try it in 10 minutes.