Omahub
← All plugins
P

Shelfish

by Patrick Fanella

Organize Omarchy bar widgets into collapsible groups with an interface localized in ten languages.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
28b3a09
Scanned
3 weeks ago

No potentially dangerous behavior detected in the analyzed commit.

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
28b3a09
Reviewed
3 weeks ago

The plugin is a legitimate bar-widget organizer that manipulates the Omarchy shell configuration through the documented mutateShellConfig API. It contains no obfuscated code, network access, or destructive commands, and the deterministic scan found no issues. The main risk is that it relies on internal shell APIs and modifies user configuration, but this is clearly disclosed and within expected plugin behavior.

  • The plugin modifies the user's shell configuration file (~/.config/omarchy/shell.json) via mutateShellConfig, which could potentially disrupt the bar layout if bugs occur, though it provides a restoreAll command.
  • It depends on Quattro's internal moduleSlots API, which may change and cause unexpected behavior, but this is a compatibility risk rather than a security risk.
  • The plugin runs unsandboxed like all Omarchy plugins)Skip, but it does not perform any privileged operations or external process execution.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/PatrickFanella/omarchy-plugin-shelfish --enable
Widgets #bar #quickshell

Shelfish

Shelfish organizes existing Omarchy bar widgets into named, collapsible groups. It adds a settings button and one icon button per group while keeping each member widget's normal popup and interactions. Its interface is localized in ten languages.

Compatibility and dependencies

Shelfish targets Omarchy 4 with the Quattro shell. It uses the standard Omarchy bar plugin API and Quattro's internal shell.bar.moduleSlots API. Changes to that internal API may break group visibility management.

Shelfish has no third-party runtime dependencies.

Languages

Shelfish supports English, German, Spanish, French, Italian, Brazilian Portuguese, Dutch, Polish, Croatian, and Simplified Chinese. It detects the locale from the shell automatically and falls back to English when necessary.

Omarchy does not support localized plugin manifest fields. The plugin name, description, category, and advanced schema metadata therefore remain in English.

Install

omarchy plugin add https://github.com/patrickfanella/omarchy-plugin-shelfish.git --enable

Add the Shelfish bar widget through Omarchy's bar settings if it is not added automatically.

Set up and use groups

  1. Select the sliders icon to open Shelfish settings.
  2. Create or select a group.
  3. Set its name, icon, and direction.
  4. Add installed bar plugins from the available plugins list.
  5. Use Up and Down to order groups and members.

Select a group icon to reveal that group's widgets. Select it again to close the group. Right-click a group icon to open settings. Middle-click one to close all groups.

The available-plugin list also includes a Shelfish settings shortcut. Add it to any group to place a second settings icon beside that group. This shortcut opens the manager directly and does not toggle or reveal the group. The primary Shelfish settings icon remains a stable anchor and stays outside groups.

Shelfish can reveal a group when a member's watched status changes. Advanced status paths use plugin.id=path|nested.path;other.id=count. Shelfish also reads explicit shelfishStatus and legacy omatenderStatus properties. It does not infer status from unrelated widget internals. Per-widget policies can disable automatic reveal or override its duration.

Status snapshots accept only null, booleans, finite numbers, and strings. Shelfish limits path count and depth, truncates scalar strings, and caps each aggregate snapshot.

Layout changes

Shelfish stores its settings on its own bar layout entry. When configuration changes, it uses Omarchy's mutateShellConfig API to move each configured member beside the Shelfish entry. Groups follow manager order. Members follow their order inside each group. A right-facing group uses group icon, members; a left-facing group uses members, group icon.

Member entries, including duplicate instances, keep their complete configuration. Missing entries are skipped. A widget can belong to only one Shelfish group. The native omarchy.tray entry cannot be grouped.

Shelfish does not remember a member's original layout position.

Restore and remove

Restore removes every generated group entry and makes all managed widget instances visible. It does not restore their historical positions. Run restore immediately before removing the plugin:

omarchy-shell io.github.patrickfanella.shelfish restoreAll

Then immediately remove Shelfish:

omarchy plugin remove io.github.patrickfanella.shelfish

Permissions and security

Omarchy plugins run unsandboxed. Shelfish changes ~/.config/omarchy/shell.json only through Omarchy's mutateShellConfig API. It does not use the network, request elevated privileges, or start external processes.

Development and validation

Run all checks from the repository root:

tests/check-all.sh
omarchy plugin validate .
qmllint BarWidget.qml GroupButton.qml ManagePanel.qml Service.qml

The test script runs model, localization, and release metadata tests, then runs Omarchy validation when the CLI is installed. Standalone qmllint is not used because it cannot resolve all Quickshell runtime types; releases also receive a controlled live shell check.

Known limitations

  • Shelfish depends on Quattro's internal moduleSlots API.
  • It groups only installed bar plugins with live module slots.
  • It cannot restore pre-group layout positions.
  • Status discovery is polling-based with a 500 ms interval.

Shell API compatibility

Shelfish uses the host and window slot discovery provided by the Omarchy 4.0.3 compatibility implementation. When no usable slots or configuration are available, it keeps widgets visible, reads its saved groups, and displays an explicit compatibility message. Group editing and automatic layout writes are disabled only in that fallback state. Grouping resumes when host slot discovery succeeds.