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, annotated with @PluginManifest
2. The Klyx Kotlin compiler plugin validates the annotation and generates a PluginDescriptor and plugin.json at compile time
3. The Klyx Gradle plugin packages everything into a .klyx bundle (a gzipped tarball)
4. Klyx loads the bundle, reads the generated plugin.json, and instantiates your plugin class
5. Your plugin registers screens, toolbar actions, file openers, and more during its lifecycle methods
6. Klyx manages your plugin lifecycle automatically (load, start, stop, unload)

Bundle format

A .klyx file is a gzipped tarball containing:

MyExtension.klyx
├── plugin.apk        -- Compiled extension APK
├── plugin.json       -- Generated plugin descriptor
├── icon.png          -- Optional plugin icon
├── readme.md         -- Optional readme
├── changelog.md      -- Optional changelog
└── ...               -- Extra files you configure

The plugin.json is generated for you by the @PluginManifest annotation and the compiler plugin, so you never hand-author or maintain this file.

Plugin lifecycle

Klyx calls four lifecycle methods on your KlyxPlugin implementation:

Method	When it is 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

See the lifecycle guide for details on each phase.

Service injection

Klyx provides services through property delegates. Use by plugin() for app-wide PluginService instances and by runtime() for per-plugin PluginRuntimeService instances.

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()

Within suspend functions or coroutines launched in the plugin scope, you can also use the currentPluginContext() and currentLifecycleOwner() functions to access runtime services without a delegate.

Registration with context receivers

Registration methods on ScreenRegistry, ToolbarRegistry, FileOpenerRegistry, LanguageServerRegistry, and LanguageRegistry use Kotlin context receivers. The KlyxPlugin instance is provided as a context parameter, so you do not pass it explicitly:

// Inside a KlyxPlugin method or another context-receiver function:
screens.register(Screen(ScreenId("myext.main")) { MainScreen() })
toolbar.register(ToolbarAction(id = "myext.action", label = "Action", onClick = { }) {})

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, .pdf)
• Terminal: Create and manage terminal sessions
• Processes: Run shell commands and programs with streaming output
• Events: Subscribe to app events (file opens, terminal events) and publish custom events
• Settings: Read and update app settings
• Language Servers: Register LSP providers for custom languages
• Language Grammars: Register tree-sitter syntax highlighting grammars for custom languages
• Theme: Use Klyx’s color system, typography, and fonts
• Diagnostics: Read device and editor capabilities

Reference implementation

A complete reference implementation demonstrating every API is available on the Klyx GitHub organization.