dotfiles/omarchy/README.md

Omarchy customization layer

A layered installer that sets up Omarchy (Arch + Hyprland) with these dotfiles and an opinionated set of removals and swaps. It does not fork Omarchy — it patches the package list before Omarchy's own installer runs, then layers customizations on top using Omarchy's documented extension points, so it survives omarchy-update.

Environment required

This is a full system installer, not a sandbox-safe script. Run it only on a machine you intend to set up as an Omarchy workstation.

• OS: a fresh Arch Linux install (x86_64). The script aborts if /etc/arch-release is absent. Arch derivatives (EndeavourOS, CachyOS) are untested.
• State: ideally a clean Arch base — Omarchy's installer reconfigures bootloader, login (SDDM/Limine), services, and the graphics stack. Existing configs at the symlink targets are backed up to *.pre-omarchy.<timestamp>, not deleted.
• Privileges: a regular user with sudo rights (do not run as root). The installer will prompt for sudo and change your login shell to zsh.
• Network: outbound HTTPS to GitHub, the Arch/AUR mirrors, the Omarchy mirror, and brave.com (Brave Origin Beta). A working pacman mirrorlist.
• Required commands: git and sudo (preflight checks these). curl is used for the optional nvm install; everything else is installed by Omarchy.
• Hardware: designed around a single 3440×1440 @ 120Hz ultrawide (see files/hypr-monitors.lua); adjust that file for other displays.
• Time/space: expect a long run (full desktop + AUR builds) and several GB of downloads.

Heads-up: there is no unattended/dry-run mode. Omarchy's own installer is interactive in places. Don't run this on a daily-driver you can't reimage.

Installation

On a fresh Arch Linux system, as your normal (non-root) user:

# 1. Clone these dotfiles
git clone https://github.com/brianpooe/dotfiles.git ~/dotfiles

# 2. Run the installer (clones Omarchy, installs it, applies the layer)
~/dotfiles/omarchy/install.sh

# 3. Reboot (or log out and back in) to start the zsh + Hyprland session

Re-apply just the customization layer after an omarchy-update — this skips the Omarchy core install and only re-applies removals/swaps/symlinks/overrides:

~/dotfiles/omarchy/install.sh --layer-only
~/dotfiles/omarchy/install.sh --help   # show usage

Configuration (environment variables)

Variable	Default	Purpose
OMARCHY_REPO	basecamp/omarchy	Omarchy source repo (owner/name)
OMARCHY_REF	master	Omarchy branch/tag to install
OMARCHY_PATH	~/.local/share/omarchy	Where Omarchy is cloned
DOTFILES_DIR	repo root (auto-detected)	Source dir for symlinks
DEFAULT_FONT	JetBrainsMono Nerd Font	System monospace font
NVM_VERSION	v0.40.1	Pinned nvm release

Example — install a specific Omarchy tag with a different font:

OMARCHY_REF=v3.0.0 DEFAULT_FONT="CaskaydiaMono Nerd Font" \
  ~/dotfiles/omarchy/install.sh

What it does

1. Clones Omarchy to ~/.local/share/omarchy (override with OMARCHY_REPO / OMARCHY_REF).
2. Patches the package list (lib/packages.sh) before Omarchy installs.
3. Runs Omarchy's own installer (install.sh) for the full system setup.
4. Applies the layer: Brave Origin Beta as default browser, WezTerm as default terminal, dotfile deps + symlinks, and menu/theme overrides.

Changes vs. upstream Omarchy

Packages removed (from install/omarchy-base.packages)

Category	Packages
Shell tools	tobi-try (the try tool)
TUIs	lazydocker, cliamp (Clamp)
GUIs	obsidian, pinta, signal-desktop, obs-studio, kdenlive
Commercial apps	1password-beta, 1password-cli, spotify, typora, libreoffice-fresh
Browser	chromium (replaced by Brave Origin Beta)

Note: current Omarchy has no "Commercial apps" menu — the commercial items are base packages, so they are removed from the package list.

• Default web apps (frameless PWA wrappers): install/packaging/webapps.sh is cleared, so none are installed.
• Lazydocker TUI entry removed from install/packaging/tuis.sh (Disk Usage kept).

Browser

• Brave Origin Beta (https://brave.com/origin/linux/beta/) installed via Omarchy's native omarchy-install-browser brave-origin (AUR package brave-origin-beta-bin) and set as default with omarchy-default-browser.
• Because omarchy-launch-webapp routes through the default browser, removing Chromium is safe once Brave Origin is the default.

Terminal

• WezTerm installed and set as the default terminal by writing ~/.config/xdg-terminals.list (desktop id org.wezfurlong.wezterm.desktop). Omarchy's Super+Return runs xdg-terminal-exec, which honors that file.
• WezTerm follows the active Omarchy theme: .config/wezterm/wezterm.lua reads ~/.config/omarchy/current/theme/colors.toml (the palette Omarchy generates for every theme), falling back to Kanagawa Wave when Omarchy is absent. A theme-set hook (~/.config/omarchy/hooks/theme-set.d/wezterm) bumps the config mtime after a theme switch so WezTerm live-reloads.

Menu (Super + Alt + Space)

Overrides are installed to ~/.config/omarchy/extensions/menu.sh (sourced by omarchy-menu after its functions are defined, so the redefinitions win):

• Setup — removed: System Sleep, DNS, Security (kept: Audio, Wifi, Bluetooth, Power Profile, Monitors, Keybindings, Input, Defaults, Config).
• Install — removed: Web App, TUI, Service, Development, Editor, Terminal, Browser, AI, Gaming, Windows (kept: Package, AUR, Style).

The removed submenu functions still exist in Omarchy but are unreachable from the launcher. Regenerate files/menu.sh from upstream if Omarchy's menu changes.

Theming model

Terminal and editor colors are decoupled by design (Option A):

• WezTerm follows whatever Omarchy theme is active.
• Neovim / tmux / starship stay on Kanagawa via the dotfiles' KANAGAWA_THEME env chain in .zshrc, independent of Omarchy. (WEZTERM_THEME from that chain is now unused.)

Files

File	Purpose
install.sh	Entry point / orchestration
lib/common.sh	Helpers (logging, symlink-with-backup, paths)
lib/packages.sh	Patches Omarchy's package list / webapps / tuis
lib/browser.sh	Brave Origin Beta install + default
lib/terminal.sh	WezTerm install + default terminal
lib/dotfiles.sh	Dotfile deps (zsh, plugins, tpm, nvm) + symlinks
lib/font.sh	Sets the default font (JetBrainsMono Nerd Font)
lib/overrides.sh	Installs menu overrides + WezTerm theme hook
files/menu.sh	Menu overrides (symlinked into Omarchy)
files/theme-set-wezterm	Theme-switch hook that reloads WezTerm
files/hypr-wezterm.lua	Hyprland rule tagging WezTerm as a terminal
files/hypr-monitors.lua	Monitor config: 3440x1440@120 ultrawide, 1x scale