Omadock (`omadock`)

A modern, high-performance application dock for Omarchy (Quickshell + Hyprland).

📖 Overview

Omadock is a lightweight, zero-CPU application dock built natively for Omarchy Linux. It pairs a clean, modern aesthetic with the power of the Hyprland tiling compositor.

Whether you run a single browser window or tile dozens of terminals across multiple workspaces, Omadock gives you:

Instant visual window-state feedback via a 3-state indicator system
Mouse-wheel window cycling with rich multi-window tooltips
Sequential or batch minimization with live preview tiles on the dock
Unpinned apps whose windows are all minimized collapse into their tile — the tile is the dock's single representation for them
Real-time attention alerts with optional audio chimes
Live drag-and-drop pin reordering
Pinned folder stacks with recent-file popovers
Native FreeDesktop Desktop Actions (jump lists)
Deep right-click customization — all without leaving the dock

⚡ Quick Start

Install

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

Update

omarchy plugin update omadock --yes

Removal / Uninstall

omarchy plugin remove omadock --yes

🌟 Feature Guide

🔘 1. The 3-State Window Indicator System

Underneath each running application icon, Omadock draws indicator dots that show the exact state of every window at a glance:

  ┌─────────────────────────────────────────────────────────────┐
  │  INDICATOR LEGEND:                                          │
  │   [ ▬ ] Active / Focused Window   (Illuminated Theme Bar)   │
  │   [ ● ] Open / Visible Window     (Solid High-Contrast Dot) │
  │   [ ○ ] Minimized / Parked Window (Hollow Circle Ring)      │
  └─────────────────────────────────────────────────────────────┘

Active Focused [ ▬ ]: Expands into an illuminated pill bar in your active theme's accent color.
Open Visible [ ● ]: Solid circle for every window sitting on your desktop.
Minimized [ ○ ]: Hollow ring the moment a window is parked on special:minimized.

🔢 2. Adaptive Multi-Window Scaling

Window Count	Indicator Display	Description
1–4 windows	`[ ▬ ] [ ● ] [ ○ ] [ ● ]`	Every window gets its own full-size dot or active bar.
5 windows	`[ ▬ ] [ ● ] [ ● ] [ ● ] [ ● ]`	Micro-dot compression (`4px`) fits 5 instances cleanly.
6+ windows	`[ ▬ ] [ ● ] [ ● ] [ ● ] [ +N ]`	First 4 states + a compact `+N` overflow badge.

🔄 3. Minimize on Click (3 Modes)

                         ┌─────────────────────────────────┐
                         │   Click On Focused Dock Icon    │
                         └──────────────┬──────────────────┘
                                        │
             ┌──────────────────────────┼──────────────────────────┐
             ▼                          ▼                          ▼
     [ Active Window ]           [ All Windows ]             [ Disabled ]
  (Sequential FIFO — default)  (Group Batch / Hide)        (Standard / Classic)

Active Window ("active" — default): Minimizes only the single focused window; focus passes to the next window. Each parked window appears as its own live preview tile.
All Windows ("all"): One click parks every window of the app simultaneously. Each becomes its own preview tile.
Disabled ("off"): Clicking an active app never minimizes — it cycles focus to the next window.

Intelligent focus & workspace navigation: Left-clicking any running app brings its window forward. If the window is minimized, Omadock unminimizes and restores it onto your current workspace; if it is visible on another workspace, Omadock navigates there and focuses it.

📜 4. Interactive Tooltips & Mouse-Wheel Selection

When an app has multiple windows open:

Hover the dock icon → a rich tooltip lists all visible windows (minimized ones appear as tiles instead).
Scroll the mouse wheel → a › cursor cycles through the window list live.
Left-click → directly focuses the selected window.

🪟 4b. Live Minimized-Window Preview Tiles

Minimized windows appear as live preview tiles between the pinned and running sections — oldest parked window on the left, newest on the right:

Each tile shows a real screenshot of the window, an app badge, and a title tooltip.
Click a tile → restores that exact window onto your currently active workspace.
Right-click a tile → Restore Here / Restore to Original / Close actions. "Restore to Original" sends the window(s) back to the workspace they were minimized from.
In All Windows mode, each app's windows compress into a single stacked group tile (badge shows the count; clicking it restores all at once — every window lands on your current workspace in a single step, with no per-window flashing).
Unpinned apps that are fully minimized hide their running icon entirely — the tile becomes the app's only representation on the dock (pinned apps keep both icon and tile).
Toggle via Settings → Minimized Window Previews or the showMinimizedTiles config key.

⚡ 5. FreeDesktop Desktop Actions (Jump Lists)

Right-click application icons to access native XDG desktop actions:

Browsers: Open New Incognito / Private Window.
Editors & Terminals: New Empty Window or recent workspaces.
Communication: New Chat, Compose, or status change.
Web Apps / PWAs: Open in browser or native window.

🗂️ 6. Pinned Folder Stacks & Recent Files

1-click popover: Click any pinned folder (~/Downloads, custom directories) to reveal a sorted list of recent files (up to 16, newest first). Folders holding more show a "+N more — open in File Manager" row at the bottom.
File metadata: Mimetype icons, sizes, and relative times (Just now, 5m ago, 2h ago).
Direct launch: Click any file to open it with xdg-open; click Open in File Manager at the bottom.
Folder picker: Add any folder from Settings → Folders & Stacks › via a native GTK folder dialog.

🎨 7. Themed Folder Colors & Symbolic Outlines

Auto Theme Sync: Folder icon colors automatically track the active Omarchy theme.
Yaru Color Swatches: Sage, Olive, Magenta, Purple, Blue, Red, Yellow, Brown, Teal, Charcoal.
Monochrome Symbolic Outlines: Crisp outline glyphs for dark, vantablack, or minimal setups. Also available as explicit White / Black presets.

🔔 8. Notification Urgency & Audio Chimes

When a background app receives a notification (Slack, Discord, Matrix, WhatsApp…), its dock icon bounces and pulses with an urgency glow.
Audio feedback: Selectable chime (Bell, Message, Complete, Info, Warning, or None).
Foreground Suppression: Urgency is automatically suppressed when you are already inside that window.
Startup Suppression: Initial window-open urgency is ignored for 3 seconds to prevent false triggers on launch.
Omarchy DND Integration: Sound alerts are automatically muted when system-wide Do Not Disturb is active.

🎨 9. Appearance & Deep Customization

Right-click the Omarchy logo → Dock Settings to access the full settings menu:

Corner Shapes: Auto (Theme), Rounded, Round (full pill), Square.
Background Opacity: Auto (Theme), 100%, 80%, 65%, 35%, 0% (Transparent).
Custom Color Swatches: 10 curated presets (Pure Black, Mocha, Deep Slate, Midnight Blue, Dark Navy, Emerald Forest, Velvet Ruby…) plus automatic luminance contrast for foreground text.
Icon Size: Small (28px), Medium (36px), Large (44px), Extra Large (52px).
Icon Spacing: Compact, Normal, Relaxed.
Magnification: Wave (raised-cosine falloff, grows layout), Zoom (single-icon peak), or Off.

🎯 10. Zero-CPU Autohide & Tiling Adaptation

0.00% Idle CPU: All state is driven by Hyprland's native IPC event bus — no polling loops.
Tiling Window Reservation: In Always Show mode, Omadock sets a Wayland exclusiveZone so tiled windows never overlap the dock.
Intelligent Autohide: Stays visible on empty workspaces; hides only when open windows overlap the dock area (AABB intersection check against the dock's own monitor — event-driven on window moves, with a lightweight 350ms fallback only while the dock is visible during interactive window drags/resizes).

🔄 11. Live Drag-and-Drop Pin Reordering

Click and drag any pinned icon horizontally to reorder it.
A real-time insertion indicator shows the exact drop position.
Pin order is persisted across reboots in ~/.config/omarchy/dock.json.

🖱️ Controls Cheat Sheet

Action	Target	Result
Left Click	Omarchy Logo	Opens the Omarchy Application Menu
Right Click	Omarchy Logo / Empty Dock Space	Opens Dock Settings
Scroll	Omarchy Logo	Cycles workspaces
Middle Click	Omarchy Logo	Opens a terminal
Left Click	App Icon	Launches, focuses, switches workspace, or minimizes/restores
Middle Click	App Icon	Opens a new instance of the application
Scroll	App Icon	Cycles focus between open windows
Right Click	App Icon	App menu (window list, Desktop Actions, Pin/Unpin, Quit)
Left Click	Folder Icon	Toggles the recent-files stack popover
Right Click	Folder Icon	Folder options (Open in File Manager, Unpin)
Left Click	Preview Tile	Restores that minimized window
Right Click	Preview Tile	Restore Here / Restore to Original / Close
Click & Drag	Pinned Icon	Reorders position live
Bottom Edge Hover	Screen Bottom	Reveals the autohidden dock

⚙️ Configuration Reference

All settings can be changed via the right-click menu or edited directly in ~/.config/omarchy/omadock.json:

{
  "autohide": true,
  "intelligentAutohide": true,
  "minimizeMode": "active",
  "showMinimizedTiles": true,
  "opacity": 1.0,
  "shape": "rounded",
  "bgColor": "theme",
  "itemSpacing": 4,
  "iconSize": 0,
  "hoverEffect": "zoom",
  "showAppsButton": true,
  "showTooltips": true,
  "advancedTooltips": true,
  "launchBounce": true,
  "showUrgentHint": true,
  "urgentOnNotification": true,
  "urgentSound": true,
  "urgentSoundName": "bell",
  "folderColor": "theme",
  "revealDelay": 160,
  "tooltipDelay": 450,
  "pinnedFolders": [
    { "path": "~/Downloads", "name": "Downloads", "icon": "folder-download" }
  ]
}

Property	Type	Default	Description
`autohide`	`boolean`	`true`	Autohide on reveal. `false` = always visible.
`intelligentAutohide`	`boolean`	`true`	Hide only when a window overlaps the dock area.
`minimizeMode`	`string`	`"active"`	`"active"` (sequential FIFO), `"all"` (group batch), `"off"` (disabled).
`showMinimizedTiles`	`boolean`	`true`	Show minimized windows as live preview tiles on the dock.
`opacity`	`number \| string`	`1.0`	Background transparency: `"theme"` / `"auto"` (follow theme), `1.0`, `0.80`, `0.65`, `0.35`, `0.0`.
`shape`	`string`	`"rounded"`	Corner style: `"rounded"`, `"round"` (full pill), `"square"`, `"theme"` (auto from Omarchy theme).
`bgColor`	`string`	`"theme"`	Background color: `"theme"` (auto), `"none"`, or a hex string e.g. `"#1e1e2e"`.
`folderColor`	`string`	`"theme"`	Folder icon color: `"theme"`, `"symbolic"`, `"white"`, `"black"`, `"Yaru-sage"`, `"Yaru-blue"`, etc.
`itemSpacing`	`number`	`4`	Gap between icons in pixels (`2`, `4`, `8`).
`iconSize`	`number`	`0`	Icon size in pixels (`28`, `36`, `44`, `52`; `0` = auto from bar height).
`hoverEffect`	`string`	`"zoom"`	`"zoom"` (single-icon peak), `"wave"` (raised-cosine falloff), `"off"`.
`showAppsButton`	`boolean`	`true`	Show/hide the Omarchy logo button.
`showTooltips`	`boolean`	`true`	Show app-name tooltips on hover.
`advancedTooltips`	`boolean`	`true`	Rich tooltips listing up to 8 windows; scroll to cycle, click to focus.
`launchBounce`	`boolean`	`true`	Bounce icon while an app is starting.
`showUrgentHint`	`boolean`	`true`	Pulse and bounce on urgency / attention demand.
`urgentOnNotification`	`boolean`	`true`	Trigger urgency when a desktop notification arrives.
`urgentSound`	`boolean`	`true`	Play a chime on urgency (auto-silenced in DND mode).
`urgentSoundName`	`string`	`"bell"`	Sound name: `"bell"`, `"message-new-instant"`, `"complete"`, `"dialog-information"`, `"none"`.
`screen`	`string`	`""`	Monitor name to pin the dock to (default: primary monitor).
`revealDelay`	`number`	`160`	Edge dwell time in ms before the hidden dock reveals (0–2000).
`tooltipDelay`	`number`	`450`	Hover dwell time in ms before tooltips appear (0–5000).
`pinnedFolders`	`array`	`[…]`	Pinned folder objects: `{ "path": "…", "name": "…", "icon": "…" }`.

Legacy key: clickToMinimize (boolean) is still read for backwards compatibility but is derived from minimizeMode. Prefer minimizeMode.

Keyboard Bindings via IPC

Omadock exposes dock actions to Quickshell's IPC bus, bindable in ~/.config/hypr/bindings.lua:

o.bind("SUPER + M",       "Minimize focused window",   "exec qs -p /usr/share/omarchy/shell ipc call omadock minimizeActive")
o.bind("SUPER + SHIFT + M", "Restore oldest minimized", "exec qs -p /usr/share/omarchy/shell ipc call omadock restoreLast")

Note: the -p /usr/share/omarchy/shell flag is required — the Omarchy shell runs from the system path, so a bare qs ipc call cannot resolve the instance.

IPC Target	Action
`minimizeActive`	Park the currently focused window to `special:minimized`
`restoreLast`	Restore the longest-parked window across all apps (FIFO)

Pinned Applications (`~/.config/omarchy/dock.json`)

{
  "pinned": [
    "foot",
    "org.gnome.Nautilus",
    "google-chrome",
    "code"
  ]
}

❓ FAQ

How do I pin or unpin an application?

Right-click the app icon → Pin to Dock / Unpin from Dock. Drag pinned icons to reorder.

Where do minimized windows go?

Omadock parks them on a hidden Hyprland workspace (special:minimized). Each appears as a live preview tile on the dock. Click a tile to restore the window onto your current workspace (or right-click → Restore to Original to send it back where it came from).

How do I make the dock fully transparent?

Right-click the Omarchy logo → Appearance → Background Opacity → Transparent (0%). The dock renders a specular border around the icons.

How do I reload the dock after editing config?

omarchy restart shell

🛠️ Diagnostics

# Validate plugin against Omarchy marketplace standards
omarchy plugin validate ~/Projects/omadock

# Live compositor logs
journalctl --user -xeu omarchy-shell -n 50 --no-pager

# Smoke-test IPC keybinds
qs -p /usr/share/omarchy/shell ipc call omadock minimizeActive
qs -p /usr/share/omarchy/shell ipc call omadock restoreLast

Name		Name	Last commit message	Last commit date
assets		assets
screenshots		screenshots
AGENTS.md		AGENTS.md
Dock.qml		Dock.qml
DockModel.js		DockModel.js
LICENSE		LICENSE
README.md		README.md
manifest.json		manifest.json
preview.png		preview.png

Navigation Menu

Repository files navigation

Omadock (`omadock`)

📖 Overview

⚡ Quick Start

Install

Update

Removal / Uninstall

🌟 Feature Guide

🔘 1. The 3-State Window Indicator System

🔢 2. Adaptive Multi-Window Scaling

🔄 3. Minimize on Click (3 Modes)

📜 4. Interactive Tooltips & Mouse-Wheel Selection

🪟 4b. Live Minimized-Window Preview Tiles

⚡ 5. FreeDesktop Desktop Actions (Jump Lists)

🗂️ 6. Pinned Folder Stacks & Recent Files

🎨 7. Themed Folder Colors & Symbolic Outlines

🔔 8. Notification Urgency & Audio Chimes

🎨 9. Appearance & Deep Customization

🎯 10. Zero-CPU Autohide & Tiling Adaptation

🔄 11. Live Drag-and-Drop Pin Reordering

🖱️ Controls Cheat Sheet

⚙️ Configuration Reference

Keyboard Bindings via IPC

Pinned Applications (`~/.config/omarchy/dock.json`)

❓ FAQ

How do I pin or unpin an application?

Where do minimized windows go?

How do I make the dock fully transparent?

How do I reload the dock after editing config?

🛠️ Diagnostics

📄 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Omadock (omadock)

📖 Overview

⚡ Quick Start

Install

Update

Removal / Uninstall

🌟 Feature Guide

🔘 1. The 3-State Window Indicator System

🔢 2. Adaptive Multi-Window Scaling

🔄 3. Minimize on Click (3 Modes)

📜 4. Interactive Tooltips & Mouse-Wheel Selection

🪟 4b. Live Minimized-Window Preview Tiles

⚡ 5. FreeDesktop Desktop Actions (Jump Lists)

🗂️ 6. Pinned Folder Stacks & Recent Files

🎨 7. Themed Folder Colors & Symbolic Outlines

🔔 8. Notification Urgency & Audio Chimes

🎨 9. Appearance & Deep Customization

🎯 10. Zero-CPU Autohide & Tiling Adaptation

🔄 11. Live Drag-and-Drop Pin Reordering

🖱️ Controls Cheat Sheet

⚙️ Configuration Reference

Keyboard Bindings via IPC

Pinned Applications (~/.config/omarchy/dock.json)

❓ FAQ

How do I pin or unpin an application?

Where do minimized windows go?

How do I make the dock fully transparent?

How do I reload the dock after editing config?

🛠️ Diagnostics

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Omadock (`omadock`)

Pinned Applications (`~/.config/omarchy/dock.json`)