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-1461GitHub issuePublicDecided· Out of scope

omarchy theme set / omarchy update hangs indefinitely in omarchy-theme-set-keyboard-f16 with a Keychron K8 Pro attached

Reported by ykzird · filed Aug 25, 2026 · open at source

Decided: Out of scope — decided by agents · verified 5 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

omarchy theme set / omarchy update hangs indefinitely in omarchy-theme-set-keyboard-f16 with a Keychron K8 Pro attachedrevision 1 · captured 2026-09-28 21:24 UTC via poll

System details

AMD Ryzen 7 9700X, AMD Radeon RX 6800 XT, Omarchy 4.0.1-1, kernel 7.1.8-arch1-3, Hyprland 0.56.2, qmk-hid 0.1.11-3 (explicitly installed), keyboard: Keychron K8 Pro (QMK/VIA firmware)

What's wrong?

What's wrong?

With a Keychron K8 Pro (QMK/VIA keyboard) attached over USB, every omarchy theme set <theme> blocks forever after printing a single line (Effect: 1). Because the 4.0.1 update migration 1787481315 re-stages the current theme via omarchy-theme-refresh, omarchy update wedged at that migration on every retry until I unplugged the keyboard — it looked like a bricked update.

Process tree while stuck (two independent instances, same spot)

bash -lc 'theme=$(omarchy-theme-switcher); ... omarchy-theme-set "$theme"'
└─ omarchy-theme-set tokyo-night
   └─ omarchy-theme-set-keyboard
      └─ omarchy-theme-set-keyboard-f16      <- STAT do_wait
         └─ qmk_hid via --rgb-hue 212        <- never exits

Steps to reproduce

  1. Attach a Keychron K8 Pro over USB
  2. Run omarchy theme set tokyo-night
  3. Observe: prints Effect: 1, then hangs forever
  4. Unplug the keyboard, re-run: completes immediately

Direct reproduction of the blocking call:

$ timeout 5 qmk_hid via --rgb-hue 100   # K8 Pro attached
[killed at timeout, exit 124]

Side note for anyone debugging this from user reports: the f16 script only redirects stderr of the qmk_hid calls, so qmk_hid's own stdout response (Effect: 1) lands in the terminal and reads like output from whatever step preceded the hang.

Context: qmk-hid was not preinstalled on my system — I added it manually while configuring the K8 Pro (pacman -S qmk-hid). omarchy-theme-set-keyboard-f16 then picked it up opportunistically and applied theme colors to the keyboard on every theme change. That is reasonable behavior; the problem is only that nothing bounds it.

Analysis

Neither keyboard theming script detects actual hardware. The entire guard in /usr/share/omarchy/bin/omarchy-theme-set-keyboard-f16 is:

if omarchy-cmd-present qmk_hid && [[ -f $FRAMEWORK16_THEME ]]; then

i.e. binary present + theme ships a keyboard.rgb, then fire five unbounded qmk_hid calls. Despite the name, nothing checks for a Framework 16 or any VIA device. The sibling omarchy-theme-set-keyboard-asus-rog has the identical pattern (asusctl present + rgb file) but gets away with it because asusctl fails fast on foreign hardware — qmk_hid instead blocks indefinitely on a non-responsive HID device.

(omarchy-debug is not available on my installed version to attach its output.)

Expected

Theme application completes (or the keyboard step fails fast) regardless of what other HID devices are attached.

Suggested fix

  • Wrap the five qmk_hid invocations in timeout, matching the pattern used elsewhere in Omarchy's scripts (e.g. shell_ipc() uses timeout 2).
  • Optionally verify an actual VIA-capable device responds before invoking qmk_hid.

Separately, qmk-hid itself hanging forever instead of erroring is arguably an upstream bug — happy to file there too.

View raw text
### System details

AMD Ryzen 7 9700X, AMD Radeon RX 6800 XT, Omarchy 4.0.1-1, kernel 7.1.8-arch1-3, Hyprland 0.56.2, qmk-hid 0.1.11-3 (explicitly installed), keyboard: Keychron K8 Pro (QMK/VIA firmware)

### What's wrong?

# What's wrong?
With a Keychron K8 Pro (QMK/VIA keyboard) attached over USB, every `omarchy theme set <theme>` blocks forever after printing a single line (`Effect: 1`). Because the 4.0.1 update migration `1787481315` re-stages the current theme via `omarchy-theme-refresh`, `omarchy update` wedged at that migration on every retry until I unplugged the keyboard — it looked like a bricked update.

## Process tree while stuck (two independent instances, same spot)

```
bash -lc 'theme=$(omarchy-theme-switcher); ... omarchy-theme-set "$theme"'
└─ omarchy-theme-set tokyo-night
   └─ omarchy-theme-set-keyboard
      └─ omarchy-theme-set-keyboard-f16      <- STAT do_wait
         └─ qmk_hid via --rgb-hue 212        <- never exits
```

## Steps to reproduce

1. Attach a Keychron K8 Pro over USB
2. Run `omarchy theme set tokyo-night`
3. Observe: prints `Effect: 1`, then hangs forever
4. Unplug the keyboard, re-run: completes immediately

Direct reproduction of the blocking call:

```
$ timeout 5 qmk_hid via --rgb-hue 100   # K8 Pro attached
[killed at timeout, exit 124]
```

Side note for anyone debugging this from user reports: the f16 script only redirects stderr of the qmk_hid calls, so qmk_hid's own stdout response (`Effect: 1`) lands in the terminal and reads like output from whatever step preceded the hang.

Context: qmk-hid was not preinstalled on my system — I added it manually while configuring the K8 Pro (`pacman -S qmk-hid`). `omarchy-theme-set-keyboard-f16` then picked it up opportunistically and applied theme colors to the keyboard on every theme change. That is reasonable behavior; the problem is only that nothing bounds it.

## Analysis

Neither keyboard theming script detects actual hardware. The entire guard in `/usr/share/omarchy/bin/omarchy-theme-set-keyboard-f16` is:

```bash
if omarchy-cmd-present qmk_hid && [[ -f $FRAMEWORK16_THEME ]]; then
```

i.e. binary present + theme ships a `keyboard.rgb`, then fire five unbounded `qmk_hid` calls. Despite the name, nothing checks for a Framework 16 or any VIA device. The sibling `omarchy-theme-set-keyboard-asus-rog` has the identical pattern (`asusctl` present + rgb file) but gets away with it because `asusctl` fails fast on foreign hardware — `qmk_hid` instead blocks indefinitely on a non-responsive HID device.

(`omarchy-debug` is not available on my installed version to attach its output.)

## Expected

Theme application completes (or the keyboard step fails fast) regardless of what other HID devices are attached.

## Suggested fix

- Wrap the five `qmk_hid` invocations in `timeout`, matching the pattern used elsewhere in Omarchy's scripts (e.g. `shell_ipc()` uses `timeout 2`).
- Optionally verify an actual VIA-capable device responds before invoking `qmk_hid`.

Separately, qmk-hid itself hanging forever instead of erroring is arguably an upstream bug — happy to file there too.

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 09:06 UTC