Plugins du shell

Le bureau Omarchy fonctionne au sein d’un unique processus Quickshell de longue durée nommé omarchy-shell, et presque tout ce que vous voyez à l’écran est un plugin qui s’exécute en son sein. La barre est un plugin. Il en va de même pour les panneaux qui se déroulent depuis celle-ci, les superpositions en plein écran comme le sélecteur d’emojis et le gestionnaire du presse-papiers, le menu Omarchy lui-même, l’écran de verrouillage, la boîte de dialogue polkit et les services sans interface qui surveillent votre batterie et réchauffent les couleurs de votre écran la nuit.

Ce n’est pas un simple détail d’implémentation. Cela signifie que vous pouvez désactiver certaines parties du bureau, les remplacer ou créer les vôtres sans modifier une seule ligne du code source d’Omarchy.

Les plugins officiels sont fournis avec Omarchy et se trouvent dans $OMARCHY_PATH/shell/plugins/. Tout ce que vous ajoutez vous-même — vos propres expérimentations ou quelque chose que vous avez trouvé sur GitHub — se trouve dans ~/.config/omarchy/plugins/. Les deux sont détectés de la même manière au démarrage ; la seule différence est leur emplacement sur le disque.

Voir les plugins disponibles #

omarchy plugin list

Cette commande affiche tous les plugins détectés avec leur identifiant, leur état d’activation, leur origine officielle ou tierce, leurs types et leur nom d’affichage. Ajoutez --json si vous transmettez le résultat à un autre outil.

Les identifiants des plugins utilisent des espaces de noms. Ceux des plugins intégrés commencent tous par omarchy. — omarchy.clock, omarchy.network, omarchy.notifications — et cet espace de noms est réservé, de sorte qu’aucun plugin tiers ne peut se l’approprier.

Les activer et les désactiver #

omarchy plugin enable omarchy.tailscale
omarchy plugin disable omarchy.weather

Vous pouvez également passer par le menu : Configuration > Plugins propose les options Activer, Désactiver, Ajouter, Cloner et Supprimer, chacune avec un sélecteur qui ne présente que les plugins pertinents pour l’action concernée.

L’état d’activation est enregistré dans ~/.config/omarchy/shell.json, et la règle diffère légèrement selon les deux catégories de plugins. Un plugin tiers est activé dès lors que son identifiant apparaît quelque part dans ce fichier — comme élément de la disposition de la barre, comme entrée dans plugins[] ou comme bar.id. Pour les plugins officiels qui ne sont pas des widgets de barre, c’est l’inverse : ils sont activés par défaut et ne sont désactivés que s’ils figurent dans disabledPlugins[].

Un plugin de barre complète ne peut pas être désactivé. Il y a toujours exactement une barre : pour la remplacer, il suffit donc d’en activer une autre. Le positionnement des widgets de la barre est expliqué dans la section consacrée à la barre supérieure.

Ajouter un plugin depuis Git #

Un plugin tiers est simplement un dépôt Git contenant un fichier manifest.json à sa racine.

omarchy plugin add https://github.com/acme/omarchy-weather.git --enable

Avant toute opération, la commande vous indique clairement que les plugins exécutent du code arbitraire, sans environnement isolé, au sein de votre processus shell de longue durée. Elle affiche l’URL et vous demande de confirmer. Prenez cet avertissement au sérieux. Un plugin n’est pas un fichier de configuration : c’est du code qui s’exécute pendant toute la durée de votre session, avec un accès à tout ce que votre compte utilisateur peut atteindre. N’ajoutez que des dépôts dont vous acceptez d’exécuter le code et examinez-les avant de les activer.

La commande clone ensuite le dépôt dans un répertoire temporaire, valide le manifeste, refuse l’installation si un autre plugin utilise déjà cet identifiant, puis le déplace vers ~/.config/omarchy/plugins/<id>/. Sans --enable, elle vous demande si vous souhaitez l’activer immédiatement ; vous pouvez répondre non et commencer par lire le code. Elle n’exécute jamais rien provenant du plugin, ne lance aucun script d’installation et ne demande jamais les droits sudo : elle clone les fichiers, vérifie le manifeste et modifie un état via IPC.

La mise à jour consiste à effectuer une récupération en avance rapide dans ce même répertoire de travail :

omarchy plugin update acme.weather
omarchy plugin update

Sans identifiant, la commande met à jour tous vos plugins gérés par Git. Elle vous présente les différences avant de les appliquer, refuse la mise à jour si des modifications locales empêchent une avance rapide et revient à la révision précédente si la nouvelle échoue à la validation.

omarchy plugin remove acme.weather

La suppression commence par désactiver le plugin, puis l’efface s’il s’agit d’un dépôt Git cloné (le dépôt reste disponible en amont) ou supprime son lien s’il s’agit d’un lien symbolique. Un dossier de plugin créé manuellement et ne contenant aucun dépôt Git est déplacé vers une sauvegarde horodatée dans le répertoire des plugins au lieu d’être définitivement supprimé.

Cloner un plugin intégré pour le modifier #

C’est ce que je préfère. Si vous souhaitez modifier le comportement d’un widget intégré, ne modifiez pas les fichiers situés sous $OMARCHY_PATH : ils appartiennent au paquet et seront écrasés lors de la prochaine mise à jour. Clonez plutôt le plugin :

omarchy plugin clone omarchy.clock

Cette commande copie l’intégralité du plugin dans ~/.config/omarchy/plugins/dhh.clock (avec votre nom d’utilisateur, pas le mien), le renomme « Mon horloge », l’active et fait passer le shell du plugin intégré à votre copie, tout en conservant la position et les réglages d’un éventuel widget déjà présent dans la barre. Ajoutez --edit pour ouvrir immédiatement le nouveau répertoire dans votre $EDITOR ; c’est ce que fait pour vous l’option Configuration > Plugins > Cloner un plugin du menu.

Le préfixe correspondant à votre nom d’utilisateur garantit que l’identifiant de votre clone vous appartient, afin qu’il n’entre pas en conflit avec celui de quelqu’un d’autre lorsque vous le partagez. Les appels adressés à l’identifiant du plugin intégré d’origine sont redirigés vers votre clone : tout ce qui faisait référence à omarchy.clock continue donc de fonctionner sans modification. Et si vous vous y perdez, omarchy plugin remove dhh.clock rétablit le plugin intégré.

L’enregistrement d’un fichier situé n’importe où sous ~/.config/omarchy/plugins/ recharge automatiquement le code du plugin. Vous pouvez donc laisser l’éditeur ouvert et voir vos modifications s’appliquer.

Créer votre propre plugin #

Un plugin est un répertoire contenant un fichier manifest.json et du code QML. Le manifeste déclare schemaVersion: 1, un id, un name, une version, un ou plusieurs kinds, ainsi qu’un objet entryPoints qui désigne le fichier QML correspondant à chaque type :

Type	Description
bar-widget	Un composant que la barre active peut placer dans une section
panel	Une fenêtre flottante permanente ou affichée à la demande
overlay	Une superposition en plein écran
menu	Une surface de menu affichée à la demande
service	Un singleton sans interface utilisateur
bar	Une barre complète qui remplace celle intégrée

Un plugin peut déclarer plusieurs types à la fois : le plugin multimédia est à la fois un service et un bar-widget. Les widgets de barre possèdent un bloc barWidget supplémentaire, avec un nom d’affichage, une catégorie, un champ facultatif defaultSection et allowMultiple, qui indique s’il est pertinent d’en placer plusieurs dans la barre. La plupart des widgets le définissent sur false ; les espaces et les indicateurs le définissent sur true.

Avant de publier quoi que ce soit, vérifiez-le :

omarchy plugin validate ./my-plugin

Cette commande effectue les mêmes vérifications que le shell lors du chargement : la version du schéma, les champs obligatoires, l’absence d’espace de noms réservé dans l’identifiant, des points d’entrée qui utilisent des chemins relatifs sûrs et qui existent réellement, un point d’entrée pour chaque type déclaré et l’absence de liens symboliques dans l’ensemble du dossier.

Pour une vue d’ensemble, le code source fait office de documentation : le fichier shell/README.md du dépôt Omarchy décrit le schéma du manifeste, le contrat IPC du shell et la structure exacte de shell.json, tandis que shell/plugins/README.md répertorie tous les plugins officiels avec leur identifiant, leurs types et leurs points d’entrée.

Partager votre plugin avec le monde entier #

Une fois que vous avez créé quelque chose qui vous plaît, placez-le dans un dépôt Git public. C’est tout le mécanisme de distribution : n’importe qui peut alors exécuter omarchy plugin add avec votre URL et le faire fonctionner en quelques secondes.

Pour aider les autres à le trouver, référencez-le sur omarchyplugins.com. Il s’agit du répertoire communautaire des plugins du shell Omarchy, et c’est le premier endroit où chercher lorsque vous vous demandez si quelqu’un a déjà créé le widget que vous vous apprêtez à développer. Parcourez-le avant de commencer !