Omarchy Dock

Omarchy Dock is a native application dock for Omarchy Quattro. It runs as a persistent service plugin inside omarchy-shell, uses Quickshell/QML and Hyprland's event stream, and does not patch Omarchy or start another shell process.

Plugin ID: setra.dock

What works

• pinned applications stored as canonical .desktop IDs
• installed-application discovery and launching through Quickshell desktop entries and Omarchy's shared application library
• event-driven Hyprland window discovery with workspace-local running indicators, focus, multi-window cycling, and quit
• conservative application/window resolution with per-app overrides
• right-click pin/unpin, desktop actions, move left/right, and quit
• bottom-centered surface, theme colors, magnification, tooltips, auto-hide, and optional exclusive work-area reservation
• continuous pointer-driven magnification wave; icons grow from their bottom center while the Dock widens to preserve icon spacing without changing height
• responsive width limiting that scales crowded docks down before they can extend beyond a monitor edge
• primary, active, all, and named monitor modes
• persistent show/hide state and direct setra.dock IPC
• optional checked Application Dock control for Omarchy's built-in Toggle menu
• keyboard integration through IPC and Omarchy's Lua bindings

The first release deliberately keeps several later-version features out of the critical path. Intellihide, left/right layouts, drag reordering, a window chooser, and a graphical settings panel are planned. The accepted configuration values already leave room for those additions; today, intellihide behaves as always-visible and position renders at the bottom.

Requirements

• Omarchy Quattro 4.x
• Hyprland, Quickshell, and Qt as supplied by Omarchy

The Dock needs no additional runtime packages, services, privileged setup, or background daemon. Node.js and qmllint are used only when developing or validating the repository.

Install

Install and enable the public GitHub repository:

omarchy plugin add https://github.com/fredbrowne/omarchy-dock.git --enable

Omarchy clones the repository to ~/.config/omarchy/plugins/setra.dock, validates manifest.json, and loads it inside the existing shell. Plugin updates are ordinary reviewed fast-forwards:

omarchy plugin update setra.dock

For local development, place a clone at the plugin ID path and enable it:

git clone /path/to/omarchy-dock ~/.config/omarchy/plugins/setra.dock
omarchy-shell shell rescanPlugins
omarchy plugin enable setra.dock

Files below ~/.config/omarchy/plugins/ hot-reload. The installer runs no plugin hooks and needs neither sudo nor an additional daemon.

Like every third-party Quattro plugin, Omarchy Dock runs unsandboxed inside omarchy-shell with the permissions of your user account. Review the source before enabling it. The Dock does not download or execute remote code, invoke a package manager, modify privileged system files, or start another shell process.

Use

• Left click launches a stopped app, focuses its only window, or cycles a multi-window app when its current window is focused. Running state is scoped to the current workspace by default, so clicking a pin that is open only on another workspace launches it here instead of moving you away.
• Middle click opens a new window through the desktop entry.
• Mouse wheel cycles an app's open windows.
• Right click opens pinning, reordering, desktop-action, and quit controls.

The stable IPC surface is:

omarchy-shell setra.dock show
omarchy-shell setra.dock hide
omarchy-shell setra.dock toggle
omarchy-shell setra.dock status
omarchy-shell setra.dock applications
omarchy-shell setra.dock reserve true

status prints visible or hidden. Additional automation methods are:

omarchy-shell setra.dock activate 1
omarchy-shell setra.dock activate spotify.desktop
omarchy-shell setra.dock launch spotify.desktop
omarchy-shell setra.dock cycle code.desktop 1
omarchy-shell setra.dock quit code.desktop
omarchy-shell setra.dock pin spotify.desktop
omarchy-shell setra.dock unpin spotify.desktop
omarchy-shell setra.dock moveLeft spotify.desktop
omarchy-shell setra.dock moveRight spotify.desktop
omarchy-shell setra.dock refresh

applications prints the focused workspace's application model, including pinned/running state, workspace identity, and the Hyprland window classes assigned to each Dock icon.

Targets passed to activate, cycle, or quit must currently be present in the Dock. Numeric activation is one-based and follows visible Dock order.

Ready-to-merge Omarchy menu and keybinding snippets live in examples/omarchy-menu.jsonc and examples/bindings.lua. Review existing bindings before copying the Lua lines into ~/.config/hypr/bindings.lua.

Merge the menu example into ~/.config/omarchy/extensions/omarchy-menu.jsonc to add Trigger → Toggle → Application Dock. The check mark means the Dock is visible. Selecting the row hides or shows it without unloading the plugin; use Setup → Plugins → Disable Plugin only when you want to unload it entirely. This optional edit is never applied automatically by the plugin. Quattro's plugin manifest does not currently support menu contributions, and the plugin installer intentionally runs no install hooks, so silently changing a user-owned menu file would be both unreliable and surprising.

Remove

Remove and unload the installed plugin with:

omarchy plugin remove setra.dock

Omarchy removes the Git checkout and the enabled plugin entry. If you copied the optional menu example, also remove the trigger.toggle.dock object from ~/.config/omarchy/extensions/omarchy-menu.jsonc. If you copied the optional Lua bindings, remove the corresponding setra.dock lines from ~/.config/hypr/bindings.lua. Those user-owned snippets are deliberately not modified during plugin removal.

Configure

Quattro keeps the authoritative plugin settings inline on the setra.dock entry in ~/.config/omarchy/shell.json. Configuration changes and Dock menu operations persist through the shell's own updateEntryInline API.

{
  "plugins": [
    {
      "id": "setra.dock",
      "visible": true,
      "visibilityMode": "always",
      "position": "bottom",
      "monitorMode": "primary",
      "monitor": "DP-1",
      "runningScope": "workspace",
      "reserveSpace": true,
      "iconSize": 48,
      "magnificationEnabled": true,
      "magnification": 1.35,
      "spacing": 6,
      "margin": 10,
      "backgroundOpacity": 0.9,
      "cornerRadius": 18,
      "animationDuration": 120,
      "indicatorStyle": "dot",
      "showRunningApps": true,
      "showUnpinnedRunningApps": true,
      "showTooltips": true,
      "pinned": [
        "com.mitchellh.ghostty.desktop",
        "google-chrome.desktop",
        "code.desktop",
        "spotify.desktop"
      ],
      "appOverrides": {
        "spotify.desktop": {
          "windowClass": "Spotify"
        }
      }
    }
  ]
}

Omitting pinned selects sensible defaults from applications actually installed on the machine. Setting it to [] explicitly starts with no pins. With monitorMode: "primary", a non-empty monitor value is the explicit primary output; when omitted, Quattro's first screen is used. named requires an exact, non-empty output name.

Setting	Default	Accepted values
visible	true	Boolean persisted independently of plugin enablement
visibilityMode	always	always, autohide; intellihide reserved
position	bottom	bottom; left and right reserved
monitorMode	primary	primary, active, all, named
monitor	empty	Output used by named, or an explicit primary output; for example DP-1
runningScope	workspace	workspace for local dots/actions; global for the previous all-workspace behavior
reserveSpace	true	Keep tiled/maximized windows above an always-visible Dock
iconSize	48	32–80 pixels
magnificationEnabled	true	Boolean
magnification	1.35	1.0–2.0
spacing	6	0–24 pixels
margin	10	0–40 pixels from the edge
backgroundOpacity	0.9	0.25–1.0
cornerRadius	18	0–40 pixels
animationDuration	120	0–500 milliseconds
indicatorStyle	dot	dot, line, background, none
showRunningApps	true	Show running state for pinned apps
showUnpinnedRunningApps	true	Append resolved, unpinned running apps
showTooltips	true	Boolean
pinned	detected	Ordered array of IDs including .desktop
appOverrides	{}	Desktop ID to matching metadata map

reserveSpace is honored while visibilityMode is always. Auto-hide and intellihide remain floating so application windows do not resize on every Dock reveal. The reservation is released when the Dock is hidden through IPC and restored when it is shown. It can also be changed without editing JSON:

omarchy-shell setra.dock reserve true
omarchy-shell setra.dock reserve false

Pins and their ordering are always global. With the default runningScope: "workspace", only windows on each monitor's active workspace contribute a running dot or receive click, cycle, and quit actions. Unpinned running applications likewise appear only on their own workspace. Set runningScope to global to restore all-workspace indicators and focusing.

Applications ultimately control their own launch behavior. A multi-window app such as Cursor can create a local window, while a strictly single-instance app may decide to activate its existing window on another workspace.

An override accepts windowClass, initialClass, or appId; each value may be a string or an array. Matching window identifiers is case- and punctuation-insensitive. Canonical desktop IDs remain case- and punctuation-preserving so two distinct installed entries cannot collapse into one Dock application.

How application matching works

The resolver ranks explicit overrides, StartupWMClass, desktop ID against Hyprland class/app ID, desktop ID against initial class, and finally a conservative normalized suffix match. A pinned alias can break an otherwise ambiguous strong match, but it cannot replace a stronger global candidate. Equal-scoring ambiguous matches are rejected. Unresolved windows remain separate rather than being grouped by a generic class such as electron.

See docs/ARCHITECTURE.md for the model invariants and component boundaries.

Develop and verify

This repository has no build step and no runtime dependency beyond what Omarchy Quattro already ships. Validate before submitting a change:

tests/validate.sh

That command validates the manifest, lints every QML component, runs the pure model and manifest tests, and starts a short-lived Quickshell package against the active Quattro session. The runtime smoke test verifies component loading, the magnification binding, and successful/failed settings persistence. GitHub Actions runs the platform-independent model and manifest checks on every push and pull request.

See CONTRIBUTING.md for contribution and release notes.

Compatibility

The plugin targets Omarchy Quattro's Quickshell plugin loader and direct IPC wrapper. It is not compatible with the Waybar-based Omarchy 3 desktop.

License

MIT