❖ OMADOCK ・ オマドック

A modern, fluid, zero-CPU application dock engineered for Omarchy Linux

❤️ Support the project

Omadock is built by thepathless, a medical student in India who codes between classes and clinics. It's free, and it always will be — but building it costs money I don't quite have: monthly AI coding tokens, and a laptop that's falling apart (dead WiFi, sticky keys, a trackpad with a mind of its own) — so I'm saving for a Dell XPS 13 (2026).

If Omadock earns a place on your desktop, sponsoring me keeps the AI lights on and the laptop fund growing. Every supporter is honored on the supporters wall 💝 — with love, no tiers, no perks.

💻 Laptop fund

📊 Where donations went

(running total so far: −₹499 for my coding-agent subscription — borrowed from my mom 😅. Updated monthly; honesty is the least I can offer)

Freebuff wallet (2026-10-03): OmaDock creator thepathless reports adding ₹1,000 to their Freebuff wallet to fund continued development.

To everyone who donates — really, truly, thank you. 🙏

⚡ Overview

Omadock (オマドック) is a fluid, zero-CPU application dock for Omarchy — Arch, Hyprland, Quickshell.

Crafted in the spirit of Omakase (おまかせ): wave magnification, live window previews, app groups, multi-monitor docks. Beautiful, opinionated, and strictly 0.00% background CPU.

✨ Key Highlights

• 🌊 Wave magnification — cosine-falloff dock physics, or classic zoom. Zero coordinate jumping.
• 🪟 Live window previews — minimized windows park on the dock as thumbnail cards.
• 🔘 3-state window dots — active, visible, and minimized at a glance.
• 📁 Folders & groups — folder stacks with recent files, smart app collections, drag-to-group.
• 🖥️ Multi-monitor — one dock per monitor, each showing its own monitor's windows.
• 💾 Removable media — USB drives dock themselves; safe eject included.
• 🔔 Attention glow & chimes — bouncing alerts and audio pings.
• 🔴 Pinned notification badges — counts matching active popups on pinned apps; dismiss or expire a popup to clear it. These are not unread-message counts.
• 🖥️ CLI app identity — Antigravity and btop keep their own icons when launched in a terminal; the terminal icon is only a fallback.
• ⌨️ Keybindings & IPC — wired for ~/.config/hypr/bindings.lua out of the box.

🚀 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

🌟 Core Features

🔘 1. 3-State Window Indicators

Every icon shows all its windows at a glance: ▬ active · ● open · ○ minimized.

🪟 2. Minimized Preview Tiles

When a window is parked on special:minimized, Omadock generates a live visual preview tile between your pinned and running applications:

• 📸→🖱️ Thumbnails appear on minimize; left-click restores to the active workspace.
• 📍 Right-click a tile: Restore Here, Restore to Original Workspace, or Close.
• 📦 In "all" mode, same-app windows stack into one card with a count badge.
• 🧩 Unpinned apps collapse into their tile — the dock stays uncluttered.

Window previews in tooltips. Hovering an app shows thumbnails of its windows, including ones minimized to the dock's hidden workspace. They are captured into GPU memory only while the tooltip is open and are never written to disk. Turn them off in Settings → Behavior → Window previews.

🔄 3. Minimize on Click Modes

Configure how clicking a focused app icon behaves (omadock.json or the Settings menu):

1. "active" (Default): Minimizes the active window and passes focus to the next instance.
2. "all" (Group Batch): Simultaneously minimizes all instances of the application in an atomic batch.
3. "off" (Disabled): Keeps all windows visible and cycles focus between open instances.

🌊 4. Magnification & Hover Effects

Juan Pablo Zamora's raised-cosine falloff magnification, plus shader hover effects — all six modes in hoverEffect:

$$\text{scale}(d) = 1 + (\text{peak} - 1) \cdot \frac{1 + \cos\left(\frac{\pi \cdot d}{R}\right)}{2} \quad \text{for } d \le R$$

• "wave" — the dock ripples under the cursor; zero feedback drift.
• "zoom" — only the hovered icon grows.
• "lift" — the hovered icon rises off the dock.
• "glow" — the hovered icon blooms with light.
• "glitch" — a shader-driven chromatic tear on hover.
• "off" — calm, static geometry.

With an icon style active, iconHoverOriginal shows the hovered icon as shipped, and iconHoverReveal dissolves it back in as a dithered reveal instead of a hard switch.

📁 5. Pinned Folder Stacks & File Popovers

Pin directories like ~/Downloads, ~/Projects, or custom paths directly to your dock:

• Files popover — up to 300 entries with icons, sizes, and relative times.
• View As — right-click the folder: Stack (a list) or Folder (a grid of larger icons, with previews for images and for anything your file manager has already thumbnailed), saved per folder.
• Browse — click a subfolder to step into it, ‹ to go back; long folders scroll.
• Sort By — right-click the folder: Name, Kind, Date Modified, Date Added or Size, saved per folder.
• Direct opening — click any file to open it in its default app (xdg-open), or jump to its folder.
• Drag out — drag a file from the popover into a file manager, browser or chat app.
• Drop in — rest a folder from your file manager over the folder section of the dock for a moment, then drop it to pin it (dropping on an app icon opens it with that app instead).
• Folder picker — attach custom folders from Settings through the desktop's file chooser (omarchy-file-select / XDG portal).

📁 6. App Group Folders (Smart Collections)

Organize applications into intelligent macOS / iOS-style folders directly on your dock:

• 2×2 live preview grid with window dots; the popover tray scales 2–4 columns.
• Drag-to-group, drag-to-pin — drop one icon on another to make a folder.
• Inline renaming, saved instantly.
• Drag-out extraction — folders auto-dissolve when one app remains.

💾 7. Removable Media Auto-Docking

Zero-CPU hardware integration for removable media and USB storage:

• udev + udisks2 detection of USB drives, SD cards, and external storage.
• Tooltips with capacity, label, and mount status; safe eject/unmount with notifications.

📐 8. Dock Alignment Options

Flexible screen placement tailored to your workflow:

• "center", "left", "right" along the bottom edge, with smooth cubic transitions.
• Popovers, tooltips, and menus self-reposition so nothing clips at screen edges.

🖥️ Multi-Monitor Docks

Enable Settings → Placement & Alignment → Show on All Monitors (or "multiMonitor": true) to run a dock on every connected monitor:

• Per-monitor apps — each dock lists its own monitor's windows (pinned apps everywhere); "perMonitorApps": false mirrors everything.
• Minimized tiles follow their origin monitor, whichever dock parked them.
• Hotplug aware; keybinds act on the focused monitor first.

⚡ 9. FreeDesktop Jump Lists & Zero-CPU Autohide

Deep Linux desktop and compositor integration:

• FreeDesktop jump lists — native quick actions straight from .desktop files.
• Drop files on apps — drag files (or a folder) onto an app icon to open them with it; the icon lights up only when the app declares their types (MimeType= in its desktop entry).
• Media controls — right-click an app that plays media (Spotify, a browser playing a video…) for Now Playing with previous / play-pause / next, through MPRIS.
• Intelligent autohide — 2D AABB overlap tests on Hyprland events only. 0.00% CPU, always.

🔔 10. Notification Badges & CLI App Identity

• Pinned icons show a badge counting matching active notification popups — the count clears as soon as the popup leaves the stack (dismissed, expired, or replaced). These are not unread-message counts.
• Terminal-launched apps know who they are: Antigravity (agy) and btop keep their own product icons; the terminal's icon is only a fallback for unknown CLI tools.

🗂 11. Window Preview Cards & Smooth Tooltips

• Hovering an app with several windows shows them as a card stack of live thumbnails in the tooltip; the wheel browses the stack (paced by wheelStepDelay), a click raises the chosen window.
• Tooltips fade in with a small rise, linger 200 ms after the pointer leaves, and cross-fade from icon to icon along the dock — no re-dwelling as you move.
• Menus, folder stacks, app groups and tooltips live in their own focus-grabbing popup windows while the dock layer hugs the card — dock VRAM cost drops from 194 MiB to 26 MiB.

🎨 Customization & Theming

Right-click the Omarchy logo or empty dock space to access deep customization.

🎛️ Settings Panel

Right-clicking either one opens the full settings panel directly: a sidebar with Appearance, Placement, Behavior, Effects, Size & Spacing, Presets, Folders and App Groups, with switches, sliders and dropdowns for every option. Changes apply live, so the dock underneath previews them. Close it with <kbd>Esc</kbd>, the close button, or a click outside. The panel can also be opened from a keybind: omarchy-shell omadock openSettings.

The settings at a glance:

• Shapes: Auto (Theme), Rounded, Round (Pill), Square.
• Opacity: Auto (Theme), 100%, 80%, 65%, 35%, 0% (Transparent Specular).
• Placement & Alignment: Center (Default), Left Aligned, Right Aligned along the screen edge.
• Color Presets: Theme Auto, Pure Black, Mocha, Deep Slate, Midnight Blue, Dark Navy, Emerald Forest, Velvet Ruby.
• Icon Sizing: Small ($28\text{px}$), Medium ($36\text{px}$), Large ($44\text{px}$), Extra Large ($52\text{px}$).
• App Folders & Groups: Automatic smart collections from running apps, drag-to-group, in-place title renaming, and column scaling.

🎨 Presets

Settings → Presets saves the current look (background, effects, border, dividers, icons, size and spacing) as a named preset, up to six, each with a small live thumbnail. Apply, update, rename or delete them there, or switch from the dock's right-click menu (Presets ›). Presets are kept in omadock.json under presets. A keybind can apply one by name:

omarchy-shell omadock applyPreset "Night"

🖱️ Controls Cheat Sheet

⚙️ Configuration Reference

Settings persist in ~/.config/omarchy/omadock.json and are editable live:

{
  "alignment": "center",
  "autohide": true,
  "intelligentAutohide": true,
  "showRemovableDrives": true,
  "minimizeMode": "active",
  "clickToMinimize": true,
  "showMinimizedTiles": true,
  "opacity": 1.0,
  "shape": "rounded",
  "cornerRadius": -1,
  "bgColor": "theme",
  "showBackground": true,
  "showShadow": true,
  "showBorder": true,
  "borderOpacity": "theme",
  "groupStyle": "rounded",
  "itemSpacing": 4,
  "splitSections": false,
  "sectionSpacing": 18,
  "dividerGeometry": "classic",
  "dividerHeight": 70,
  "dividerStyle": "simple",
  "dividerWidth": 1.5,
  "dividerOpacity": 0.4,
  "iconSize": 0,
  "hoverEffect": "zoom",
  "keepPointer": true,
  "wheelStepDelay": 150,
  "iconHoverReveal": false,
  "showAppsButton": true,
  "showTooltips": true,
  "advancedTooltips": true,
  "launchBounce": true,
  "showUrgentHint": true,
  "urgentOnNotification": true,
  "showNotificationBadges": true,
  "urgentSound": true,
  "urgentSoundName": "bell",
  "folderColor": "theme",
  "revealDelay": 160,
  "tooltipDelay": 450,
  "pinnedFolders": [
    { "path": "~/Downloads", "name": "Downloads", "icon": "folder-download" }
  ],
  "appGroups": [
    { "id": "browsers", "name": "browsers", "apps": ["google-chrome", "brave-browser", "chromium", "firefox", "zen-browser"] }
  ]
}

⌨️ Keyboard Shortcuts via IPC

Omadock registers IPC commands callable directly by Quickshell.

Automated Setup (Recommended)

Run the bundled keybinding helper script to automatically configure all shortcuts:

~/.config/omarchy/plugins/omadock/scripts/bind-keys.sh

Manual Setup

Add these keybinds to ~/.config/hypr/bindings.lua:

-- Toggle Dock Visibility
o.bind("SUPER + D", "Toggle Omadock", "exec qs -p /usr/share/omarchy/shell ipc call omadock toggleVisibility")

-- Minimize currently focused window to Omadock
o.bind("SUPER + M", "Minimize focused window", "exec qs -p /usr/share/omarchy/shell ipc call omadock minimizeActive")

-- Restore longest-parked window (FIFO)
hl.unbind("SUPER + SHIFT + M")
o.bind("SUPER + SHIFT + M", "Restore oldest minimized", "exec qs -p /usr/share/omarchy/shell ipc call omadock restoreLast")

Additional IPC methods available:

• reveal: Force dock to slide into view.
• hide: Force dock to slide out of view.
• setAlignment("center" | "left" | "right"): Change dock alignment dynamically.
• setPosition("bottom" | "top" | "left" | "right"): Change dock edge position.
• openSettings: Open the settings panel on the focused monitor's dock.
• openSettingsPage("appearance" | "placement" | "behavior" | "effects" | "size" | "folders" | "groups" | "presets" | "about"): Open the settings panel on a given page.
• closeSettings: Close the settings panel.

[!NOTE] The -p /usr/share/omarchy/shell flag is mandatory to target the active Omarchy system shell instance.

❓ FAQ

🛠️ Diagnostics & Validation

Every pull request runs the test suites, a QML syntax gate and the manifest schema check in CI.

# Validate manifest compliance against Omarchy 4.0.3+ standards
omarchy plugin validate ~/Projects/omadock

# Same manifest gate CI runs (a faithful mirror of the command above)
./tests/manifest-check.sh .

# Test suites (Node: model + perf + hardening; Python: script helpers)
node --check DockModel.js
node --test tests/unit/*.test.js tests/unit/*.test.mjs
python3 -m unittest discover -s tests/unit -p 'test_*.py'

# Load-time smoke test (probes the running shell)
./tests/smoke-test.sh

# Inspect live compositor journal logs
journalctl --user -xeu omarchy-shell -n 50 --no-pager

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

🗂 Repository Layout

📄 License

Distributed under the MIT License.
Copyright © 2026 thepathless.

📋 Releases & Changelog

Full release notes, historical changelogs, and upgrade guides across all versions are available on GitHub Releases.