Zen Mode

Black out distractions and leave only the window you're working in.

Zen Mode is a distraction-free focus plugin for the Omarchy desktop on Hyprland. When toggled, Zen Mode heavily darkens everything outside your active window while keeping the active window 100% untouched and clear. When you need to interact with the Omarchy bar, moving the pointer over the bar smoothly reveals it.

https://github.com/user-attachments/assets/b684c501-d5af-4df5-87e6-288f8c72272c

Features

Distraction-Free Focus Mask: Heavily darkens the desktop outside the active window (0.94 dim default) without intrusive glows, decorative frames, or artificial borders.
Accurate Window Cutout: Automatically follows active window bounds, including compositor borders (2px) and Hyprland's corner rounding for floating, pinned, and tiled windows without corner sliver leaks.
Bar Reveal on Hover: Moving your pointer over the real Omarchy bar smoothly reveals only the bar rectangle (120 ms reveal / 200 ms hide duration). Moving away restores full dimming.
Zero Input Interference: Uses empty input regions (Region {}) and WlrKeyboardFocus.None to ensure 100% pass-through for all mouse clicks, scroll wheels, gestures, and keystrokes.
Multi-Monitor Architecture: Independent layer-shell overlay per monitor with dynamic focus tracking across screens and workspaces.
Lightweight & Secure: Pure QML / Quickshell implementation running strictly within standard shell lifecycle events. No background polling loops, no daemons, and no network dependencies.

Installation

Via Omarchy Plugin Manager (omarchyplugins.com)

omarchy plugin add https://github.com/sanjyay/zen-mode.git --enable

Manual / Local Development Install

Clone or copy this repository to your local plugins directory:

git clone https://github.com/sanjyay/zen-mode.git ~/.config/omarchy/plugins/io.github.sanjyay.zenmode
omarchy plugin enable io.github.sanjyay.zenmode

Uninstallation

Via Omarchy Plugin Manager

omarchy plugin remove io.github.sanjyay.zenmode

Manual Removal

omarchy plugin disable io.github.sanjyay.zenmode
rm -rf ~/.config/omarchy/plugins/io.github.sanjyay.zenmode

Usage & Keybindings

Keybinding Setup

Add the following binding to ~/.config/hypr/bindings.lua:

o.bind(
  "SUPER + SHIFT + O",
  "Zen Mode",
  "omarchy-shell shell toggle io.github.sanjyay.zenmode '{}'"
)

Reload Hyprland bindings:

hyprctl reload

Terminal Commands

Toggle Zen Mode:

omarchy-shell shell toggle io.github.sanjyay.zenmode '{}'

Summon (turn ON):

omarchy-shell shell summon io.github.sanjyay.zenmode '{}'

Hide (turn OFF):

omarchy-shell shell hide io.github.sanjyay.zenmode

Configuration

Zen Mode can be customized in ~/.config/omarchy/shell.json under the plugins array:

{
  "plugins": [
    {
      "id": "io.github.sanjyay.zenmode",
      "dimOpacity": 0.94,
      "spotlightPadding": 0,
      "animationDuration": 150,
      "revealBarOnHover": true,
      "barRevealDuration": 120,
      "barHideDuration": 200,
      "showPresentationLabel": false
    }
  ]
}

Options Reference

Option	Type	Default	Description
`dimOpacity`	`number`	`0.94`	Darkness level of inactive screen areas (`0.20` - `1.00`).
`spotlightPadding`	`number`	`0`	Additional padding around the active window cutout in pixels (`0` - `32`).
`animationDuration`	`number`	`150`	Transition speed in milliseconds when switching windows or workspaces.
`revealBarOnHover`	`boolean`	`true`	Whether hovering or interacting with the Omarchy bar reveals it.
`barRevealDuration`	`number`	`120`	Fade-in animation duration in milliseconds when pointer enters the bar.
`barHideDuration`	`number`	`200`	Fade-out animation duration in milliseconds when pointer leaves the bar.
`showPresentationLabel`	`boolean`	`false`	Displays a subtle title badge next to the active window when focused.

Plugin Specification Compliance

This plugin complies with the omarchyplugins.com v1 specification:

Manifest: manifest.json conforms to schemaVersion: 1.
Kind: overlay with keepLoaded: true for instantaneous toggle performance.
Entry Point: ZenMode.qml implements standard open(payloadJson) and close() lifecycle methods.
Namespace: io.github.sanjyay.zenmode.
License: MIT.

Marketplace Metadata

Name: Zen Mode
Category: Desktop
Tags: hyprland, quickshell, focus, productivity

Testing & Quality Assurance

Run the test suite and validation:

# Run unit tests
QML_XHR_ALLOW_FILE_READ=1 qmltestrunner -input tests

# Validate Omarchy plugin manifest and structure
omarchy plugin validate .

# Check git formatting
git diff --check

License

This project is licensed under the MIT License - see the LICENSE file for details.