> ## 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.

# Extensions

> Overview of the Klyx extension system

Extensions let you add features to Klyx by bundling Kotlin/Compose code into plugins that Klyx loads at runtime. The extension system is built around a few core concepts.

## How it works

1. You write a Kotlin class implementing `KlyxPlugin`
2. You declare metadata in `plugin.json`
3. The Klyx Gradle plugin packages everything into a `.klyx` bundle
4. Klyx loads the bundle, reads the manifest, and instantiates your plugin
5. Your plugin registers screens, toolbar actions, file openers, etc.
6. Klyx manages your plugin's lifecycle automatically

## Bundle format

A `.klyx` file is a GZIP Tar archive containing:

```text theme={null}
MyExtension.klyx
├── plugin.apk        # Compiled extension APK
├── plugin.json       # Plugin descriptor
├── icon.png          # Optional plugin icon
├── readme.md         # Optional readme
├── changelog.md      # Optional changelog
└── ...               # Extra files
```

## Plugin lifecycle

Klyx calls four lifecycle methods on your `KlyxPlugin` implementation:

| Method       | When it's called                                                          |
| ------------ | ------------------------------------------------------------------------- |
| `onLoad()`   | Plugin is loaded into memory. Register screens, actions, subscribers here |
| `onStart()`  | All plugins are loaded. Safe to depend on other plugins                   |
| `onStop()`   | Plugin is about to be unloaded. Release start-time resources              |
| `onUnload()` | Final cleanup. Unregister everything you registered                       |

## Service injection

Klyx provides services through property delegates. Use `by plugin()` for app-wide services and `by runtime()` for per-plugin scoped services.

```kotlin theme={null}
private val screens: ScreenRegistry by plugin()
private val toolbar: ToolbarRegistry by plugin()
private val settings: Settings by plugin()
private val navigator: Navigator by plugin()
private val fileSystem: FileSystem by plugin()
private val info: PluginInfo by runtime()
```

## What plugins can do

* **Screens**: Register custom Compose screens navigable from within Klyx
* **Toolbar**: Add toolbar actions with icons in custom categories
* **File Openers**: Handle custom file types (e.g., `.mp3`, `.svg`)
* **Terminal**: Create and manage terminal sessions
* **Processes**: Run shell commands and programs
* **Events**: Subscribe to app events (file opens, terminal events)
* **Settings**: Read and update app settings
* **Language Servers**: Register LSP providers for custom languages
* **Theme**: Use Klyx's color system, typography, and fonts

## Reference implementation

The [SamplePlugin](https://github.com/klyx-dev/SamplePlugin) on GitHub is a complete reference implementation that demonstrates every API. Use it as a starting point and companion to these docs.