LUDASH / MODULES

Your shell, one block at a time.

Resize a panel, change its corners, move it to the bottom—or replace a specific component with your own QML. Start with JSON, then add code when you need it.

Replace a feature, keep your desktop

Plugin SDK 2 separates a plugin's implementation type from its target: native C/C++ hooks, Quickshell components and OpenGL shaders can extend supported desktop features. Choose Built-in and plugin or Plugin only, with categorized settings and an advanced JSON editor. Changes reload live between hook calls, without rebooting or logging out.

Installed SDK 2 packages appear under Settings → Plugins. The registered target determines where a plugin attaches; the target registry also controls which implementation types are accepted and whether one or multiple plugins can be enabled.

CREATE A PLUGIN

lunadash-create-plugin --list
lunadash-create-plugin --type quickshell --target panel --id org.example.panel --output my-panel
cmake -S my-panel -B my-panel/build -DCMAKE_INSTALL_PREFIX="$HOME/.local"
cmake --build my-panel/build
cmake --install my-panel/build

Every new plugin uses metadata and the LunaDash CMake SDK. OpenGL packages retain their .vert/.frag sources and include compiled shader assets; software rendering retains the built-in visual. Native plugins run inside the compositor and must be trusted. Start with the website Plugin SDK guide, then use the repository's SDK reference and target contracts.

Nine independent blocks

panel, wallpaper, launcher, overview, settings, setup, session, feedback and compatibility each have a style and an optional custom entrypoint. Settings, setup and feedback cannot be disabled, so recovery remains available.

The style contract

Field	Accepted values
`schemaVersion`	Exactly 1. Documents are limited to 16 KiB.
`enabled`	Boolean; recovery blocks cannot be disabled.
`width / height`	0 means built-in size. Width 320–3840 (settings minimum 800). Panel height 24–96; settings/setup 480–2160; other heights 80–2160. Sizes clamp to the screen.
`margin / radius`	Integers from 0 to 64 logical pixels.
`background / foreground / accent`	inherit, #RRGGBB, or Qt #AARRGGBB. Inherit follows the desktop palette.
`fontSize`	10–28. Applies to panel labels and is passed to custom components.
`edge`	top or bottom for panel; top for other blocks. Panel height and margins reserve tiling space.
`custom`	Boolean enabled plus relative entry, such as panel/Main.qml.

The JSON file lives in ~/.config/LuDash/shell-modules.json, respecting XDG_CONFIG_HOME. Invalid external edits retain the last valid document. Module colors affect the main built-in surface and direct labels; shared nested controls retain the desktop theme.

Make the component yours

In Shell modules, create a panel or dashboard template. Existing code is never overwritten.
Edit ~/.config/LuDash/modules/panel/Main.qml in your editor.
Set custom.entry to panel/Main.qml and custom.enabled to true in JSON.
Review the code and imports, then explicitly allow custom code in Settings.

MAIN.QML / MINIMAL COMPONENT

import QtQuick
Item {
    id: root
    required property var shell
    required property var style
    required property string moduleId
    Rectangle {
        anchors.fill: parent
        color: root.style.background
        radius: root.style.radius
    }
    Text {
        anchors.centerIn: parent
        text: root.shell.focusedTitle
        color: root.style.accent
        font.pixelSize: root.style.fontSize
    }
}

The root must be an Item with required shell, style and moduleId properties. Use anchors and layouts; the host owns the Wayland window, dimensions and animations. Do not create another PanelWindow or ShellRoot. The entrypoint must resolve inside the module directory, match module/Main.qml using letters, digits, underscores or hyphens, and be at most 256 KiB.

Entry file edits trigger reload. For helper files, use explicit QML type registration where needed and touch the entrypoint after editing a dependency. Read state as a snapshot; use shell.command() or shell.setAppearance() for changes.

Custom QML is executable, trusted code. It can access files, processes and the network with your user permissions. Syntax/load errors fall back to built-in content; runtime hangs, crashes or malicious code cannot be isolated inside the same shell process.

Always keep a way back

TERMINAL

ludashctl module-code-trust false
ludashctl module-reset
ludashctl open-settings modules

Reset restores built-ins, disables custom code and preserves your QML files. If the shell is hung, disable code through the compositor's IPC and restart the session. Offline, remove the modules/allowCustomCode setting and rename the module JSON before restarting.