Omarchy in depth: extend it without breaking updates, and five 'bugs' that are not

Level IntermediateEstimated time 1 hRead first A second-hand laptop as a comfortable Linux workstation (Omarchy)A word you don't know? Glossary

Omarchy is an opinionated setup of Arch Linux and the Hyprland window manager: install it and you have a fast, keyboard-driven workstation. It updates often, and its updates overwrite its own files. The rule that follows: change nothing in its folders, extend from yours. And when something looks broken, look for the cause before reinstalling.

What you get. Your own entries in Omarchy's menu that survive every update, and the diagnosis of five strange behaviours in one line each, instead of the evenings they cost us.

1. Extend the menu from your folder

The packaged menu (/usr/share/omarchy/default/omarchy/omarchy-menu.jsonc) is to be read, never edited: the next update rewrites it. Your entries go in ~/.config/omarchy/extensions/omarchy-menu.jsonc:

{
  "setup.default.agent.openfox": {
    "icon": "", "label": "OpenFox",
    "description": "Local coding agent",
    "action": "omarchy launch webapp https://openfox.lan"
  }
}

The identifier is a dotted path, and its parent is the menu: setup.default.agent.openfox lands in the "Default Agent" submenu. Reusing an existing identifier extends that entry instead of replacing it. omarchy menu refresh reloads.

The "default agent" setting only knows binaries launched in a terminal, from a fixed list. A web app can be added to the menu, not made the default.

2. "100 % brightness" and a dark screen

On our laptop's panel, the driver overflows near the top: above about 60,300 out of 65,535, the value wraps to 0 and the screen drops to its minimum. "100 %" was the darkest setting. The fix stays in user space: a small script that caps the raw value at 60,200, and the brightness keys rebound to it.

Probe value by value (/sys/class/backlight/*/brightness, then read actual_brightness) before blaming the desktop.

3. The bar that vanished, even after reboot

The top bar is not dead: a flag on disk, ~/.local/state/omarchy/toggles/bar-off, slides it off screen, and it survives reboots by design. It is set by one menu entry, easy to pick by accident with the keyboard. The command is inverted, which costs a round trip:

omarchy toggle bar off      # brings the bar BACK

4. Four title bars, four owners

What you see	Who draws it	What removes it
a frame around a window	Hyprland	`general:border_size = 0`
an address bar over a pop-up	the browser, inside the page	nothing from the page
a title bar on an app window	Chromium, inside its surface	`--disable-features=WaylandWindowDecorations`
a title bar on an installed web app	Chromium, because of `display: standalone`	`"display_override": ["window-controls-overlay"]` in the manifest

The way you open the app decides which you get: an --app=URL launcher has no bar; the installed app's icon has one until its manifest asks otherwise. Chromium caches the manifest: restart it to see the change.

5. Transparency that makes text milky

Hyprland's window opacity applies to the whole window: the compositor receives a finished image and cannot tell the background from the text. Everything goes milky. For a see-through background with sharp text, set the opacity in the application itself (the terminal's own background opacity), and leave the compositor at 1.0.

Traps

Never restart the terminal service from inside a terminal session you care about: it closes every terminal, including the one running your agent.

A key-sending tool types text; it does not trigger Hyprland shortcuts. To test a menu without seeing the screen, summon it by command, type the search, and take a screenshot.

Sources

Found this useful? Tell us what to measure next.