❖ OMADOCK ・ オマドック

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

Quick Start • Features • Preview Tiles • Theming • Controls • Configuration • Keybindings • FAQ

---

⚡ Overview

Omadock (オマドック) is an ultra-fast, lightweight shell overlay plugin built natively for Omarchy (Arch Linux + Hyprland + Quickshell).

Crafted in the spirit of Omakase (おまかせ) — curated elegance and effortless flow — Omadock bridges the gap between dynamic tiling compositors and tactile desktop ergonomics. It delivers fluid wave magnification, live screencopy preview cards, and multi-instance window management with strictly 0.00% background CPU consumption.

✨ Key Highlights

• 🔘 3-State Window Dots: Instant visual indicator dots for active, visible, and minimized windows.
• 🌊 Wave & Zoom Magnification: Continuous cosine-falloff cursor growth with unmagnified geometry anchors.
• 🪟 Visual Window Previews: Minimized windows park directly on the dock as visual thumbnail cards.
• ⚡ FreeDesktop Jump Lists: Native desktop action menus (incognito tabs, new windows, custom actions).
• 📁 Folder Stacks & Popovers: 1-click popovers for recent files with automatic theme sync and color presets.
• 🔔 Attention Glow & Canberra Chimes: Bouncing alerts and audio chimes for background notifications.
• 🎯 Intelligent Zero-CPU Autohide: Event-driven 2D Axis-Aligned Bounding Box (AABB) window overlap detection.
• 🔄 Fluid Drag-and-Drop: Drag pinned items to reorder with live real-time insertion markers.

---

🚀 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 running application icon features micro-indicators communicating the exact state of all open instances:

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

Window Count	Indicator Visual	Behavior
1–4 windows	[ ▬ ] [ ● ] [ ○ ] [ ● ]	Dedicated indicator dot/bar for every individual window.
5 windows	[ ▬ ] [ ● ] [ ● ] [ ● ] [ ● ]	Micro-dot scaling ($4\text{px}$) fits up to 5 instances cleanly.
6+ windows	[ ▬ ] [ ● ] [ ● ] [ ● ] [ +N ]	First 4 instance dots plus a compact +N count badge.

---

🪟 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:

• 📸 Visual Window Previews: Displays a clean, static thumbnail of the window upon minimization.
• 🎯 1-Click Restore: Left-clicking any preview tile restores the window directly onto your currently active workspace.
• 📍 Origin Restoration: Right-click any tile to choose between Restore Here, Restore to Original Workspace, or Close.
• 📦 Stacked Group Cards: In "all" mode, multiple windows from the same application bundle into a stacked visual card with count badge.
• 🧩 Space-Saving Icon Collapse: Unpinned apps collapse into their preview tile when all windows are minimized, keeping the dock uncluttered.

---

🔄 3. Minimize on Click Modes

Configure how clicking an active application icon behaves in omadock.json or via the Settings menu:

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

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. Wave & Zoom Magnification

Omadock features Juan Pablo Zamora's raised-cosine falloff equation for fluid, Apple-style wave magnification:

$$\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 Mode ("wave"): Dynamic slot growth where neighbor items smoothly expand with constant unmagnified home coordinates (zero feedback drift).
• Zoom Mode ("zoom"): Scales only the hovered icon in-place without shifting surrounding slots.
• Off ("off"): Clean, static dock geometry for minimal distraction.

---

📁 5. Pinned Folder Stacks & File Popovers

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

• Recent Files Popover: 1-click reveals up to 16 newest files sorted chronologically with mimetype icons, file sizes, and relative times (Just now, 5m ago).
• Direct Opening: Click any file to launch with xdg-open or open the containing folder in your file manager.
• GTK Folder Dialog: Easily browse and attach custom folders from the Settings menu.

---

🎨 Customization & Theming

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

Appearance	Behavior & Windows	Effects & Animations
Size & Spacing	Folders & Stacks

• Shapes: Auto (Theme), Rounded, Round (Pill), Square.
• Opacity: Auto (Theme), 100%, 80%, 65%, 35%, 0% (Transparent Specular).
• 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}$).

---

🖱️ Controls Cheat Sheet

Gesture / Trigger	Target	Action Executed
Left Click	❖ Omarchy Logo	Opens Omarchy Application Launcher
Right Click	❖ Omarchy Logo	Opens Omadock Preferences Menu
Scroll Wheel	❖ Omarchy Logo	Cycles active Hyprland workspaces
Middle Click	❖ Omarchy Logo	Spawns default terminal emulator
Left Click	Application Icon	Launches app / focuses / restores window
Middle Click	Application Icon	Launches a new instance of the application
Scroll Wheel	Application Icon	Cycles focus through open instances
Right Click	Application Icon	Context menu (Window list, Desktop Actions, Pin, Close)
Left Click	Folder Stack	Toggles recent-files popover
Right Click	Folder Stack	Folder options (Open in File Manager, Unpin)
Left Click	Preview Tile	Restores window to current workspace
Right Click	Preview Tile	Restore Here / Restore to Original / Close
Drag & Drop	Pinned Icon	Reorders pinned application position live
Bottom Edge Hover	Screen Edge	Reveals autohidden dock instantly

---

⚙️ Configuration Reference

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

View Annotated Configuration Schema

{
  "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" }
  ]
}

Key	Type	Default	Description
autohide	bool	true	Enables dock autohiding on hover exit.
intelligentAutohide	bool	true	Hides dock only when windows overlap its bounding box (AABB).
minimizeMode	string	"active"	"active" (FIFO single), "all" (batch group), "off" (disabled).
showMinimizedTiles	bool	true	Displays live screencopy preview tiles for parked windows.
opacity	number | str	1.0	Background opacity: "theme", 1.0, 0.80, 0.65, 0.35, 0.0.
shape	string	"rounded"	Dock geometry: "rounded", "round" (pill), "square", "theme".
bgColor	string	"theme"	"theme", "none", or custom hex string ("#1e1e2e").
folderColor	string	"theme"	"theme", "symbolic", "white", "black", "Yaru-blue", etc.
hoverEffect	string	"zoom"	Hover growth mode: "zoom", "wave", or "off".
revealDelay	int	160	Edge dwell time in milliseconds before unhiding ($0$–$2000$).
tooltipDelay	int	450	Tooltip hover dwell delay in milliseconds ($0$–$5000$).

---

⌨️ Keyboard Shortcuts via IPC

Omadock registers IPC commands callable directly by Quickshell. Add these keybinds to ~/.config/hypr/bindings.lua:

-- 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)
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 mandatory to target the active Omarchy system shell instance.

---

❓ FAQ

Where are minimized windows stored?

Windows are placed onto Hyprland's hidden special:minimized workspace. Omadock remembers their origin workspace so you can restore them instantly to where they belong.

How do I pin or unpin applications?

Right-click any running application icon and click Pin to Dock. Pinned applications are stored in ~/.config/omarchy/dock.json. You can drag and drop icons along the dock to reorder them live.

How do I make the dock completely transparent?

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

How do I reload after manual JSON edits?

Run omarchy restart shell in your terminal to instantly reload the Quickshell engine.

---

🛠️ Diagnostics & Validation

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

# 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

---

📄 License

Distributed under the MIT License.
Copyright © 2026 thepathless.