Skip to main content
A plugin is a small widget you place on your desktop: a stock ticker on the wallpaper, a photo beside the clock, a panel that melts out of the screen edge on hover. The author writes the logic and one view; Ryoku owns where it lives, how it looks, how it moves, and how it sizes. That split is the whole point, a plugin always looks and behaves like a native part of the shell, because the shell draws the surface around it.
Plugins are widgets, not applications. To install real software (game launchers, dev stacks, security tools), use Extras bundles, a separate system.

​
The three hosts

When you enable a plugin you pick one host for it. The same widget can run in any of them; Ryoku just renders it differently.
A tile on the wallpaper, next to the clock and calendar, with the same machinery they have:
  • Left-drag to move it (snaps to a grid).
  • Right-click for its menu: Lock to freeze it in place, Hide to turn it off.
  • Drag the bottom-right corner to resize, live, from 50% to 250%.
  • It rides on a card (rounded, translucent, soft shadow) that matches the clock and calendar.
You arrange desktop widgets directly on the wallpaper, not from Settings.
Island and window hosts are planned but not built yet. Today a plugin declares desktopWidget, framePopout, topbarGlyph, or a mix.

​
Install, enable, place

1

Install from the Store

Press Mod + , for Ryoku Settings and open Store (under Add-ons). It opens on a grid of plugin cards with live previews; open one and choose Install. The source downloads to ~/.local/share/ryoku/plugins/<id>/.
2

Enable it

Switch to Installed (also under Add-ons) and toggle the plugin Enabled.
3

Pick a host and place it

In the same panel choose the host. For a frame popout, set the edge and alignment there. A desktop widget appears on the wallpaper, where you drag, corner-resize, lock, or hide it directly.
Placement and settings persist to ~/.config/ryoku/plugins.json. The shell watches that file and retunes every surface live, no reload, no restart. Removing a plugin (from Installed) deletes its files but keeps your placement, so reinstalling drops it back where you had it.

​
Bar widgets from the community

The catalogue’s official plugins are only half the picture. Anyone can write a bar widget and share it, and the ones you add yourself live in **QS Bar Settings
Community**. Open that panel from the bar’s logo, from Mod + Escape then QS Bar, or with:
Community lists each plugin you added, with its author, a switch, its own settings, and EXPORT, SHARE TO RYOSTORE, and REMOVE buttons. It opens on a warning that applies to all of them:
Community plugin. Ryoku does not review or maintain it: it runs inside your shell with your permissions, so inspect its code before you trust it.
To add one, paste a git URL or a local folder into the panel’s ADD field, or run:
Either way Ryoku validates the plugin, installs it through the Store’s transaction (a receipt and a content-hashed copy), places it on the bar, and the shell picks it up within seconds, no restart. Remove it with the REMOVE button or:

​
Share a widget you made

Made something worth passing on? Turn an installed plugin into a shareable folder with:
That writes ~/Documents/ryoku-plugins/<id>/ (or ~/ryoku-plugins/<id> if you have no Documents directory) and puts it under git. Inside are the plugin’s files plus two Ryostore descriptors: product-manifest.json (the per-file checksums the Store verifies against) and registry-entry.json (the catalogue entry, marked official: false). When you are ready to publish, run:
With the GitHub CLI (gh) logged in this opens a pull request against Ryostore; without it, it opens the submission form prefilled. A maintainer then reviews the entry before it appears in the catalogue.
Ryostore review is a listing review, whether the entry belongs in the catalogue and is described honestly, not a security audit. Nobody vets the code for you, which is why every community plugin keeps the warning above. Read the source before you install one.

​
Ask Rashin for one

You do not have to write a widget by hand. If Rashin is on, describe the bar widget you want and its agent builds it, installs it with ryoku plugin add, and drops it into Community for you to review. See Asking for a widget.

​
Example plugins

Ryoku ships two official plugins in the catalogue, both desktop widgets:

Market

Track any Yahoo Finance symbol, a crypto pair (BTC-USD), a stock (AAPL), or an index (^GSPC), with live price, change, and history in one of four faces: dossier, line, area, or minimal.

Photo Frame

Pin any photo to your wallpaper in a chosen style (rounded, square, polaroid, framed, or film) with a tunable drop shadow and colour filters. Ships with a sample photo so it looks right the moment you enable it.
Each plugin’s own options (Market’s symbol and face, Photo Frame’s style and filter) live in its settings, edited from Installed or the desktop widget’s right-click menu.

​
From a terminal

The Hub is the normal path, but the same actions have commands. Ids are the ones in the ryoku-extras plugin catalogue (market, photo-frame).
Community bar widgets have their own command family, ryoku plugin:

​
Write your own

Yes, Ryoku has a plugin SDK. A plugin is a folder with a manifest.json, a non-visual service/Main.qml (your logic and state), and one content/Widget.qml (your view), installed to ~/.local/share/ryoku/plugins/<id>/. Your view imports the Ryoku.PluginKit deck kit, so it picks up the shell’s colours, type, and motion automatically.
The golden rule: never set your own position, never draw your own window chrome, never assume your size. You report your content’s natural implicitWidth and implicitHeight; Ryoku sizes the card or grows the popout around it. Break this rule and your plugin looks bolted-on instead of native.
The full authoring guide, the manifest schema, the three densities (glyph, compact, full), and the settings schema live in the repo:

​
Make one

You do not start from a blank folder. One command scaffolds a complete, working plugin in the right place:
That writes ~/Documents/ryoku-plugins/my-widget/ with a template you can run as is: the manifest, the logic, the view, a bar panel, a README, a LICENSE, and a first git commit. --bar makes a bar widget (the default); --desktop or --popout start a desktop tile or a frame popout instead.
1

Scaffold it

ryoku plugin new <id> creates the folder and fills it with a template that already validates and runs.
2

Edit it

Change the logic, the view, and (for a bar widget) the panel; write the README; drop in a real preview image. The template shows where each piece goes.
3

Check it

ryoku plugin validate <dir> runs the safety checks and tells you, line by line, anything to fix.
4

Install it

ryoku plugin add <dir> --bar --yes puts it on your bar. The shell picks it up within seconds, no restart.
5

Verify and (only then) share

Find it on the bar and under QS Bar Settings > Community. When you want to publish it, and only then, ryoku plugin share <id> opens the Ryostore pull request.

​
The rules

A plugin runs inside your shell with your permissions, so a good one plays by a few plain rules. ryoku plugin validate checks the ones it can, and Ryostore runs the same check on anything submitted:
  • Stay in your folder. A plugin is one folder named after its id; it never writes into the shell’s own config or the store’s install folder.
  • Ship the standard pieces. A manifest, the logic, one view, an optional bar panel, a README, a LICENSE, and a real preview image. Scripts live in bin/.
  • Import only the kit. Views use Ryoku’s PluginKit and Qt, never the shell’s private internals, so a shell update never breaks them.
  • Settings go through the manifest. You declare them; the shell draws and saves them. A plugin never edits the shell’s settings files by hand.
  • Be honest about programs. Every command a plugin runs is shipped with it or listed in the manifest. No sudo; anything that needs a password uses the system prompt (pkexec), only on a click you make, and says so in the README.
  • Be honest about the network. Every server a plugin talks to is listed in the manifest. Nothing downloads and runs more code.
  • Write only your own scratch space. A plugin writes to its own state and cache folders, never to your ~/.ssh, your system files, or another plugin.
  • No hidden code. No secrets in the files, no compiled binaries, no symlinks; just readable scripts and QML.
  • Tell the truth. A community plugin is marked community, names its author, and its README says what it runs, reads, writes, and asks for.
The full rule list, with the exact wording the validator uses, is in the authoring guide.

​
A bar panel

A bar widget is more than a mark. Its glyph on the bar shows a glance of state; click it and a panel opens beneath it, in the same surface the shell’s own panels use, closing on Escape or an outside click. The widget declares one extra view and a width, and Ryoku draws and sizes the panel for it, capped to your screen. Clicking the bar only ever opens the panel; it never changes anything on its own. The actions live inside the panel, behind buttons you press. The VPN plugin in Ryostore is the worked example: its glyph shows whether a VPN is up, and its panel holds the switch, the connection details, and an AUTHORISE button that asks for your password once.

​
See also

Extras

Software bundles, the other half of how Ryoku grows beyond its core.

Ryoku Settings

The Store and Installed panels, and everything else the Hub tunes.
Last modified on September 2, 2026