Plugin Lifecycle

Klyx manages your extension through four lifecycle methods. Each method is a suspend function running on the plugin’s coroutine scope, so you can safely call other suspend APIs.

Lifecycle overview

Load → onLoad() → onStart() → (running) → onStop() → onUnload() → Unloaded

Phase	Method	Purpose
1	`onLoad()`	Register resources, subscribe to events, set up infrastructure
2	`onStart()`	Begin operations that depend on other plugins
3	onStop	(Triggerable by user or system)
4	`onStop()`	Pause or release start-time resources
5	`onUnload()`	Full cleanup — unregister everything
6	Unloaded	Plugin removed from memory

onLoad()

Called when Klyx loads your extension. At this point, your plugin’s services (screens, toolbar, etc.) are available, but other plugins may not have started yet. What to do here:

Register screens with ScreenRegistry
Register toolbar actions with ToolbarRegistry
Register file openers with FileOpenerRegistry
Subscribe to events on the event bus
Register language server providers
Register tree-sitter language grammars
Initialize lightweight state

override suspend fun onLoad() {
    val bus = currentPluginContext().eventBus

    screens.register(Screen(ScreenId("myext.main")) { MainScreen() })

    toolbar.register(ToolbarAction(
        id = "myext.action",
        label = "My Action",
        category = ToolbarCategory("My Plugin"),
        priority = 100,
        onClick = { /* ... */ }
    ) {})

    // Subscribe to events
    bus.subscribe<FileOpenedEvent> { event ->
        showToast("Opened: ${event.fileName}")
    }
}

onStart()

Called after all plugins have completed onLoad(). This is the right place to interact with other plugins, access shared resources, or start ongoing work. What to do here:

Start coroutines for background work (via pluginScope or currentLifecycleOwner().lifecycleScope)
Access other plugins’ registered resources
Start long-running operations that depend on the full environment

override suspend fun onStart() {
    pluginScope.launch {
        // Background work tied to the plugin's lifetime
        val result = command("git", "status").output()
        showToast(result.stdoutText)
    }
}

onStop()

Called when Klyx is about to unload your extension. You should release any resources acquired in onStart(). What to do here:

Cancel ongoing operations started in onStart()
Close file handles or network connections
Save any state that needs persistence

override suspend fun onStop() {
    showToast("Stopping...")
}

onUnload()

Called after onStop() completes. This is your last chance to clean up before the plugin classloader is discarded. What to do here:

Unregister all screens
Unregister all toolbar actions
Unregister file openers
Unregister language server providers
Unregister language grammars
Cancel all coroutines
Unsubscribe from all event bus subscriptions

override suspend fun onUnload() {
    screens.unregister(ScreenId("myext.main"))
    toolbar.unregister("myext.action")
    busSubscription?.cancel()
    fileOpenerRegistration?.unregister()
}

If you do not unregister screens and toolbar actions in onUnload(), they will leak. Klyx automatically cleans up registrations when a plugin crashes, but you should still unregister explicitly for a clean shutdown.

Coroutine scopes

Your plugin has two coroutine scopes available:

pluginScope — Created when the plugin loads and cancelled when it unloads. Use this for background tasks that should persist across start/stop cycles.
currentLifecycleOwner().lifecycleScope — Tied to the started/stopped lifecycle state. Coroutines are cancelled when the plugin stops.

Both scopes carry a PluginContextElement, so coroutines launched on them can access currentPluginContext() and currentLifecycleOwner().

override suspend fun onLoad() {
    // Tied to plugin load/unload lifecycle
    pluginScope.launch {
        // This runs even when the plugin is stopped
    }

    val owner = currentLifecycleOwner()
    // Tied to start/stop lifecycle
    owner.lifecycleScope.launch {
        // This is cancelled when onStop() is called
    }
}

Crash handling

If a plugin throws an unhandled exception during any lifecycle method, Klyx marks the plugin as crashed. The plugin’s scope is cancelled, its lifecycle is destroyed, and all its screen and toolbar registrations are automatically removed. A crash file is persisted so the plugin can be disabled on next startup if needed. You can check if a plugin has crashed via the crash(t: Throwable) method on the internal PluginRuntime.

Getting Started

Extensions

API Reference

Lifecycle overview

onLoad()

onStart()

onStop()

onUnload()

Coroutine scopes

Crash handling

​Lifecycle overview

​onLoad()

​onStart()

​onStop()

​onUnload()

​Coroutine scopes

​Crash handling

Lifecycle overview

onLoad()

onStart()

onStop()

onUnload()

Coroutine scopes

Crash handling