Talk to your desktop.

Use the local control socket, write a Quickshell component, or build an opt-in native effect. Each interface has a different scope and trust boundary.

Start with ludashctl

Applications launched inside LunaDash inherit LUDASH_CONTROL. For an external terminal, point it at your running session's socket. The default session name is ludash-0; substitute the name passed to --socket.

export LUDASH_CONTROL="$XDG_RUNTIME_DIR/ludash-test-control"
./build/ludashctl status
./build/ludashctl appearance '{"gap":16,"animations":true}'
./build/ludashctl open-settings modules

Send one UTF-8 JSON object followed by a newline. method and value are strings; JSON-valued settings are encoded inside value. Numeric IDs are also sent as strings.

{"method":"appearance","value":"{\"gap\":16}"}

A successful call generally returns an updated state object. Failure returns {"error":"message"}; the CLI exits nonzero. Audio and power helpers run asynchronously, so acceptance is not completion—poll status for busy/error fields. Requests are limited to 64 KiB with a three-second server deadline; a client should also bound response size and time.

import json, os, socket

request = {
    "method": "appearance",
    "value": json.dumps({"accent": "#c4b5fd", "gap": 16})
}
with socket.socket(socket.AF_UNIX) as client:
    client.settimeout(3)
    client.connect(os.environ["LUDASH_CONTROL"])
    client.sendall(json.dumps(request).encode() + b"\n")
    data = b""
    while b"\n" not in data:
        chunk = client.recv(65536)
        if not chunk or len(data) + len(chunk) > 1024 * 1024:
            raise RuntimeError("Invalid LunaDash response")
        data += chunk
    response = json.loads(data)
    if "error" in response:
        raise RuntimeError(response["error"])
    print(response["appearance"])

Control methods

A small QML interface

Each custom component receives shell, resolved style, and moduleId. Read shell.state as a snapshot and use commands for changes. The host manages the window, dimensions, animation and fallback content.

shell.launch("terminal")
shell.launch("files")
shell.command("workspace", 1)
shell.setAppearance({ blur: true, blurRadius: 18 })
shell.settingsOpen = true
const title = shell.focusedTitle
const label = shell.tr("Settings")

The component guide includes a complete Item template, JSON styles and recovery steps. Custom QML can execute processes and access files; metadata does not isolate it.

Native effect plugins · API 1

Native plugins use the LuDash::CompositorPlugin interface. Implement windowOpened(QQuickItem*) and windowFocused(QQuickItem*) in a QObject subclass, declare Q_INTERFACES, and embed metadata with Q_PLUGIN_METADATA.

{
  "KPlugin": {
    "Id": "org.example.effect",
    "Name": "Example effect",
    "Version": "1.0.0",
    "License": "GPL-3.0-only",
    "EnabledByDefault": false
  },
  "LuDash": {
    "ApiVersion": 1,
    "Type": "WindowEffect",
    "Library": "libexample-effect.so"
  }
}

#include <QObject>
#include <LuDash/plugins/CompositorPlugin.h>

namespace LuDash {
class ExampleEffect final : public QObject, public CompositorPlugin {
    Q_OBJECT
    Q_PLUGIN_METADATA(IID LUDASH_COMPOSITOR_PLUGIN_IID FILE "metadata.json")
    Q_INTERFACES(LuDash::CompositorPlugin)
public:
    void windowOpened(QQuickItem* frame) override;
    void windowFocused(QQuickItem* frame) override;
};
}

Put implementations in a matching .cpp file and build a CMake MODULE library linked to Qt Quick. Store the library and metadata together in ~/.local/share/ludash/plugins/<id>/, enable it in Plugins, then restart the compositor. Keep retained window references in QPointer and never access a destroyed frame.

The repository contains a complete fade effect implementation, its header, and packaging instructions.