Skip to content


Repository files navigation

A user-friendly API for KDE's KRunner application.


  • Create KRunner plugins ("runners")
    • Type safe
    • Null safe
    • Named parameters
    • Documentation explaining the various parts


Creating plugins

import 'package:krunner/krunner.dart';

Future<void> main() async {
  /// Create a runner instance.
  final runner = KRunnerPlugin(
    identifier: 'com.example.plugin_name',
    name: '/plugin_name',
    matchQuery: (String query) async {
      /// If the KRunner query matches exactly `hello` we return a match.
      if (query == 'hello') {
        return [
            id: 'uniqueMatchId',
            title: 'This is presented to the user',
            icon: 'checkmark',
            rating: QueryMatchRating.exact,
            relevance: 1.0,
            properties: QueryMatchProperties(subtitle: 'Subtitle for match'),
      } else {
        return []; // Empty response (no matches).
    retrieveActions: () async => [
        id: 'uniqueActionId',
        text: 'hoverText',
        icon: 'addressbook-details',
    runAction: ({required String actionId, required String matchId}) async {
      if (actionId == 'uniqueActionId') {
        print('User clicked secondary action!');

  /// Start the runner.
  await runner.init();

Refer to the example directory for a complete example, including instructions for debugging and installing plugins.

For a real-world example of a plugin made with this API see VSCode Runner.

Additional Information

API Documentation