> ## Documentation Index
> Fetch the complete documentation index at: https://klyx.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin Lifecycle

> Understanding the Klyx plugin lifecycle

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

## Lifecycle overview

```text theme={null}
Load → onLoad() → onStart() → (running) → onStop() → onUnload() → Unloaded
```

| Phase | Method       | Purpose                                       |
| ----- | ------------ | --------------------------------------------- |
| 1     | `onLoad()`   | Register resources, set up infrastructure     |
| 2     | `onStart()`  | Begin operations that depend on other plugins |
| 3     | onStop       | (Triggered 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`
* Subscribe to events on the event bus
* Register file openers
* Initialize lightweight state

```kotlin theme={null}
override suspend fun onLoad() {
    screens.register(this, Screen(ScreenId("myext.main")) { MainScreen() })
    toolbar.register(this, ToolbarAction(
        id = "myext.action",
        label = "My Action",
        category = ToolbarCategory("My Plugin"),
        priority = 100,
        onClick = { /* ... */ }
    ))
}
```

## 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:**

* Register file openers (if they depend on other plugins)
* Start coroutines for background work
* Access other plugin's registered resources

```kotlin theme={null}
override suspend fun onStart() {
    // Register a file opener for a custom type
    openers.register(object : FileOpener {
        override val id = "myext.opener"
        override val priority = 50
        override suspend fun open(request: FileOpenRequest): WorkspaceTab? {
            if (request.extension != "mp3") return null
            return WorkspaceTab.Custom(title = request.fileName) {
                AudioPlayer(request.uri)
            }
        }
    })
}
```

## 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
* Unregister file openers

```kotlin theme={null}
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
* Cancel all coroutines
* Unsubscribe from events

```kotlin theme={null}
override suspend fun onUnload() {
    screens.unregister(ScreenId("myext.main"))
    screens.unregister(ScreenId("myext.detail"))
    toolbar.unregister("myext.action")
    toolbar.unregister("myext.other_action")
    job?.cancel()
}
```

<Warning>
  If you don't unregister screens and toolbar actions in \`onUnload()', they will leak. Klyx does not automatically clean them up.
</Warning>

## Using the plugin scope

Your plugin has access to a `CoroutineScope` via `pluginScope` or `lifecycleOwner.lifecycleScope`. Coroutines launched on this scope are automatically cancelled when the plugin is unloaded.

```kotlin theme={null}
override suspend fun onLoad() {
    // This coroutine is tied to the plugin's lifecycle
    pluginScope.launch {
        // Background work
    }
}
```