The Quickshell Plugin Ecosystem: Community Plugins and Modular Structure

Summary: It explains how a Quickshell plugin is installed: each plugin consists of a metadata.json and a main QML file in its own directory, and Quickshell finds them at runtime with Instantiator and Loader and adds them to the panel. A faulty plugin stops only itself, not the entire desktop. The last section shows the security plugins I wrote for Omarchy as examples.

What truly makes a desktop shell powerful is not only the features offered by the core developers; it is a flexible plugin architecture that the community can easily contribute to. Omarchy Shell and Quickshell, thanks to their modular component structure, make plugin development child's play.

Thousands of community plugins are shared on the Omarchy Plugin Catalog (plugins.omarchy.org), and users can integrate them into their desktops with a single command.

1. Anatomy of a Quickshell Plugin

Each plugin consists of a manifest file (metadata.json) and a main QML file in its own independent directory:

~/.config/quickshell/plugins/badusb-shield/
├── metadata.json
├── Plugin.qml
└── assets/
    └── icon.svg

`metadata.json` Manifest Example

{
  "name": "BadUSB Shield",
  "id": "org.omarchy.badusb-shield",
  "version": "1.2.0",
  "author": "Ozan Özdil",
  "description": "USB veri yollarını anlık izleyen donanım güvenlik eklentisi",
  "entryPoint": "Plugin.qml",
  "category": "security"
}

2. Dynamic Loading of the Plugin

Quickshell uses Instantiator or Loader components to discover installed plugins at runtime and place them on the panel:

import QtQuick 2.15
import Quickshell 1.0

Row {
    spacing: 6
    
    Repeater {
        model: PluginManager.installedPlugins
        
        Loader {
            source: modelData.entryPointUrl
        }
    }
}

Even if an error occurs in the plugin code, thanks to Quickshell's isolation mechanism, the entire desktop does not crash; only the relevant plugin is stopped in safe mode.

3. Our Community Plugins

The cybersecurity and system tools we have brought to the Omarchy ecosystem (BadUSB Shield, CVE Radar, DNS Leak Guard, Ghost MAC, etc.) are among the most concrete examples of Quickshell's modular plugin architecture.

My reading

A plugin starts with two files: a manifest file and a QML component are enough.
Isolation protects the desktop: an error in one plugin stops only that plugin.
The catalog makes distribution easy: plugins can be installed from the Omarchy catalog with a single command.

Resources

plugins.omarchy.org