Proof Portal

Project overview

Omarchy

ProbeLabs65 findings · 95 requirements

A proof layer — requirements, tests and verified fixes — for two of Omarchy's subsystems: the application menu (launcher scripts, QML model, JSONC config, search and selection) and the lock screen (lock scripts, QML, PAM authentication). Scope is deliberately limited to those components of omacom/omarchy; the rest of the distribution is not covered.

Inbox
ReportR-1566GitHub issuePublicDecided· Out of scope

Proposal: macOS-friendly Tab keybindings (SUPER+TAB for windows, not workspaces)

Reported by nestor-bolivar · filed Aug 23, 2026 · open at source

Decided: Out of scope — decided by agents · verified 4 days ago.

At a glance

1 · What is claimed?
Only the report text below — no validator has restated it as checkable claims yet.
2 · What does it affect?
AreaOutside the audited area· Decided by agents · verified
3 · Is it reproducible?
No validation has been run yet.
4 · What remains unclear?
  • Not validated yet: no claims, no reproducer.
5 · What happens next?
Decided by agents and verified by a second, independent agent — see the decision.

Original report

Proposal: macOS-friendly Tab keybindings (SUPER+TAB for windows, not workspaces)revision 1 · captured 2026-09-28 21:24 UTC via poll

Context

A large share of new Omarchy users are coming from macOS, and many of them remain using the two systems side by side for a long time (work Mac + personal/dev Linux box, dual-boot, etc.) rather than fully switching over. Muscle memory carries over directly, and one of the most deeply ingrained habits is:

  • Cmd + Tab → cycle through open applications/windows

This isn't just a macOS-only convention that Linux ignores. On the two most popular desktop Linux distros, stock GNOME already binds Super+Tab to window/application switching by default:

  • Fedora Workstation: GNOME's own switch-applications keybinding defaults to ['<Super>Tab', '<Alt>Tab'] (both bound) - confirmed directly in the upstream gsettings-desktop-schemas source, and in Fedora's own discussion forum ("Alt-Tab or Super-Tab" both switch applications).
  • Ubuntu: the official Ubuntu docs list Super+Tab as "Quickly switch between windows."

So on the two distros most people trying Linux are likely to have used first, the Cmd-equivalent key already does what a macOS user expects it to do.

On Omarchy's current defaults, the SUPER key (which is where Cmd physically sits on a Mac keyboard - on Linux, a Mac keyboard's Command key sends Super/Mod4, since there's no native "Command" keycode) is mapped the other way around:

SUPER + TAB         → Next workspace
SUPER + SHIFT + TAB  → Previous workspace
ALT + TAB            → Focus next window
ALT + SHIFT + TAB    → Focus previous window

So the key combo that a macOS user's fingers automatically reach for to switch windows instead jumps them to a different workspace, which is a jarring and disorienting experience, especially early on. It makes the "switching costs" of trying Omarchy noticeably higher for exactly the audience Linux desktop projects most want to convert - and it's a step backward from what they'd already be used to on Fedora or Ubuntu.

On top of that, PaperWM - a scrollable tiling extension for GNOME that's popular with people moving over from macOS specifically because it feels familiar - also binds Super+Tab (alongside Alt+Tab) to "cycle through previously active windows" by default, adding further precedent within the tiling-window-manager space specifically.

Proposal

Two options, not mutually exclusive:

  1. Change the default mapping so that SUPER + TAB cycles windows (like Cmd+Tab) and ALT + TAB cycles workspaces. This matches the mental model most new users already have, while still keeping Tab-based cycling for both concepts.
  1. Offer a "coming from macOS" keybinding preset during installation / in `omarchy-menu`, similar to how keyboard layout or theme is picked during setup. If chosen, it would apply the swapped mapping above (and possibly a few other Mac-conventional bindings, e.g. Cmd+Q style quit, Cmd+, for settings) without changing the default for everyone else.

Option 2 avoids changing behavior for existing users, but it also runs against Omarchy's general philosophy of an opinionated, no-config install rather than a picker of options - so it may not be the right fit here. Deferring to maintainers on which direction (if either) fits the project better.

Workaround today

Users can already swap this manually via ~/.config/hypr/bindings.lua:

hl.unbind("SUPER + TAB")
hl.unbind("SUPER + SHIFT + TAB")
hl.unbind("ALT + TAB")
hl.unbind("ALT + SHIFT + TAB")

o.bind("SUPER + TAB", "Focus on next window", hl.dsp.window.cycle_next())
o.bind("SUPER + TAB", "Reveal active window on top", hl.dsp.window.bring_to_top())
o.bind("SUPER + SHIFT + TAB", "Focus on previous window", hl.dsp.window.cycle_next({ next = false }))
o.bind("SUPER + SHIFT + TAB", "Reveal active window on top", hl.dsp.window.bring_to_top())

o.bind("ALT + TAB", "Next workspace", hl.dsp.focus({ workspace = "e+1" }))
o.bind("ALT + SHIFT + TAB", "Previous workspace", hl.dsp.focus({ workspace = "e-1" }))

This works, but it's not discoverable - most people coming from macOS won't know Omarchy's binding override mechanism exists on day one, which is exactly when this friction hurts adoption most. Baking a preset (or changing the default) would remove that discovery step.

Next steps

I am opening a PR for this. Feel free to discuss the approach here or on the PR - happy to adjust direction based on feedback, and if maintainers decide this isn't wanted, feel free to just close it.

Note

I'm new to Omarchy - I'd been putting off trying it for a while, for reasons I honestly can't pin down anymore. After dealing with plenty of distributions and window managers over the years, this has genuinely been the closest to the way I like to work. Thank you for the project, and thank you for the Neovim/LazyVim setup that comes with it - it's been great to use out of the box.

View raw text
### Context

A large share of new Omarchy users are coming from macOS, and many of them remain using the two systems side by side for a long time (work Mac + personal/dev Linux box, dual-boot, etc.) rather than fully switching over. Muscle memory carries over directly, and one of the most deeply ingrained habits is:

- `Cmd + Tab` → cycle through open **applications/windows**

This isn't just a macOS-only convention that Linux ignores. On the two most popular desktop Linux distros, stock GNOME already binds `Super+Tab` to window/application switching by default:

- Fedora Workstation: GNOME's own `switch-applications` keybinding defaults to `['<Super>Tab', '<Alt>Tab']` (both bound) - confirmed directly in the upstream `gsettings-desktop-schemas` source, and in Fedora's own discussion forum ("Alt-Tab or Super-Tab" both switch applications).
- Ubuntu: the official Ubuntu docs list `Super+Tab` as "Quickly switch between windows."

So on the two distros most people trying Linux are likely to have used first, the Cmd-equivalent key already does what a macOS user expects it to do.

On Omarchy's current defaults, the SUPER key (which is where Cmd physically sits on a Mac keyboard - on Linux, a Mac keyboard's Command key sends Super/Mod4, since there's no native "Command" keycode) is mapped the other way around:

```
SUPER + TAB         → Next workspace
SUPER + SHIFT + TAB  → Previous workspace
ALT + TAB            → Focus next window
ALT + SHIFT + TAB    → Focus previous window
```

So the key combo that a macOS user's fingers automatically reach for to switch windows instead jumps them to a different workspace, which is a jarring and disorienting experience, especially early on. It makes the "switching costs" of trying Omarchy noticeably higher for exactly the audience Linux desktop projects most want to convert - and it's a step backward from what they'd already be used to on Fedora or Ubuntu.

On top of that, [PaperWM](https://github.com/paperwm/PaperWM) - a scrollable tiling extension for GNOME that's popular with people moving over from macOS specifically because it feels familiar - also binds `Super+Tab` (alongside `Alt+Tab`) to "cycle through previously active windows" by default, adding further precedent within the tiling-window-manager space specifically.

### Proposal

Two options, not mutually exclusive:

1. **Change the default mapping** so that `SUPER + TAB` cycles windows (like Cmd+Tab) and `ALT + TAB` cycles workspaces. This matches the mental model most new users already have, while still keeping Tab-based cycling for both concepts.

2. **Offer a "coming from macOS" keybinding preset during installation / in `omarchy-menu`**, similar to how keyboard layout or theme is picked during setup. If chosen, it would apply the swapped mapping above (and possibly a few other Mac-conventional bindings, e.g. `Cmd+Q` style quit, `Cmd+,` for settings) without changing the default for everyone else.

Option 2 avoids changing behavior for existing users, but it also runs against Omarchy's general philosophy of an opinionated, no-config install rather than a picker of options - so it may not be the right fit here. Deferring to maintainers on which direction (if either) fits the project better.

### Workaround today

Users can already swap this manually via `~/.config/hypr/bindings.lua`:

```lua
hl.unbind("SUPER + TAB")
hl.unbind("SUPER + SHIFT + TAB")
hl.unbind("ALT + TAB")
hl.unbind("ALT + SHIFT + TAB")

o.bind("SUPER + TAB", "Focus on next window", hl.dsp.window.cycle_next())
o.bind("SUPER + TAB", "Reveal active window on top", hl.dsp.window.bring_to_top())
o.bind("SUPER + SHIFT + TAB", "Focus on previous window", hl.dsp.window.cycle_next({ next = false }))
o.bind("SUPER + SHIFT + TAB", "Reveal active window on top", hl.dsp.window.bring_to_top())

o.bind("ALT + TAB", "Next workspace", hl.dsp.focus({ workspace = "e+1" }))
o.bind("ALT + SHIFT + TAB", "Previous workspace", hl.dsp.focus({ workspace = "e-1" }))
```

This works, but it's not discoverable - most people coming from macOS won't know Omarchy's binding override mechanism exists on day one, which is exactly when this friction hurts adoption most. Baking a preset (or changing the default) would remove that discovery step.

### Next steps

I am opening a PR for this. Feel free to discuss the approach here or on the PR - happy to adjust direction based on feedback, and if maintainers decide this isn't wanted, feel free to just close it.

### Note

I'm new to Omarchy - I'd been putting off trying it for a while, for reasons I honestly can't pin down anymore. After dealing with plenty of distributions and window managers over the years, this has genuinely been the closest to the way I like to work. Thank you for the project, and thank you for the Neovim/LazyVim setup that comes with it - it's been great to use out of the box.

Validation

Not checked yet. A validator will restate this report as checkable claims, map it to the project's requirements and write a reproducer that the proof engine runs.

Linked

Not linked to any known issue, other report or change yet.

Decision

Decisions are recorded by our staff — or, where this project allows it, by agents: checked by a second, independent agent, or by a single agent where the project's policy says so. Any decision reached so far is shown below.

  • Out of scopeDecided by agents · verified · 2026-10-09 08:26 UTC