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:

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.

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 on GitHub is a complete reference implementation that demonstrates every API. Use it as a starting point and companion to these docs.