Omahub
← All plugins
S

Omatheme

by Sam Davies

Theme designer panel: edit the running theme's borders, window chrome, palette and backgrounds live, then fork, preview and publish it. Summon with: omarchy-shell shell toggle davies-sam.omatheme '{}' (or run: bin/omatheme).

GitHub Homepage

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
c28c885
Scanned
1 month ago

No potentially dangerous behavior detected in the analyzed commit.

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
c28c885
Reviewed
1 month ago

The plugin is a theme designer that edits user-owned theme files and Hyprland window settings. It validates inputs, writes only to user config directories, and does not touch system files. No malicious behavior, obfuscation, or hidden persistence was found.

  • Uses hyprctl eval to push live previews, but values are validated and constrained by the GUI.
  • Can download images from user-provided URLs via curl, but only into the user's theme directory.
  • Publish feature can push to a git remote, but only when the user explicitly provides a remote URL.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/Davies-Sam/omatheme --enable
Appearance #Hyprland #quickshell

Omatheme

A Quickshell app for designing an Omarchy Quattro theme in place — live on the desktop it is theming, painted from the very palette it edits.

It is built as a shell plus panels, switched by tabs that keep each panel's unsaved edits alive:

  • Border — the window border colors. Quattro derives every border from the active theme's colors.toml (hyprland_active_border / hyprland_inactive_border), and the same key feeds the bar, notifications and the lock screen, so a change lands everywhere at once. Dragging pushes the border straight into the running compositor with hyprctl eval (Quattro's Lua parser rejects hyprctl keyword); nothing is written until Apply.
  • Window — the chrome Hyprland owns rather than the theme: border width, corner rounding, gaps and opacity. Live preview via the same eval path; Apply persists to ~/.config/hypr/looknfeel.lua, touching only the six keys it owns and leaving the rest of that file byte-identical.
  • Palette — a swatch grid over the theme's color keys, with a live WCAG contrast readout for the selected key. Applying a palette regenerates the whole theme (omarchy theme set, too slow for live-on-drag), so edits collect behind an explicit Preview — which also re-skins the app itself, since it paints from the theme it edits. This panel also carries the authoring actions: a Dark/Light mode switch, the fork field, preview regeneration and publishing.
  • Backgrounds — a thumbnail grid over the theme's background set: click to apply, add from a local path or an image URL, remove. Curating what a theme ships lives here; cycling between backgrounds stays with Omarchy (SUPER + CTRL + SPACE). "Palette from this background" generates a candidate palette from the selected wallpaper and stages it in the Palette panel as pending edits — nothing touches disk until you judge the swatches and press Preview.
Border panel Window panel
Palette panel Backgrounds panel

Editing a stock theme never touches /usr/share/omarchy: writes land in a user overlay under ~/.config/omarchy/themes/<slug>/, which is Omarchy's documented override mechanism. The window scales with omarchy display text size, and panel content scrolls when a short screen or a big text scale leaves it no room.

Authoring a theme

The tool's second job is making a theme that can leave your machine:

  1. Fork a starting point in the Palette panel — a stock theme, or the one you're running.
  2. Backgrounds: add the wallpapers the theme should ship (they go into the fork's own backgrounds/, so publishing carries them).
  3. Palette: generate from a wallpaper, or edit by hand with the contrast hints; flip mode if you crossed the dark/light line.
  4. Regenerate previews so the theme switcher shows your fork's real face instead of its parent's (the capture briefly dodges the app's own window off-screen).
  5. Publish — the theme directory becomes a git repo with copy-pasteable next steps; anyone installs it with omarchy theme install <url>.

One inherited edge: forks copy their parent's neovim.lua / vscode.json / icons.theme, so a heavily recolored fork should have those edited by hand — they are editor configs, not palette entries.

Shell-first architecture

QML draws, shell scripts mutate. Every panel has an omatheme-<domain> helper with show / set / reset subcommands, so anything the GUI can do is also reachable and testable from a terminal:

omatheme-state                   # current theme, palette, font, text scale
omatheme-border show
omatheme-border set --active "rgba(33ccffee) rgba(00ff99ee) 45deg"
omatheme-window set --rounding 12 --gaps-in 4
omatheme-window reset --all
omatheme-palette set --accent "#ff9e64"
omatheme-palette mode light
omatheme-palette generate wallpaper.png --apply
omatheme-palette fork my-new-theme
omatheme-bg add https://example.com/wallpaper.jpg
omatheme-bg set wallpaper.jpg
omatheme-preview regen
omatheme-publish --push git@github.com:you/omarchy-my-new-theme-theme.git

Install

Omatheme is an Omarchy shell plugin — it runs as a panel inside the omarchy-shell process. It's listed on omarchyplugins.com, the community plugin directory.

omarchy plugin add https://github.com/Davies-Sam/omatheme.git --enable

External dependencies: Omarchy 4.0+ (Quattro), plus imagemagick (palette generation, previews, the boot logo) and inotify-tools (following external theme switches). jq and git are already Omarchy core dependencies.

Remove it the same way any shell plugin goes:

omarchy plugin remove davies-sam.omatheme

Removal disables the panel first and never touches your themes — the forks you made live in ~/.config/omarchy/themes/ and stay yours.

Then summon it:

omarchy-shell shell toggle davies-sam.omatheme '{}'

or bind that — in Quattro's ~/.config/hypr/bindings.lua:

hl.bind({ "SUPER", "SHIFT", "CTRL" }, "T", "exec",
  "omarchy-shell shell toggle davies-sam.omatheme '{}'")

and float it in ~/.config/hypr/hyprland.lua:

hl.window_rule({ float = true, match = { title = "^Omatheme$" } })

(Quickshell hardcodes the app-id org.quickshell for every surface, so rules must match on the title.)

Optional extras, for a launcher entry and terminal-friendly helpers — from the installed plugin directory:

PLUGIN=~/.config/omarchy/plugins/davies-sam.omatheme
ln -s "$PLUGIN/bin/omatheme" ~/.local/bin/omatheme
ln -s "$PLUGIN/share/applications/omatheme.desktop" ~/.local/share/applications/
mkdir -p ~/.local/share/icons/hicolor/scalable/apps ~/.local/share/icons/hicolor/256x256/apps
ln -s "$PLUGIN/share/icons/hicolor/scalable/apps/omatheme.svg" ~/.local/share/icons/hicolor/scalable/apps/
ln -s "$PLUGIN/share/icons/hicolor/256x256/apps/omatheme.png" ~/.local/share/icons/hicolor/256x256/apps/

Developing

Work in a clone, deploy by copy (the plugin folder may not contain symlinks, and the shell only hot-reloads real file changes — a restart picks up changes reliably):

rsync -a --delete --exclude .git ./ ~/.config/omarchy/plugins/davies-sam.omatheme/
omarchy-restart-shell
omarchy-shell shell summon davies-sam.omatheme '{}'

tests/run exercises every bundled helper end to end on a throwaway fork and restores the desktop it started on.

Adding a panel

  1. Write Panels/<Name>Panel.qml — a ColumnLayout owning its own state, processes and action buttons, like Panels/BorderPanel.qml.
  2. Add a small omatheme-<domain> helper next to the others for the reads and writes it needs (omatheme-lib has the shared theme plumbing).
  3. Add one entry to panels in Omatheme.qml. The switcher appears automatically at two panels.

Development notes and the original build plan live in omatheme-goal.md.