The Nucleus framework lets you write cross-platform desktop applications using Kotlin. It is based on Compose Multiplatform and adds native window decorations, deep operating-system integration, code signing, and native installers — all configured through a single Gradle DSL. Your app runs either as a GraalVM Native Image or on the JVM.

It targets the gap between "a Compose Desktop window" and "an application the operating system treats as its own" — the work that is normally spread across a dozen half-maintained libraries and a hand-written packaging pipeline. Every OS integration is a real platform API behind a Kotlin one: no AWT dependency on the Tao backend, and the accessibility layer is verified against AT-SPI, UI Automation, and macOS AX in CI on all three platforms.

Read Why Nucleus for how it compares to vanilla Compose Desktop, Electron, and Tauri.

Project status

Published releases are 2.5.x (latest tag v2.5.0). Nucleus is under active development and moves fast. All published runtime modules run in Kotlin explicitApi() mode with their public surface locked by a binary-compatibility dump (api/*.api, checked by apiCheck via kotlinx binary-compatibility-validator). Breaking changes to a public FQN or signature fail CI. The one exception is decorated-window-jewel (JVM 25 bytecode), which still uses explicitApi() but is not dumped until BCV can read class-file major version 69.

Windowing runs on a single backend: the no-AWT Tao one. The legacy AWT-based backends (decorated-window-jni, decorated-window-jbr, and the shared decorated-window-awt chrome) are removed in 2.6. To migrate: depend on nucleus.decorated-window-tao, drop the backend = NucleusBackend.… argument (NucleusBackend and LocalNucleusBackend are gone), and replace AWT-typed window access (window.unsafe.awtWindow, Compose Desktop's Window / Dialog / Tray) with nucleusWindow, HostedWindow / HostedDialog, and an AWT-free tray.

Used by

Each line is the Nucleus surface that project actually depends on:

• AB Download Manager — packaging plugin, aot-runtime, tray
• SimpMusic — notifications
• Tasks.org — notifications
• CrossPaste — tray
• Husi — notifications, autolaunch, darkmode-detector, scheduler, core-runtime, tray
• Flare — packaging plugin, JNI window backend, darkmode-detector, aot-runtime
• Rush — packaging plugin
• Hammer — Tao backend, nucleus-application, decorated-window-material3, darkmode-detector, launcher
• OtakuWorld — nucleus-application, notifications, scheduler, taskbar-progress, system-color, system-info, core-runtime, aot-runtime, updater
• ZonePane — packaging plugin, Tao backend
• WG Tunnel — packaging plugin, Tao backend, nucleus-application, decorated-window-material3, core-runtime, darkmode-detector, system-color, energy-manager, system-info, updater, graalvm-runtime, tray
• Zayit — packaging plugin, Tao backend, nucleus-application, decorated-window-core, decorated-window-jewel, core-runtime, darkmode-detector, system-color, system-info, energy-manager, notifications, updater, aot-runtime, graalvm-runtime, native-http, launcher, menu-macos, taskbar-progress-tao, sf-symbols
• NOMM — packaging plugin, Tao backend, nucleus-application, decorated-window-material3, core-runtime, darkmode-detector, notifications, taskbar-progress, updater, aot-runtime, native-http, fs-watcher
• FuoEvolve — packaging plugin, Tao backend, nucleus-application, graalvm-runtime, media-control, notifications, launcher, tray
• CozySpace — packaging plugin, Tao backend, nucleus-application, decorated-window-core, darkmode-detector, tray
• Amethyst — packaging plugin, Tao backend, nucleus-application, updater, menu-macos, global-hotkey, system-info
• GitVantage — packaging plugin, Tao backend, nucleus-application, darkmode-detector, notifications, fs-watcher

Showcase

• EdgeTranslator — offline AI translator

Installation

Nucleus ships as a Gradle plugin. Apply it alongside the Kotlin and Compose plugins in your module's build.gradle.kts:

plugins {
    kotlin("jvm") version "2.4.10"
    id("org.jetbrains.compose") version "1.12.0"
    id("dev.nucleusframework") version "2.5.0"
}

repositories {
    mavenCentral()
    google()
}

dependencies {
    implementation(compose.desktop.currentOs)
    // Entry point — provides nucleusApplication and DecoratedWindow
    implementation("dev.nucleusframework:nucleus.nucleus-application:2.5.0")
    // Tao backend — Rust-native windowing
    implementation("dev.nucleusframework:nucleus.decorated-window-tao:2.5.0")
}

For more installation options, see the install guide and project setup.

Requirements

Nucleus builds on Compose Multiplatform and requires:

Platform support

Each build can compile, run, and package for macOS, Windows, and Linux from a single codebase.

• macOS — Intel (x64) and Apple Silicon (arm64), shipped as a universal binary. Liquid Glass on macOS 26.
• Windows — x64 and arm64.
• Linux — x64 and arm64, with Wayland and X11 support.

Getting started

Create src/main/kotlin/com/example/Main.kt:

package com.example

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import dev.nucleusframework.application.DecoratedWindow
import dev.nucleusframework.application.nucleusApplication

fun main(args: Array<String>) = nucleusApplication(args) {
    DecoratedWindow(
        onCloseRequest = ::exitApplication,
        title = "MyApp",
    ) {
        Box(Modifier.fillMaxSize()) {
            Text("Hello from Nucleus")
        }
    }
}

nucleusApplication initializes GraalVM native-image support, takes the single-instance lock, and primes autolaunch / Windows AUMID when those modules are on the classpath. Pass the process args so deep links, file associations, and "started at login" see the original command line. Windows are Tao-backed: the native event loop owns the main thread and doubles as Dispatchers.Main, with no AWT in the process. Inside the block you can call onDeepLink { } and aotTraining(); plugin-injected metadata is NucleusApp, not a generated constants object.

On macOS the Tao backend delivers trackpad gestures to Compose as pan events (PointerEventType.PanStart / PanMove / PanEnd, with panOffset in pixels) and mouse-wheel notches as Scroll, with the same distances the AWT backend produces. Foundation's Modifier.scrollable handles both; a custom pointerInput that only reacts to PointerEventType.Scroll must also handle pan, or start the app with -Dnucleus.tao.trackpadPanEvents=false to receive AWT-style Scroll events for everything.

Then configure packaging in build.gradle.kts:

nucleus.application {
    mainClass = "com.example.MainKt"

    nativeDistributions {
        packageName = "MyApp"
        packageVersion = "1.0.0"
        targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
    }
}

./gradlew run                              # Run locally in a native Tao window
./gradlew packageDistributionForCurrentOS  # Build an installer for your OS

The full quickstart walks through each step.

Resources for learning Nucleus

• nucleusframework.dev/en/docs — all of Nucleus's documentation
• Quickstart — build and package your first app
• Architecture — the layered model behind the framework
• examples/lab — the Nucleus Lab, one app that exercises every runtime module, plus the other samples

What Nucleus provides

Ship everywhere — 18 packaging formats (DMG, PKG, EXE, MSI, NSIS, NSIS-Web, Portable, AppX, DEB, RPM, Pacman, AppImage, raw AppImage, Snap, Flatpak, ZIP, TAR, 7Z), store publishing (Mac App Store, Microsoft Store, Snapcraft, Flathub), code signing and notarization, built-in auto-update, deep links, and file associations.

Feel native — Decorated windows with native controls, notifications, taskbar/dock badges and menus, media controls (MPRIS, Now Playing, SMTC), dark mode, accent colors, global hotkeys, system tray, native context menus, and OS spell check — all behind clean Kotlin APIs.

Perform — GraalVM Native Image compiles your app to a standalone binary with automatic reachability metadata; a Hello-World Compose window cold-starts in about 0.2 s and around 30 MB of RAM (measured on Windows 11). Or stay on the JVM with an AOT cache (JDK 25+) and ProGuard-optimized release builds.

Runtime modules

Each module is published independently to Maven Central — use them together or standalone.

Documentation

Full documentation is available at nucleusframework.dev (English and French).

Community

Ask questions, report bugs, and share what you're building on GitHub Discussions, the issue tracker, and #nucleus on the Kotlin Slack.

License

MIT