Advanced Omarchy Customization for Hyprland, Bar, and Themes

Maintainable Omarchy customization uses user-level overrides, changes one variable at a time, and keeps a rollback record. Paths and Lua, TOML, or JSON structures can change, so the installed files and current official manual take precedence over an old guide.

Establish a baseline

1. Record the active theme, terminal, editor, and update channel.
2. Copy each user file before changing it and date the copy.
3. If configuration is tracked by Git, commit a clean baseline.
4. Prove that you can enter a TTY or restore a known-good config.
5. Change one subsystem and verify it again after a fresh login.

Do not edit package-managed defaults under /usr/share/omarchy. User overrides normally live under ~/.config; the file opened by the current Omarchy menu is the safest source.

Hyprland appearance and layout

Current Omarchy separates monitor and appearance rules into Lua files such as ~/.config/hypr/monitors.lua and ~/.config/hypr/looknfeel.lua. These control gaps, borders, rounding, and default layout.

The official Common Tweaks page uses the hl.config structure in looknfeel.lua for rounding and gaps. Do not mix an old hyprland.conf snippet into a Lua file. Read the installed commented example and use hyprctl to verify syntax and runtime state.

Workspaces can switch between dwindle and scrolling layouts. Try the temporary per-workspace toggle before making either one the default.

Custom keybindings

Confirm the existing action and conflicts in the system Hotkeys help, then open the user binding entry for your installed release. Record modifier, key, action, description, and any input-method or app conflict.

Safety rules:

• Preserve menu, terminal, window-close, and recovery access.
• Do not bind deletion or power actions to an easy accidental chord.
• Test Mac keyboards and multilingual layouts on the actual hardware.
• Hot-reload, then log out or reboot and test again.
• Give every override a one-sentence purpose.

Bar and Quickshell

The bar supports drag placement and widget reordering, plus CLI control:

omarchy bar position bottom
omarchy bar transparent toggle
omarchy plugin list

The current custom layout lives in ~/.config/omarchy/shell.json. Once it exists, it is a complete canonical config rather than a deep-merge patch, so new shipped widgets may not appear automatically. Back it up before restoring defaults:

omarchy bar defaults

Build a custom theme

Copy an existing theme from /usr/share/omarchy/themes to ~/.config/omarchy/themes/<name>, then edit colors.toml. Its palette generates configuration for terminals, btop, Chromium, Hyprland, Neovim, Helix, VS Code, Obsidian, and the Omarchy Shell.

Validate:

• contrast for prose, links, focus, and errors;
• terminal 16-color palette and selected text;
• mode = "light" for a light theme;
• wallpaper copyright and distribution license;
• multiple monitors, lock screen, and active states.

Omarchy filters some executable or high-risk files when installing a third-party theme, but you should still review its repository, license, and maintenance.

Theme an uncovered application

Place .tpl templates under ~/.config/omarchy/themed/ to generate app configuration from palette placeholders. A user template can override a shipped one. Start from the official sample, verify the target path, then test both theme switching and rollback.

Maintain after an update

An update may preserve a conflicting user config as a .bak file. Compare the new default, your file, and the backup line by line. Use Update → Config for a single damaged default, and read snapshots and recovery for broader failures.

Sources: Common Tweaks, Making Your Own Theme, and The Top Bar.