Skip to content

About

A window overview plugin for Omarchy and Hyprland, with live thumbnails, instant search, workspace navigation, and optional three-finger swipe controls.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

NittyGriddy

Window grid overview for Omarchy. It shows every open window on the focused screen. Three-finger swipes open and dismiss it after you copy the gesture snippet.

What the plugin does

Enabling the plugin installs the overlay. It does not change your Hyprland swipes or keys.

  • The grid opens on the focused screen, on All, and lists open windows. Live thumbnails appear when Hyprland can export them.
  • The strip keeps this monitor's workspaces 1 through 9 even when empty. Slot 10 is added when that workspace exists. A card shows that same number, so a window Hyprland numbers 14 reads as workspace 4. The number stays at the right edge when the title is long. Clicking a number in the strip shows that page. Clicking the number on a card does the same when that window is on this screen. The desktop workspace stays put.
  • A window on a special workspace, such as the quake console, shows the workstation of the monitor it is on. That console can be summoned on more than one workstation, so it does not get an id of its own. A Grok session in a terminal or in that console is labeled grok.
  • Click a card to focus that window. The window is chosen when the press starts and focused when the click is released, so the click cannot land on the desktop and a pointer warp cannot switch cards. Click the × to close it. Click the empty backdrop to dismiss the grid. The backdrop waits for the release too.
  • Arrow keys move the selection. Enter focuses the selected window. Typing filters by title, app, or workspace.
  • Middle-click and Shift+Q do not close a card. Super+Q closes the selected card while the grid is open, the same as Super+W. With the grid closed it still closes the focused window.
  • While the grid is open the pointer stays where it is, and a visible quake console is hidden. Dismissing the grid brings that console back.

What you set up

Copy gestures.snippet.lua and bindings.snippet.lua into ~/.config/hypr/, then reload Hyprland and restart the shell. The steps are under Swipes and shortcuts. Until you do that, three-finger swipes stay as they are, and Escape, Super+W, Super+Q, Super+Tab, Super+Shift+Tab, and Super+Shift+number keep Omarchy's behavior. The grid will not see them.

After the snippets are in place:

  • Three-finger up opens the grid. Down dismisses it. Left and right switch workspaces while the grid is closed, and page the strip while it is open. The desktop workspace stays put during that paging. Super+Tab and Super+Shift+Tab do the same thing as those swipes.
  • Escape dismisses the grid only while it is open.
  • Super+W and Super+Q close the selected card while the grid is open, and still close the focused window when the grid is closed.
  • The blur behind the grid follows the page. All, and a workstation with no windows, show the blurred desktop wallpaper. That picture is the desktop's current background. A video background uses the lock screen's still. A workstation with windows shows those windows, blurred, and updates when one opens or closes. The grid stays where it is.
  • Super+Shift+1 through Super+Shift+9, and Super+Shift+0 for workspace 10, move the selected card while the grid is open and follow it. With the grid closed, the same chords still move the focused window.

The plugin does not bind Super+A. Omarchy uses that chord for Select all.

Requirements

  • Omarchy Quattro with shell plugins
  • Hyprland Lua config (hl.gesture, hl.dsp)
  • jq
  • hyprctl

Quickshell ships with Omarchy. Live thumbnails need Hyprland toplevel export. Without it, each card still shows the app name and the window title.

Install

omarchy plugin add https://github.com/timsonner/nitty-griddy --enable --yes

If an AI agent is doing the install for you, point it at AGENTS.md.

That clones the plugin to ~/.config/omarchy/plugins/timsonner.nitty-griddy/. Plugin id: timsonner.nitty-griddy.

Swipes and shortcuts

These swipes and keys are yours to install. The pointer actions further down are part of the overlay and need no extra bind.

Copy gestures.snippet.lua to ~/.config/hypr/gestures.lua. Copy bindings.snippet.lua into ~/.config/hypr/bindings.lua. ~/.config/hypr/hyprland.lua does not load gestures.lua unless you require it. Add that require after require("default.hypr.omarchy"):

require("default.hypr.omarchy")

require("hypr.gestures")

Hyprland keeps the first gesture for a fingers-and-direction pair, so this file should be the only three-finger set in the user config.

On Omarchy 4.5 and the edge channel, Omarchy registers its own three-finger swipes: left and right switch workspace, up opens the AI console, and down opens the Omarchy menu. The snippet unsets those four before binding its own, and only when Omarchy actually loaded them, following Omarchy's manual for changing a default gesture. With the snippet in place, three-finger up and down open and dismiss the grid instead of the AI console and the menu. Omarchy's four-finger swipes are not touched. On Omarchy 4.0 nothing is unset, because action = "unset" on a gesture nothing registered is a config error.

Do not add omarchy_default_gestures = false yourself. If an Omarchy migration inserted that line because it saw hl.gesture in ~/.config/hypr, leave it. Omarchy's gestures then never load, the snippet skips its unset, and its four binds still work.

hyprctl reload
omarchy restart shell

hyprctl reload picks up the gestures and the keys. omarchy restart shell mounts the overlay. This overlay stays loaded, so a change to its QML needs another omarchy restart shell before the grid shows it. Saving the file alone can leave the previous grid on screen. A gesture or key change still needs hyprctl reload.

Trackpad

Three fingers. The grid opens on All: every window, including ones on a special workspace. No card is selected.

Swipe Grid closed Grid open
Up Opens the grid Opens the grid. It does not toggle closed
Down Does nothing. It does not open the menu or a console Dismisses the grid. Focus returns to the window that was focused, if it is still open. A quake console that was showing comes back
Right Next workspace, including an empty one Next page. All, then this monitor's workspaces. 1 through 9 stay even when empty. Slot 10 is added when that workspace exists. The desktop workspace stays put. The blur follows that page
Left Previous workspace, including an empty one Previous page, back toward All. The desktop workspace stays put. The blur follows that page

hl.dsp.event posts custom>>timsonner.nitty-griddy:open or custom>>timsonner.nitty-griddy:close on Hyprland’s socket2. The overlay is keepLoaded, so the shell mounts it at startup and it hears those events.

Keys

Key Grid closed Grid open
Escape Passes through to the focused app Dismisses the grid. The compositor bind runs before an input method, so this still works while fcitx5 is running
Super+Tab Next workspace, the same as Omarchy Next page, the same as a three-finger swipe right. The desktop workspace stays put. All and an empty workstation show the wallpaper. A workstation with windows shows those windows
Super+Shift+Tab Previous workspace, the same as Omarchy Previous page, the same as a three-finger swipe left. The desktop workspace stays put. All and an empty workstation show the wallpaper. A workstation with windows shows those windows
Super+W Closes the focused window Closes the selected card. The grid stays if other windows remain. Hover a card, or move to it with the arrow keys, first. With nothing selected, this does not close the window behind the grid. The blur drops that window. The last window leaves the wallpaper
Super+Q Closes the focused window Same as Super+W. Closes the selected card, not the window behind the grid
Super+Shift+1 through Super+Shift+9, and Super+Shift+0 Moves the focused window to that workspace. 0 is workspace 10, same as the bar Moves the selected card there and follows it. All updates that card's workstation number while the grid stays open. Hover a card, or move to it with the arrow keys, first. With nothing selected, this does not move the window behind the grid
Arrow keys Unchanged Move the selection
Enter Unchanged Focuses the selected window and dismisses the grid. The pointer stays where it is
Type, Backspace Unchanged Filters by title, app, or workspace. A letter does not close a window

The plugin does not bind Super+A. Omarchy uses that chord for Select all. Open the grid with a three-finger swipe up.

Pointer

Action Result
Click a card Focuses that window and dismisses the grid when the click is released. The window is chosen when the press starts, so a pointer warp cannot switch cards. The previously focused window is not restored. The pointer stays where it is
Click a number in the strip, or All Shows that page, the same as a left or right swipe. The desktop workspace stays put. The click does not reach the window behind the grid
Click the number on a card Shows that workstation's page when the window is on this screen. A window on another screen keeps its own number, and the click stays on the grid
Click the grid title, or a gap between strip numbers Stays on the current page. The click does not reach the window behind the grid
× on a card Closes that window. The grid stays if others remain
Click the empty backdrop Dismisses the grid when the click is released, same as swipe down or Escape. The press cannot land on the window behind the grid

Middle-click and Shift+Q do not close a card.

The hint along the bottom reads: Type to filter · Arrow keys to move · Enter to focus · Super+W or Super+Q to close · Esc to dismiss · Super+Tab or swipe for workspace. The strip under the title shows All, then each workspace. The current page is the accent color. The grid is on the focused screen. Thumbnails are live while the grid is open. Until a frame arrives, the card shows the app and the title. Window titles are plain text. All and an empty workstation show the blurred desktop wallpaper. A workstation with windows shows those windows, blurred, and that picture updates when a window opens or closes. The cards stay on screen.

IPC

omarchy-shell shell summon timsonner.nitty-griddy '{}'
omarchy-shell shell hide timsonner.nitty-griddy
omarchy-shell shell toggle timsonner.nitty-griddy '{}'

The plugin target is the same three calls:

omarchy-shell timsonner.nitty-griddy open
omarchy-shell timsonner.nitty-griddy close
omarchy-shell timsonner.nitty-griddy toggle

Socket2 events, which is what the gestures dispatch:

hyprctl dispatch 'hl.dsp.event("timsonner.nitty-griddy:open")'
hyprctl dispatch 'hl.dsp.event("timsonner.nitty-griddy:close")'
hyprctl dispatch 'hl.dsp.event("timsonner.nitty-griddy:toggle")'
hyprctl dispatch 'hl.dsp.event("timsonner.nitty-griddy:workspace-prev")'
hyprctl dispatch 'hl.dsp.event("timsonner.nitty-griddy:workspace-next")'
hyprctl dispatch 'hl.dsp.event("timsonner.nitty-griddy:close-selected")'

Validate

omarchy plugin validate ~/.config/omarchy/plugins/timsonner.nitty-griddy

In a checkout of this repo, ./validate checks the manifest, the helpers, and the workspace-number rules without a running shell.

Upgrading Omarchy

If you copied the snippet before this change and then moved from Omarchy 4.0 to 4.5, or from stable to edge, Hyprland can show "Gesture will be overshadowed by a previous gesture" for up, down, left, and right. Copy the current gestures.snippet.lua over ~/.config/hypr/gestures.lua again, then run hyprctl reload.

Troubleshooting

hyprctl configerrors mentions a gesture. "Previous UP shadows new UP" (or DOWN, LEFT, RIGHT) means Omarchy's own three-finger gesture registered first. Copy the current snippet again; see Upgrading Omarchy. Otherwise a direction is bound twice in your own config, or an unset names a gesture nothing registered. Keep one bind for each direction.

Swipe does nothing after a shell restart. The shell is not seeing the socket2 event. In the gesture functions, replace the hl.dispatch(hl.dsp.event(...)) lines with summon and hide. Use hl.dispatch(hl.dsp.exec_cmd(...)). A bare hl.dsp.exec_cmd() only builds a dispatcher and does not run. exec_cmd goes through a shell, which is what the '{}' payload needs.

hl.dispatch(hl.dsp.exec_cmd("omarchy-shell shell summon timsonner.nitty-griddy '{}'"))
hl.dispatch(hl.dsp.exec_cmd("omarchy-shell shell hide timsonner.nitty-griddy"))

Clicking a card does nothing, or the pointer sticks to one card. The window that was focused stays selected under the grid, and Hyprland warps the pointer onto that window's real geometry. On this machine that window is often the quake console (special:qconsole). While the grid is open it sets cursor:no_warps and hides a visible special workspace. Dismissing restores both. Choosing another window leaves the console hidden.

Escape does nothing while an input method is running. fcitx5 can sit on the overlay's keyboard grab and swallow the key. bindings.snippet.lua binds Escape in the compositor and consumes it only while the grid is open, so the grid still dismisses. Leave omarchy-fcitx5.service enabled unless letters typed into the filter are swallowed too. Caps Lock compose sequences need that service.

No thumbnails. The cards still show the app name and the title. Check that Hyprland offers toplevel export and that nothing is blocking screen capture for Quickshell.

Plugin not listed. Run omarchy plugin validate on the plugin directory, then omarchy-shell shell rescanPlugins, then omarchy plugin enable timsonner.nitty-griddy --yes.

Uninstall

Remove the NittyGriddy gestures from ~/.config/hypr/gestures.lua, and remove require("hypr.gestures") if this plugin was the only reason it was there. In ~/.config/hypr/bindings.lua, remove the Escape dismiss bind, the Super+W and Super+Q rebinds, the Super+Tab and Super+Shift+Tab rebinds, and the Super+Shift+number rebinds. Deleting those rebinds gives the keys back to Omarchy. Then:

omarchy plugin remove timsonner.nitty-griddy --yes
hyprctl reload
omarchy restart shell

Removing the plugin does not restore the swipes by itself, because those lines live in your config.

About the name

NittyGriddy takes its name from the Nitty Gritty Dirt Band.

Credits

MIT license. The bounded client list and the short pause before focus follow ideas in kristofferR/omarchy-expose and harel/omarchy-birdseye, both MIT. This overlay is a separate implementation.

About

A window overview plugin for Omarchy and Hyprland, with live thumbnails, instant search, workspace navigation, and optional three-finger swipe controls.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages