Make Omarchy Your Own

A companion to Systems for Humans — Omarchy Fieldwork, OMA-02. Production experiment recorded 11 September 2026. Companion to the published episode.

The useful connection is source palette → installed templates → generated application configuration → visible interface. We built a light theme, made the selected menu row stronger, tested a shell restart, and restored the original theme.

1. Check your installation

This experiment used a disposable VM derived from our previous widget lab, not a clean stock installation. Package versions were Omarchy 4.0.2-1, Hyprland 0.56.2-1, Foot 1.27.0-2 and Neovim 0.12.5-1. The bundled /usr/share/omarchy/version contained 4.0.0.alpha; this discrepancy is preserved in the evidence. Other releases can have different commands and files.

pacman -Q omarchy hyprland foot neovim
omarchy theme current
ls /usr/share/omarchy/default/themed

Read the official theme manual and compare it with your installed tools. This guide targets the named-token colors.toml format and the installed shell.<section>.toml override mechanism we inspected.

2. Save a way back

Choose a new backup directory. The exclusive mkdir stops this sequence from overwriting an existing baseline.

backup="$HOME/aow-theme-backup"
mkdir "$backup" && {
  omarchy theme current > "$backup/theme-name.txt"
  cp -a "$HOME/.local/state/omarchy/current/theme" "$backup/generated-theme"
  readlink "$HOME/.local/state/omarchy/current/background" > "$backup/background-path.txt"
}

Keep a screenshot of the original terminal and menu. Our original theme was Tokyo Night. Use your own recorded theme name for recovery; the command later in this guide is specific to our lab. A theme backup is not a backup of your personal files or the whole operating system.

3. Give the agent a bounded job

Our recorded prompt asked Codex to create a new user-owned aow-workshop folder inside ~/.config/omarchy/themes, inspect the installed format, use ivory #F5F0E3, ink #242D2B, teal #28767A and restrained amber #D49A35, check readable text pairs, avoid packaged-default changes, and wait before applying. Authentication happened off camera. No credentials belong in the theme archive.

You can use the included theme without an agent: inspect it, then copy the supplied aow-workshop directory into ~/.config/omarchy/themes/. Stop if that destination already exists and compare versions rather than overwriting it. The downloaded folder is a local copy; do not assume all remote-theme installation paths accept executable files such as a validator. The color and wallpaper files are the theme itself.

4. Read the source connection

The primary file contains named roles:

mode = "light"
accent = "#28767A"
background = "#F5F0E3"
foreground = "#242D2B"

Our actual file has additional selection, muted and ANSI colors. In the installed Foot template, background={{ background_strip }} becomes background=F5F0E3 in ~/.local/state/omarchy/current/theme/foot.ini. The _strip suffix removes the leading hash. Theme selection regenerates these files, so make persistent changes in the source theme.

backgrounds/aow-workshop.svg is original vector artwork; the bundled PNG is the wallpaper. shell.menu.toml and shell.launcher.toml override only those sections, retaining generated defaults elsewhere.

5. Check colors before applying

Our validator runs installed templates in a temporary folder inside the theme. It does not call theme-set. Inspect it before running:

cd "$HOME/.config/omarchy/themes/aow-workshop"
python3 validate.py

It rendered 17 installed templates, parsed TOML/JSON and checked 60 specified text pairs. Ink/ivory is 12.43:1; teal/ivory is 4.66:1; brand amber/ivory is 2.18:1. We kept amber decorative and used darker ochre for warning text. These checks do not certify arbitrary ANSI combinations, transparent surfaces, every editor plugin or the entire desktop.

6. Apply and compare the same surfaces

omarchy theme set aow-workshop

The command changed the wallpaper, top bar, terminal and border without rebooting in our test. Open the same menu, notification and editor content to compare. We used Foot with a 14-point font for recording. Neovim's initial launch performed parser setup; that was a first-run editor event, separate from theme generation. Our capture input initially dropped a tilde in an editor path; reopening with the full absolute path corrected the test without saving anything.

7. Make one small refinement

After seeing the root menu, we requested a stronger selected-row fill. The two functional changes were:

# shell.menu.toml and shell.launcher.toml
-selected-background-alpha = 0.08
+selected-background-alpha = 0.16

Ink text stayed unchanged. Reapplying the same theme regenerated the overrides and visibly darkened the selected Apps row. The static selected-row contrast remained 9.25:1. The archive includes both revisions and their exact diff. The runtime observation is of the menu; the launcher's override was validated in generated configuration, not separately exercised on screen.

8. Test persistence and restore

omarchy restart shell
omarchy theme current
# Open the menu and a fresh terminal again.
omarchy theme set tokyo-night

After shell restart, the AOW selection fill persisted. A new terminal also used the AOW palette. After restoring Tokyo Night, the terminal, menu and reopened editor returned to its colors. A recursive comparison of generated theme files against our saved baseline found no differences; the original wallpaper path returned, and packaged-theme checksums were unchanged. The custom theme remained in its own folder.

We did not test a full reboot, all applications, other hardware, remote installation or every accessibility interaction. If your original theme had a different wallpaper choice, restore that saved background explicitly and compare it; theme selection alone should not be assumed to restore every personal preference.

Results

Surface / transition	Observed result
Foot, top bar, active border, wallpaper	Changed after apply
Root menu and notification	AOW palette visible
Neovim	Palette visible when file reopened
Menu selection refinement	Stronger fill visible after reapply
Shell restart / fresh terminal	AOW appearance persisted
Tokyo Night restore	Generated files matched saved baseline
Packaged themes	Checksums unchanged
Full reboot, all apps and hardware	Not tested

The recording preserves the real build and troubleshooting. The narrated edit uses selected excerpts, enlarged details and explicitly labeled pauses for explanation. No desktop behavior is simulated.

Verification commands from the lab

Before the change, we saved the generated theme directory and a checksum inventory of packaged themes. After selecting Tokyo Night again, we ran:

# Lab paths: use the backup path you actually created.
diff -qr "$HOME/aow-theme-evidence/original-generated" \
  "$HOME/.local/state/omarchy/current/theme"
sha256sum -c "$HOME/aow-theme-evidence/packaged-themes.sha256"
readlink "$HOME/.local/state/omarchy/current/background"

The diff emitted no differences. Every packaged-theme checksum matched. The final background symlink target equaled the saved target. The recording shows the UI restore; these additional file checks ran through the lab control connection and are preserved as separate evidence.