New in 0.2: grid zones. Hold SUPER + SHIFT and drag, or press SHIFT in the middle of a drag.
And the layout editor in the settings window: split, drag a divider, merge, save, apply.
Magnet-style window snapping for Omarchy's floating workspace mode. Press a shortcut or drag a window to a screen edge, and it snaps to a half, third, quarter or the whole screen. It does nothing on dwindle or scrolling workspaces.
omagnet is two parts in one repo:
- The snapping module (
lua/): pure Lua on Hyprland's own Lua API. No native code, so a Hyprland update cannot break a compiled module. - The settings app (this folder is an Omarchy plugin): a settings window opened from the launcher. It adds nothing to the bar unless you switch on an optional icon.
Status (2026-11-05): everything on the roadmap is built and tested except a visual editor for custom positions and the marketplace listing. The checks that need a person at the machine are in docs/validation-checklist.md. Every claim in the docs says how it was checked.
- Keyboard (
CTRL + ALT): arrows for halves,U I J Kquarters,D F Gthirds,E Ttwo thirds,Returnmaximize (press it again to go back),Ccentre,Backspacerestore the size from before the first snap.SUPER + CTRL + ALTwithLeftorRightsends the window to the previous or next monitor. - Drag (hold
SUPERand drag with the left mouse): an outline shows the target, in the colour of your theme's window border; let go to snap. Corners give quarters, left and right edges halves, the top edge maximizes, the bottom edge gives thirds (slide along it for two thirds). On a vertical screen the side edges give thirds. Dragging a snapped window away gives it its old size back. - Grid zones (from PowerToys FancyZones): hold
SUPER + SHIFTand drag (or pressSHIFTin the middle of aSUPERdrag), and the screen shows a grid that fits the screen by default (two columns on a laptop, a 25/50/25 split on an ultrawide), or the columns, rows or rectangles you choose, one layout per monitor or workspace. Let go in a cell and the window fills it; near the line between two cells it fills both.CTRL + ALT + ]and[step a window through the cells. A Layouts page in the settings window edits them visually (split, drag dividers, merge, free rectangles), assigns one per monitor or per workspace, and shows a layout on your screen before you use it. See docs/config.md. - No shadow over the bar: a window as tall as the screen loses its shadow, which would fall over the bar. A shorter window gets it back.
- Gaps between snapped windows (8 pixels by default, none against the screen border), space kept free for a dock.
- Your own positions and shortcuts, an ignore list of apps, and the look of the outline, all in
~/.config/omagnet/config.tomlor in the settings window. See docs/config.md.
Anything that is not a floating-workspace window is left alone, and a key pressed in one goes on to the app.
Tested on Omarchy 4.5.0-3 with Hyprland 0.56.2 and Quickshell 0.3.2 (the versions Omarchy ships). It needs:
- Omarchy 4.5 or newer, for floating workspaces and the plugin system
- Hyprland's Lua config API (
hyprland.lua), which embeds Lua 5.5 - Quickshell (
qs), already part of Omarchy, for the drag outline and the settings window - Nothing else to install. No native module, no extra packages. It writes one file,
~/.config/omagnet/config.toml, and never edits your Hyprland config.
-
Add the plugin (the settings app, and the repo's Lua module comes with it):
omarchy plugin add https://github.com/felipecpaiva/omagnet --enable omarchy restart shell # once: a plugin added while the shell runs is not built properly until thenIt adds a launcher entry, "omagnet". It adds nothing to the bar. Omarchy's theme picker opens whenever the shell restarts; press
Escapeto close it. -
Load the snapping module. Installing a plugin does not edit your Hyprland config, so add one line to the end of
~/.config/hypr/hyprland.lua, then runhyprctl reload:pcall(dofile, os.getenv("HOME") .. "/.config/omarchy/plugins/io.github.felipecpaiva.omagnet/lua/omagnet-snap.lua")
The
pcallmeans a missing or broken file never breaks the rest of your config. To remove it, delete the line. -
Switch a workspace to floating mode (
Super + Lcycles the layouts) and tryCtrl + Alt + Left.
Remove: delete the line above, then omarchy plugin remove io.github.felipecpaiva.omagnet.
Open "omagnet" from the launcher, or run omarchy-shell shell toggle io.github.felipecpaiva.omagnet. Changes are saved
as you make them. Spacing, zones, switches, the ignore list and the outline look apply to the next snap. A changed
shortcut needs hyprctl reload, and the window has a button for it. The file it edits keeps anything it does not know,
so anything it does not edit is never lost.
Custom positions have their own editor: each existing one shows a thumbnail, its shortcut field and a delete button, and "Add position" gives a 24 by 14 grid where you press and drag to pick the size and place, like Magnet's. Click a thumbnail to change that position. A new or re-keyed shortcut needs the Hyprland reload; a changed rectangle applies live.
"Show an icon in the bar" adds a small button that opens the settings window. Off (the default), the bar looks exactly as it did before. The plugin declares a bar widget so Omarchy can place one, and the widget hides itself with zero size.
manifest.json, SettingsPanel.qml, SettingsStore.qml, Service.qml, BarWidget.qml, ConfigIO.js, Paths.js, omagnet.desktop
the settings plugin (the repo root is the plugin, as Omarchy's installer and marketplace expect)
lua/ the snapping module: geometry.lua, config.lua, omagnet-snap.lua, preview.qml, and its unit tests
tests/ run-all.sh, live tests (virtual keyboard, mouse and monitor), the Node test, scrub.sh
docs/ roadmap, architecture, settings, gotchas, history, research
| Document | What it holds |
|---|---|
| docs/launch/ | Release notes, marketplace listing text, repo settings to apply, where each image goes |
| docs/architecture.md | The parts, how they talk, the approaches compared and why these were chosen |
| docs/ROADMAP.md | Every function, its status, the rules, the batch order |
| docs/validation-checklist.md | What only a person can check, as ticks, about ten minutes |
| docs/config.md | Every setting, the default shortcuts and the drag zones |
| docs/gotchas.md | The traps found while building it (Hyprland Lua 5.5, key strings, maximized windows, shell caching) |
| docs/batch-log.md | What each batch changed, its tests and results |
| docs/magnet-reference/ | What Magnet does, from its website and store screenshots |
| docs/research/ | Existing snappers, Omarchy's community, what Hyprland can do, how plugins are built |
bash tests/run-all.sh --no-live # unit tests, the Hyprland glue with a fake hl, scrub, Node test, plugin validation
bash tests/run-all.sh # also the live test: real key and mouse events on a throwaway window (about 2 minutes)
python3 tests/live_displays.py # adds a temporary virtual monitor (about 30 seconds)
python3 tests/live_overlay.py # the drag overlay settings, with a screenshot
Run the Lua tests with Lua 5.5, the version Hyprland embeds: 5.4 accepts code that 5.5 rejects. The live tests drive your real keyboard, mouse and focus, so keep your hands off the machine while they run. The same is true of Omarchy's theme picker: it opens when its shell reloads and takes keyboard focus, so close it before a live run.
- Magnet (macOS) is the quality bar. Every function gets ported or a written reason why not.
- Floating workspaces only. Tiled and scrolling workspaces are never touched.
- Nothing on the Omarchy bar by default. The icon is an option.
- No native code.
- Public repo: no LAN addresses, hostnames, home paths or client names.
tests/scrub.shchecks before every push.
MIT license.
omagnet is an independent project. It is not affiliated with or endorsed by Omarchy, or by Magnet or its makers (BOOTCODE A.S.). "Magnet-style" describes what it does; the names belong to their owners.


