Omahub
← All plugins
M

OmaDock

by matheusmedrado

A fast, terminal-inspired application dock for Omarchy Quattro.

GitHub

Security review

Review recommended · 5 findings

Deterministic scan — not a security guarantee

Medium
Risk level
Medium
Analyzed commit
e5f4175
Scanned
2 weeks ago

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
e5f4175
Reviewed
2 weeks ago

The plugin is a well-structured QML dock for Omarchy with no malicious behavior. The deterministic scan flagged the README's git clone example and CI workflow's apt-get/sudo usage, but these are documentation and CI-only, not part of the runtime plugin. The plugin only reads/writes a local config file and interacts with Hyprland through standard Quickshell APIs.

  • No obfuscated code, network requests, persistence mechanisms, or destructive commands found in the plugin source.
  • The deterministic scan's medium risk is driven by non-runtime files (README and CI workflow), which are not executed by the plugin.
  • The plugin writes to ~/.config/omadock/config.json, which is expected and user-controlled.
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/matheusmedrado/omadock --enable
Desktop #Hyprland #quickshell #launcher
<h1 align="center">OmaDock</h1> <p align="center"> A fast, terminal-inspired application dock for Omarchy Quattro. </p> <p align="center"> <img src="preview.png" alt="OmaDock sitting at the bottom of the Omarchy desktop" width="100%"> </p>

OmaDock is a native Quickshell overlay for Hyprland. It helps you launch, focus, and cycle through applications while staying out of the way when it is not needed. Think of it as a small graphical command strip—with fewer commands to remember.

The dock hides so your windows can shine. Mostly.

Every entry is a dot-matrix glyph beside a lowercase command label, over an ordered-dither texture. State is a brightness ladder: the application you are on is fully lit, a running one sits below it, and a pinned one that is not running stays dim.

In motion

Smart Hide keeps the dock out of the way until you reach for it, and the bar widget changes any of it live.

<p align="center"> <img src="display.gif" alt="OmaDock revealing on edge hover, switching modes, and reordering pins" width="100%"> </p>

Features

  • Smart Hide with edge reveal and Hyprland-aware window detection.
  • Independent behavior on each monitor.
  • Pinned applications and running, unpinned applications.
  • Launch, focus, multi-window cycling, and safe context-menu actions.
  • Drag reorder for pinned apps, including pinning eligible running apps.
  • A bar widget with a preferences panel for hiding, layout, and pointer actions.
  • A switch that turns the dock off without removing the plugin.
  • Dot-matrix glyphs resolved from the application, its name, its desktop entry categories, or -- for a web application, which declares none of those -- the address it opens.
  • Live Omarchy theme integration.
  • A JSON configuration file that survives updates and removal.
  • No daemon, polling loop, telemetry, network requests, or extra runtime.

OmaDock is not a replacement for the Omarchy bar, a standalone desktop shell, or a macOS dock cosplay contest.

Requirements

  • Omarchy Quattro
  • Hyprland
  • Quickshell 0.3.x
  • The official omarchy plugin command

The first release targets the Omarchy 4.0.1-1 / Quickshell 0.3.1 baseline.

Multi-monitor support is implemented — each monitor keeps its own hide state, and monitorMode selects all, focused, or a named list — but it has so far only been exercised on a single display. Reports from multi-monitor setups are welcome.

Installation

Omarchy plugin

The recommended installation method:

omarchy plugin add https://github.com/matheusmedrado/omadock.git --enable

Manual Git installation

For a regular local checkout:

git clone https://github.com/matheusmedrado/omadock.git \
  ~/.config/omarchy/plugins/io.github.matheusmedrado.omadock
omarchy-shell shell rescanPlugins
omarchy plugin enable io.github.matheusmedrado.omadock

OmaDock runs inside the existing Omarchy shell. It does not install a separate process or edit Hyprland configuration.

Usage

The dock sits at the bottom edge of each enabled monitor and uses Smart Hide by default:

  • Left click: launch, focus, or cycle an application's windows.
  • Middle click: launch a new instance.
  • Mouse wheel: cycle existing windows.
  • Right click: open actions such as pin, unpin, or close the active window.
  • Drag: reorder pinned apps, or drag a running app into the pinned region.
  • Drag out: pull a pinned app clear of the strip to unpin it. A running application stays in the dock as an unpinned entry until it exits.
  • Edge hover: reveal the dock when Smart Hide has tucked it away.

With Reserve space switched on, a revealed dock pushes windows up instead of covering them, and they flow back the moment it hides. Under Smart Hide that makes any tiled window count as a reason to hide, because releasing the space is exactly what would put a window back under the dock; floating windows are exempt, since an exclusive zone never moves them.

Activating a window on another workspace lets Hyprland handle the workspace change; OmaDock does not move the pointer for you.

The dock suspends itself on fullscreen workspaces by default, because games and videos deserve the whole screen—and all the pixels they can get.

Preferences

OmaDock ships a bar widget. Its icon is the dock's own dot-matrix glyph; click it to open a preferences panel covering hiding, layout, glyphs, and pointer actions. Middle-clicking the icon toggles between Smart Hide and never hiding, which is the setting worth reaching for without opening anything.

The first row of the panel is the dock itself. Switching it off leaves the plugin installed and the widget on the bar: the dock's surfaces go away, it stops tracking windows, and every other setting keeps its value for when it comes back. The bar icon dims while the dock is off, and middle-clicking it then switches the dock back on rather than changing the hide mode.

Add it to the bar from the Omarchy plugin UI, or from a terminal:

omarchy-shell shell putBarWidget io.github.matheusmedrado.omadock '{"section":"right"}'

The panel writes to the same config.json described below, through the same validation, so a change made there is identical to one typed by hand and applies to the running dock immediately. Pinned applications stay where they belong: on the dock itself, via right click and drag.

Keybindings

The dock answers to omarchy-shell, so it can be reached without the pointer:

omarchy-shell omadock toggle            # focused monitor
omarchy-shell omadock reveal
omarchy-shell omadock conceal
omarchy-shell omadock toggleOn DP-1     # a named monitor
omarchy-shell omadock status            # state, per monitor, as JSON

omarchy-shell omadock disable           # switch the dock off; the plugin stays
omarchy-shell omadock enable
omarchy-shell omadock toggleEnabled

disable, enable, and toggleEnabled write the same setting the first row of the preferences panel does. While the dock is off, reveal and toggle answer disabled and change nothing, rather than latching a dock that is not there.

A reveal is a latch rather than a hover: it holds the dock open over whatever Smart Hide would otherwise do, until something conceals it. Bind it in ~/.config/hypr/bindings.conf:

bindd = SUPER, D, Toggle the dock, exec, omarchy-shell omadock toggle

The preferences panel answers on its own target, omadock-settings, with open, close, and toggle.

Configuration

Everything in the panel, and a few settings beyond it, live outside the plugin checkout:

~/.config/omadock/config.json

A minimal configuration looks like this:

{
  "version": 1,
  "enabled": true,
  "position": "bottom",
  "monitorMode": "all",
  "pinned": [
    { "desktopId": "com.mitchellh.ghostty" }
  ]
}

enabled is the dock itself: set it to false and the plugin stays installed and the bar widget stays on the bar, with nothing on screen and no window tracking, until it is set back. The configuration also supports monitor selection, compact or comfortable density, appearance, hide behavior, and click actions. Changes are applied live when valid; invalid edits keep the last known-good configuration.

Settings the panel does not surface, because they are set once and forgotten: monitorMode and monitors, aliases for applications whose window class does not match their desktop entry, and the reveal, hide, and animation timings.

Removing OmaDock preserves the configuration file by default.

Updating and removing

The permanent plugin ID is:

io.github.matheusmedrado.omadock

Update a plugin installation with:

omarchy plugin update io.github.matheusmedrado.omadock
omarchy-restart-shell

The restart is part of the update, not an optional extra. The shell loads a plugin's QML when it starts, so new files on disk are not new code in the running shell. omarchy plugin update ends by calling omarchy-shell shell rescanPlugins, which finds plugins that have been added or removed but does not rebuild one that is already loaded -- so without the restart the update looks like it did nothing. It did: the files changed, the pixels did not.

For a manual Git installation, update the checkout instead:

git -C ~/.config/omarchy/plugins/io.github.matheusmedrado.omadock pull
omarchy-restart-shell

Only ~/.config/omadock/config.json is applied without a restart. It is watched and re-read on save, which is why a preference set from the bar widget takes effect immediately while a new version of the dock does not.

Remove the plugin with:

omarchy plugin remove io.github.matheusmedrado.omadock

To remove the configuration as well, delete ~/.config/omadock/ manually after uninstalling the plugin.

Development

How to set up a working checkout, what the checks enforce, and how a release is cut are in CONTRIBUTING.md.

Run the local checks with:

./scripts/check
git diff --check

On an Omarchy installation, also run:

omarchy plugin validate .
qmllint -I "$OMARCHY_PATH/shell" \
  Overlay.qml components/*.qml services/*.qml tests/*.qml

Troubleshooting

Check the plugin status and shell logs first:

omarchy plugin list --json | jq '.[] | select(.id == "io.github.matheusmedrado.omadock")'
qs log -p "$OMARCHY_PATH/shell" --tail 200

For visibility and window-interaction issues, inspect the compositor state:

hyprctl layers
hyprctl clients -j
hyprctl monitors -j

If the dock is hidden, check the active workspace, fullscreen state, and configured monitor mode before blaming the pixels.

The update ran but nothing changed

Run omarchy-restart-shell. See Updating and removing: the shell keeps running the QML it started with, so an update is not visible until it restarts.

To confirm the update itself landed, compare the checkout against the remote:

P=~/.config/omarchy/plugins/io.github.matheusmedrado.omadock
git -C "$P" rev-parse HEAD
git -C "$P" ls-remote origin HEAD

Matching hashes mean the update worked and only the restart is missing. Note that git status in that checkout may report main as ahead of origin/main even when it is identical: omarchy plugin update fetches with git fetch origin HEAD, which records FETCH_HEAD without moving the origin/main tracking ref that git status compares against. A plain git -C "$P" fetch origin refreshes it.

Security and privacy

OmaDock runs with the user's permissions and keeps its command surface small:

  • No sudo, pkexec, telemetry, update checker, or runtime network access.
  • No edits to ~/.config/hypr/.
  • Application launches use resolved desktop entries and structured arguments.
  • User configuration is treated as data, not shell code.
  • No persistent helper process is required at idle.

License

OmaDock is licensed under the MIT License.