Omahub
← All plugins
I

Screens

by IM0001GT

Snap-to-edge monitor layout with brightness, text size, HDR, VRR, hardware-aware profiles, optional bar dim, and workspace spreading with names, icons, and a configurable total

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
1138159
Scanned
2 days 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
1138159
Reviewed
2 days ago

The plugin is a legitimate monitor management tool that writes Hyprland config files and installs a companion workspace widget. It runs unsandboxed code and modifies system config on startup, but it backs up originals, provides a restore path, and does not appear to contain malicious or hidden behavior. The deterministic scan found no issues.

  • On first run, the service automatically runs `display-ctl claim` and `recover-internal`, which back up and take over `monitors.lua` and related config without an explicit user action beyond installing the plugin.
  • The plugin creates a symlink at `~/.local/bin/omarchy-brightness-display` that intercepts the system brightness command, though the wrapper only forwards to the real command after handling idle states.
  • It can modify `shell.json` and install a companion workspace plugin, which is a form of persistence, but this is documented and reversible.
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/IM0001GT/omarchy-screens --enable
Hardware #Hyprland #bar #quickshell

Screens

An Omarchy bar widget for arranging displays and setting how they look.

Click the two-tile mark for a panel that stays open. Displays are drawn at their real Hyprland size. Drag them and they snap flush — no overlapping tiles, no cursor-eating gaps. Stacking a screen above or below another also gets a light center snap, easy to pull off if you want it offset. Then set brightness, text size, resolution, refresh, HDR, VRR, scale, rotation, and mirroring. Save the desk as a named profile; Screens can restore it when a display is plugged in.

<p align="center"> <img width="960" alt="Screens" src="preview.png" /> </p>
Layout This screen Night Light HDR Profiles Workspaces Pixel Care
Drag tiles; edges snap, neighbours reflow. Apply, then 20s Keep / Revert Brightness (optional all-monitors), text size, resolution, Hz, scale slider, rotation, mirror, Detect 1500K–6500K Kelvin slider and on/off, same hyprsunset temps as Omarchy 8-bit or 10-bit PQ on HDR panels, Tune for black / peak Name a desk; restore on connect Optional spread; Assign menu for count (default 10, up to 99, 10-per-screen preset) and per-screen pins Optional 0–100% bar dim, hover lift, no black veil

Works with two screens or a full battlestation. A fallback Hyprland rule still catches anything you hot-plug later. The panel scrolls when it is taller than the screen, so controls stay reachable at large scale (for example 2× on 1080p).

Stock Display can stay on the bar if you want it. Screens uses a different icon on purpose.

Why this exists

Omarchy's Display widget does brightness, text size, and scale. It does not arrange monitors or expose HDMI 2.1 features.

Other listed tools cover adjacent jobs:

  • Stock Display — backlight, font size, scale presets, enable/disable
  • hyprmoncfg — named profiles and a hotplug daemon. If it is still managing Hyprland, Screens waits and offers a choice: keep the plugin and run hyprmoncfg unmanage, or remove crmne.hyprmoncfg. Screens will not do either until you pick. An unmanaged leftover is not treated as in control.
  • HyprMod — GTK settings app. If it still has per-display monitor rules, those load after monitors.lua and win. Screens warns until you open HyprMod, click the trash can next to each managed display, and save; it will not delete HyprMod's rules for you
  • Generic layout editors — often reuse the stock monitor glyph, skip snap, and leave HDR/VRR in monitors.lua

Screens keeps the editor in the bar, follows the theme, and writes Hyprland Lua only after you act. No AUR package. No extra daemon.

Install

Plugins run as unsandboxed code inside omarchy-shell. Only add repos you trust.

omarchy plugin add https://github.com/IM0001GT/omarchy-screens --enable

That places the plugin in ~/.config/omarchy/plugins/im0001gt.screens/ and can drop the widget on the right side of the bar, next to Display.

The first time Screens runs, it copies every stock file it may change into ~/.local/state/im0001gt.screens/originals/ (and a copy of monitors.lua at original-monitors.lua). Those copies are never overwritten, live outside the plugin directory, and do not depend on a system snapshot. It then starts from a fresh Screens-owned monitors.lua taken from the live Hyprland layout, so leftover edits from hyprmoncfg or another layout tool cannot keep controlling the desk.

If hyprmoncfg is still managing displays, the Screens panel offers Keep unmanaged (hyprmoncfg unmanage, plugin can stay) or Remove hyprmoncfg (unmanage, then omarchy plugin remove crmne.hyprmoncfg). Screens does not do either until you click. If hyprmoncfg is already unmanaged, Screens takes over and only reminds you the plugin is still on the bar until you keep or remove it. The AUR package is left unless you drop it yourself.

If HyprMod is managing displays, its hyprland-gui.lua (or .conf) rules load after Screens and keep winning. Open HyprMod, click the trash can next to each monitor, and save. You can keep HyprMod for other settings. Screens does not remove those rules.

Use

Layout

  • Click the two-tile icon — the panel stays open until you click away
  • Drag a tile — edges snap so the cursor never falls in a gap. Dropping a screen above or below another also snaps to horizontal center if you are close; keep dragging to park it off-center
  • Find — badge on the selected output (not only the screen that holds the menu)
  • Detect — rescan Hyprland and DRM for a plugged-in screen that is currently off, then Turn on. If it is listed but stays blank, restart Hyprland or the machine
  • Enable this Display turns a screen off. On a non-primary GPU that can leave the panel blank until Hyprland or a reboot; Detect still finds it
  • Make primary chooses which screen the panel prefers when it opens

This screen

  • Pick a screen, then set brightness, night light, text size, resolution, refresh, scale, orientation, or mirror. Scale is per output (slider to 0.01, including 1.33×). Text size is remembered per display; Omarchy only has one desk font, so Apply uses that display's value
  • Layout, HDR, scale, and text size stay in the panel until Apply. Undo throws the draft away. Apply previews on the displays with a 20 second Keep / Revert. Closing the panel without Keep undoes or reverts
  • Super+/ and Super+Alt+/ step the focused display's scale when those keys still belong to stock Display scaling. If you already bound them to something else, Screens asks before taking them (or offers Super+Ctrl+/ instead)
  • Brightness follows the selected output (internal backlight or DDC). It hides when that output has no backlight. With two or more screens on, All monitors sets the same percentage on every connected display. A short label (Night owl, Golden hour, and so on) shows in the panel header while you drag the slider
  • Night Light sits under brightness: on/off plus a 1500K–6500K slider. It uses the same hyprsunset temperatures as omarchy toggle nightlight (4000K on, 6500K off) and refreshes the bar indicator
  • Text size uses Omarchy's 9–20 px stops and applies to the shell, GTK, and terminals
  • Laptop built-in panels are written as eDP-1 / LVDS / DSI so Omarchy's clamshell helper keeps your scale instead of forcing 2. Turning the laptop panel off uses Omarchy's overlay toggle, not a named disabled = true in monitors.lua, so unplugging the last external display brings the built-in panel back
  • Sleep and DPMS can make Hyprland invent a FALLBACK output (1080p @ 60). Screens does not write that into monitors.lua. A display you already applied stays in the file, so it comes back at that mode and scale instead of preferred
  • Labels use Hyprland's model string

HDR and VRR

  • HDR: Off, Auto, or Always. Auto keeps the desktop in SDR (no sdr_max_luminance / Display P3 metadata that makes Chromium and Electron look washed out) and only switches to HDR for fullscreen games and video (cm_auto_hdr). Always leaves PQ on all the time and can wash out HDR-ready LCDs
  • Tune (Auto or Always): 8-bit or 10-bit (Hyprland's real output depths), nine colour presets, wide-colour EDID override, SDR brightness/saturation/transfer, black floor, and SDR peak. Live scanout format is shown, not invented bit depths
  • Color space Display uses this panel's EDID primaries. Wide is BT.2020. HDR-ready LCDs that are not full wide-gamut should stay on Display
  • HDR and VRR disable themselves when that panel cannot do them
  • VRR modes: Off, Always, Fullscreen, Games & video. Always + HDR can flicker on some OLEDs; Fullscreen or Games & video is the usual workaround

Bar care

  • Pixel Care (under Detect / Find) dims bar widgets 0–100% without a black veil, so a transparent or themed bar keeps that look
  • Hover can lift the dim. Off until you turn it on

Workspaces

  • Spread workspaces pins workspaces across the screens that are on and not mirroring. Omarchy 4.0.3 no longer lets a plugin register a second bar widget at runtime, so Screens installs a companion plugin (im0001gt.screens.workspaces) next to this one. You still only add Screens; spreading swaps that companion onto the bar in place of stock Workspaces.
  • Default is still 10 workspaces. Assign (next to the spread toggle) opens the pinning UI so the main panel stays short until you need it
  • Total can go to 99. 10 per screen sets 10 on each enabled display (2 screens → 20). Omarchy’s Super+1–0 keys still jump 1–10; extras are on the bar, Super+Tab, and Super+wheel
  • Two screens at the default 10: primary gets 1–5, the next screen gets 6–10. More screens split the total as evenly as possible (leftover slots go to the first screens)
  • Make primary chooses which screen receives the first group
  • Each display's bar then shows only that screen's numbers. Left-click a number to go there. Right-click that same number to name it, pick an icon, or set Tile, Scroll, or Float. Those choices apply only to that workspace
  • If the active workspace has a name, it appears as a chip next to the numbers
  • Assign by monitor — tap a digit to pin that workspace to the screen. A workspace you leave unassigned still shows on the screen where it currently lives, dimmed. If the screen it was pinned to is unplugged, those numbers stay on the display Hyprland moved them to, dimmed, until that screen comes back. Assignment comes from Titanium-Mothy
  • Split evenly rebuilds the automatic split (primary first) and replaces a custom plan
  • Turning the toggle off restores Omarchy's stock workspace widget and leaves windows where they are. Shrinking the total moves windows off workspaces you no longer manage so they cannot stick around like a stray 11

Profiles

  • Save names the current layout. Click the profile name (or Apply) to write it. Two or more profiles become a dropdown
  • On connect reapplies a matching profile when a display is plugged in
  • Turning a display on, or turning Mirror off, restores the matching saved layout instead of leaving tiles stacked

Changes write ~/.config/hypr/monitors.lua after you drag, turn a display on, or save. Later applies keep a short rolling set of timestamped copies in ~/.local/state/im0001gt.screens/. Leftover rules from stock Omarchy, hyprmoncfg, or another editor are replaced after the original file is copied aside.

Move it with omarchy bar move im0001gt.screens.

Multi-GPU desks

If Hyprland is painting on one GPU and another panel is plugged into a second GPU, idle standby or Enable this Display off can leave that output blank until Hyprland or a reboot. Screens only Hyprland-DPMS the primary GPU on idle; any display on another GPU stays on but black. Detect can still find a disabled output. A one-time note appears the first time you open the panel.

Resolution lists come from Hyprland / the EDID. A DP-to-DVI adapter that only advertises 2560×1440@60 will only show that mode.

Update

omarchy plugin update im0001gt.screens --yes
omarchy restart shell

1.12.0 is the Omarchy 4.0.3 fix, plus two older holes. The shell no longer lets a third-party service call barWidgetRegistry.register(), so spreading workspaces now ships as a generated companion plugin instead of a runtime registration. Unplugging the last external display re-enables the laptop panel, even if Hyprland briefly reports zero outputs, without reloading Hyprland over and over (that was leaving USB-C DP dongles stuck in USB-only mode so the external never came back). Apply/Keep/Revert keeps the Screens panel open across layout remaps (including scale on another display) until you click outside it. HDR Auto no longer writes the luminance / Display P3 metadata that washed out Chromium and Electron. Pixel Care dims the bar layer window itself (Omarchy 4.0.3 no longer lets a plugin reach moduleSlots). Hover still lifts it. Night Light (Kelvin slider + on/off) and All monitors brightness come from sunshine144.

1.13.0 adds per-screen workspace pinning on top of the 1.12 fixes. HDR Off no longer writes a bare cm = "hdr" line. Dock/resume no longer leaves a stray workspace like 11. Apply/Keep sits in a sticky footer. Sliders ignore the wheel unless the pointer is on the track. Assign by monitor comes from Titanium-Mothy.

1.13.1 keeps the workspaces companion parent and destination directory descriptors open through rename and recursive cleanup, so a path swap between check and replace cannot redirect the delete.

1.14.0 stops Screens from corrupting other Omarchy menus while the panel is closed. Sliders are drag-only (click, then arrows / Home / End for a fine nudge) so scrolling the panel cannot grab them. Workspace spreading can go past 1–10 (default still 10, cap 99, 10 per screen preset); extra IDs show on the bar, Super+Tab, and Super+wheel. Omarchy’s Super+1–0 keys still jump 1–10. Pinning and the count sit behind Assign next to Spread workspaces. Long profile names elide instead of clipping Save / Delete / On connect. First-install backup/restore covers workspace-layout files 1–99. Workspace count past 1–10 comes from joewinke.

1.15.0 keeps a saved display mode across sleep. Hyprland’s FALLBACK placeholder is not written into monitors.lua, and an external rule you already applied stays there while that panel is in DPMS. Spread workspaces still shows numbers on the laptop after you undock: pins for a monitor that is gone are treated as unassigned until it returns, and a sync while undocked does not throw those pins away. Monitor names drawn from Hyprland / EDID are plain text. Thanks to lixenstrand and BVisagie for the reports.

1.15.1 checks a saved display’s scale, position, mode, and HDR fields before they are written into monitors.lua, so a tampered state file cannot add Lua. The workspace bar keeps its buttons while the list of workspaces is unchanged, instead of rebuilding them on every Hyprland update. Thanks to AlienWithGlasses for the crash report.

1.15.2 keeps the text size you confirmed with Keep when more than one bar is running. If you Apply and do not Keep, HDR, color, text size, and the other fields go back to their previous setting instead of staying on the preview after the picture reverts. Thanks to Dielerorn for the report.

Uninstall

Restore the pre-Screens files first, then remove the plugin:

~/.config/omarchy/plugins/im0001gt.screens/scripts/display-ctl restore-original
omarchy plugin remove im0001gt.screens

That puts back monitors.lua, bindings.lua, shell.json, and any workspace-layout files Screens captured (including IDs above 10), then removes the scale-key block, the brightness wrapper Screens added, and the generated im0001gt.screens.workspaces companion plugin.

Omarchy does not run an uninstall hook. If the plugin is already gone, the same restore still works from the first-install copy (it survives plugin remove and is independent of Timeshift or other system snapshots):

~/.local/state/im0001gt.screens/restore.sh

Profiles stay in ~/.local/state/im0001gt.screens/ until you delete that directory.

Security and data

Plugins run as unsandboxed code inside omarchy-shell. Screens does not use the network at runtime, does not ship binaries, and does not request extra privileges. It writes only files under your home directory:

  • ~/.config/hypr/monitors.lua — layout, scale, HDR, VRR
  • ~/.config/hypr/bindings.lua — Super+/ and Super+Alt+/ scale keys
  • ~/.config/omarchy/shell.json — only if you turn on workspace spreading, to swap the workspace widget
  • ~/.local/state/omarchy/workspace-layouts/ — Tile / Scroll / Float per workspace (1–99 when you raise the total)
  • ~/.local/state/im0001gt.screens/ — profiles, backups, Pixel Care settings (bar-care.json), workspace assignment (workspaces.json), and the restore helper

Requirements

  • Omarchy with the shell plugin CLI (omarchy plugin add)
  • Hyprland 0.55+ Lua monitor config (hl.monitor)
  • python3 and jq (already on Omarchy)

Hyprland HDR is PQ (cm = hdr or hdredid) at 8-bit or 10-bit. There is no HLG preset. Some capture tools do not like 10-bit.

Layout

manifest.json            Omarchy plugin manifest (must live at repo root)
Screens.qml              Bar icon + click panel
ScreenMark.qml           Two-tile bar/hero mark
Workspaces.qml           Per-display workspace numbers (right-click layout)
WorkspaceLayoutMenu.qml  Name, icon, Tile / Scroll / Float picker
Service.qml              Headless helper: Pixel Care, Apply/Revert, companion workspaces plugin
Model.js                 Snap / normalize / workspace split helpers
scripts/display-ctl      hyprctl snapshot, monitors.lua writer, hyprmoncfg / HyprMod check, scale keys
preview.png              Marketplace still

The repo root is the plugin. That is what omarchy plugin add and omarchy plugin validate expect.

Credits

Night Light (Kelvin slider and on/off) and All monitors brightness were contributed by sunshine144.

Assign by monitor (tap digits onto each screen, Split evenly, unassigned digits stay dimmed on the bar) was contributed by Titanium-Mothy.

Workspace count past 1–10 (total slider, 10-per-screen, IDs that still render above 10) was contributed by joewinke.

License

MIT. See LICENSE.