Meeseeks is a Kotlin Multiplatform library for scheduling and managing background tasks across Android, JVM, native (iOS), and JS (Web). Whether your tasks are simple or complex, for one user or hundreds of millions, Meeseeks can help.
Kotlin Multiplatform runtime for scheduling and managing background tasks across Android, JVM, JS, and iOS.
Add Meeseeks in your shared KMP source set:
kotlin {
sourceSets {
commonMain.dependencies {
implementation("dev.mattramotar.meeseeks:runtime:<version>")
}
}
}
@Serializable
data object SyncPayload : TaskPayload
class SyncWorker(appContext: AppContext) : Worker<SyncPayload>(appContext) {
override suspend fun run(payload: SyncPayload, context: RuntimeContext): TaskResult {
return TaskResult.Success
}
}
val manager = Meeseeks.initialize(appContext) {
minBackoff(20.seconds)
maxRetryCount(3)
maxParallelTasks(5)
allowExpedited()
register<SyncPayload> { SyncWorker(appContext) }
}
val oneTime = manager.oneTime(SyncPayload) {
requireNetwork()
highPriority()
}
val periodic = manager.periodic(SyncPayload, every = 15.minutes) {
retryWithExponentialBackoff(initialDelay = 30.seconds, maxAttempts = 5)
}
val taskId = oneTime.id
val status = manager.getTaskStatus(taskId)
val stream = manager.observeStatus(taskId)
oneTime.cancel()
val missedEvents = manager.replayTerminalEvents(lastHandledEventId)
missedEvents.forEach { event ->
when (event.outcome) {
TaskEventOutcome.Success -> showCompleted(event.taskId)
TaskEventOutcome.Failure -> showFailed(event.taskId)
TaskEventOutcome.Cancelled -> showCancelled(event.taskId)
}
}
The 1.x SemVer contract is intentionally limited to these packages:
dev.mattramotar.meeseeks.runtimedev.mattramotar.meeseeks.runtime.dsldev.mattramotar.meeseeks.runtime.telemetrydev.mattramotar.meeseeks.runtime.typesAnything under dev.mattramotar.meeseeks.runtime.internal is implementation detail and not part of the compatibility promise.
ANDROID_HOMEANDROID_SDK_ROOTlocal.properties with sdk.dir=/absolute/path/to/Android/sdkexport ANDROID_HOME="/absolute/path/to/Android/sdk"
export ANDROID_SDK_ROOT="$ANDROID_HOME"
or create local.properties in the project root:
sdk.dir=/absolute/path/to/Android/sdk
# macOS example
export CHROME_BIN="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
# Linux example
export CHROME_BIN=/usr/bin/google-chrome
Run the preflight check before full builds:
./gradlew preflight
Then run the main verification commands:
./gradlew :runtime:jvmTest --stacktrace
./gradlew :runtime:jsTest --stacktrace
./gradlew clean build --stacktrace
For an all-in-one local validation pass:
./gradlew preflight clean build --stacktrace
Use this exact release gate before publishing:
./gradlew preflight clean build :runtime:jvmApiCheck :runtime:klibApiCheck :runtime:verifyCommonMainMeeseeksDatabaseMigration --stacktrace --warning-mode fail
Expected outcomes:
preflight passes with a valid Android SDK path and required SDK components.clean build passes across configured targets in CI/release environment.:runtime:jvmApiCheck and :runtime:klibApiCheck both execute and pass.:runtime:verifyCommonMainMeeseeksDatabaseMigration passes.preflight validates SDK component presence (platform-tools, licenses, and either build-tools or platforms) and fails if the SDK path is incomplete.Meeseeks uses Gradle dependency locking and verification metadata for reproducibility.
Typical update flow:
./gradlew :runtime:dependencies :sample:dependencies :tooling:plugins:dependencies --write-locks
./gradlew :commonizeNativeDistribution --write-locks
./gradlew --write-verification-metadata sha256 help
CI enforces verification metadata drift checks via bash scripts/ci/check-dependency-verification.sh.
1.x follows SemVer for the stable API packages listed above:
docs/capabilities.md.2.0.0, except for security-critical fixes.Apache 2.0. See LICENSE.
docs/platforms/android.mddocs/platforms/ios.mddocs/platforms/js.mddocs/completion-replay.mddocs/checkpoint-api-contract.mddocs/checkpoint-verification.mddocs/capabilities.mddocs/troubleshooting.mddocs/migration-0x-to-1x.mdCHROME_BINCHROME_BIN is optional in preflight. If browser auto-discovery fails at runtime, set CHROME_BIN explicitly before running :runtime:jsTest.SDK location not found:
ANDROID_HOME/ANDROID_SDK_ROOT or add sdk.dir to local.properties.Cannot start ChromeHeadless or Please set env variable CHROME_BIN:
CHROME_BIN to a valid Chrome/Chromium binary path.Cannot schedule task on <target>: unsupported preconditions [...]:
docs/capabilities.md for target support and fail-fast rules.Surfaced from shared tags and platforms — no rankings paid for.