File Runners

Run files from the editor toolbar

Extensions can claim files for the editor’s Run button. When the user opens a file and hits Run, Klyx consults every registered FileRunner in descending priority order and delegates to the first runner whose supports returns true.

All runner types live in com.klyx.api.data.runner.

FileRunnerRegistry

Resolve the registry from a plugin as a service:

val runners: FileRunnerRegistry by plugin()
// or
val runners = context.service<FileRunnerRegistry>()

Method	Returns	Description
register(runner)	FileRunnerRegistration	Register a runner (context receiver provides the plugin)
unregister(id)		Remove a runner by its id
runnerFor(request)	FileRunner?	First runner that supports the request
supports(request)	Boolean	Whether any runner claims the file
runners()	List<FileRunner>	All runners, ordered by descending priority

Registering a runner whose id matches an existing one replaces the previous registration.

private var registration: FileRunnerRegistration? = null

override suspend fun onStart() {
    registration = runners.register(PythonRunner())
}

override suspend fun onStop() {
    registration?.unregister()
}

FileRunner

Implement this interface to handle a specific kind of file:

interface FileRunner {
    val id: String                    // Unique, reverse-DNS id (e.g. "com.example.python.runner")
    val priority: Int                 // Higher runs first. Defaults to 0.

    fun supports(request: FileRunRequest): Boolean

    suspend fun run(request: FileRunRequest, runner: FileRunnerContext)
}

Member	Description
id	Unique identifier. Recommended format: reverse-DNS
priority	Runners with a higher priority are consulted first. Defaults to 0
supports	Return true if this runner can execute the file. Called to decide whether to show the Run button, so keep it cheap and side-effect free
run	Execute the file using the provided FileRunnerContext

FileRunRequest

The request handed to every runner when the user hits Run:

data class FileRunRequest(
    val file: KxFile,
    val uri: Uri,
    val projectUri: Uri? = null,
    val tabId: String? = null,
)

Property	Description
file	The file being run
uri	The URI of the file being run
projectUri	The URI of the project the file belongs to, if any
tabId	The id of the active editor tab for this file, if any
extension	Lowercase file extension without the leading dot, or "" if none

The extension convenience property is the most common way to match a file:

override fun supports(request: FileRunRequest): Boolean =
    request.extension == "py"

FileRunnerContext

Runtime helpers handed to run. Use it to interact with the host:

Method	Returns	Description
runInTerminal(command, cwd?, sessionName?)		Open the terminal and run a shell command in a fresh session
openTerminal()		Navigate to the terminal screen without running a command
openScreen(screenId)		Navigate to a plugin-registered screen
openScreen(screenId, content)	ScreenRegistration	Register the composable for the id, navigate to it, and auto-unregister it when the screen is popped
openTab(tab)		Open a custom tab in the editor workspace

Running a command in the terminal

runInTerminal opens the terminal screen and executes the command directly — no login shell, prompt, or MOTD, only the command’s stdout/stderr and stdin:

override suspend fun run(request: FileRunRequest, runner: FileRunnerContext) {
    val path = request.uri.path ?: return
    runner.runInTerminal(
        command = "python3 \"$path\"",
        cwd = path.substringBeforeLast('/'),
        sessionName = "Python"
    )
}

These terminal helpers are only available inside a FileRunner. To run a command or open an interactive shell from anywhere else in your plugin (toolbar action, settings, lifecycle), use TerminalManager.runInTerminal(...) / TerminalManager.openTerminal() instead. See Terminal.

Opening a custom screen

Runners that preview a file can navigate to a screen registered via ScreenRegistry:

override suspend fun run(request: FileRunRequest, runner: FileRunnerContext) {
    runner.openScreen(ScreenId("com.example.html.preview"))
}

To open a screen directly with data — no pre-registration required — pass a composable. The closure captures whatever the screen needs, typically the file being run and its URI:

override suspend fun run(request: FileRunRequest, runner: FileRunnerContext) {
    runner.openScreen(ScreenId("com.example.html.preview")) {
        HtmlPreviewScreen(file = request.file, uri = request.uri)
    }
}

Screens opened this way are transient: the host auto-unregisters them when the screen is popped, so no cleanup is required. The returned ScreenRegistration lets you remove the screen earlier if needed.

Example

A Python runner registered during onLoad:

class PythonRunner : FileRunner {
    override val id = "com.example.python.runner"
    override val priority = 10

    override fun supports(request: FileRunRequest): Boolean =
        request.extension == "py"

    override suspend fun run(request: FileRunRequest, runner: FileRunnerContext) {
        val path = request.uri.path ?: return
        runner.runInTerminal(
            command = "python3 \"$path\"",
            cwd = path.substringBeforeLast('/'),
            sessionName = "Python"
        )
    }
}

// In the plugin:
private var registration: FileRunnerRegistration? = null

override suspend fun onLoad() {
    registration = runners.register(PythonRunner())
}

override suspend fun onUnload() {
    registration?.unregister()
}

Best practices

• Keep supports cheap: It runs on every file open to decide whether to show the Run button
• Register with a stable id: Re-registering with the same id replaces the runner
• Unregister on onUnload: Keep the FileRunnerRegistration and call unregister() to clean up
• Use runInTerminal for interpreters: It handles opening the terminal, running the command, and setting the working directory