FIELD NOTE / 01
Naming the repository
Follow the omarchy-<name>-theme convention. Omarchy takes the last path segment of the clone URL, strips .git, removes a leading omarchy- and a trailing -theme, and lowercases what is left. That remainder becomes both the directory name and the name in the theme picker.
Because the result becomes a directory name that Omarchy passes around, it is validated rather than sanitised. The first character must be a letter, a digit or an underscore; the rest may be letters, digits, ., _, + and -. Capitals are lowercased for you. Anything else — a space, a quote, an accented character — is refused at install time with an error, not turned into a directory.
| Repository | Installs as |
|---|---|
omarchy-tokyo-night-theme | tokyo-night |
omarchy-flexoki_light-theme | flexoki_light |
omarchy-c++-theme | c++ |
omarchy-Harbor-Theme | harbor |
FIELD NOTE / 02
The install command
omarchy theme install https://github.com/you/omarchy-harbor-theme.gitOmarchy checks the URL names a repository rather than a Git transport helper, clones it into ~/.config/omarchy/themes/harbor, and applies it immediately. SSH URLs work too. If a theme of that name is already installed, it is replaced. The same thing is available from the menu under Install > Style > Theme.
This is also how every theme in this gallery installs, including palettes published from the Theme Studio — those are served as small read-only Git repositories, so the native installer handles them with no account and no extra tooling.
FIELD NOTE / 03
Before you publish
- A
README.mdwith a screenshot, what the theme is for, and background credits. - A
LICENSE, and a note if the backgrounds are licensed differently from the palette. - A
preview.png, so the theme picker shows something. - No
.lua, no terminal configs, novscode.json— they are dropped on install, so a theme that depends on them is broken for everyone but you. - A real install test from the published URL on a machine that has never had the theme.
FIELD NOTE / 04
Getting listed on omarchy.org
Omarchy’s own extra themes page is maintained in the website repository. To be added, send a pull request to omacom/omarchy-site . Listings there carry a screenshot and a link to your repository.
FIELD NOTE / 05
How this gallery imports themes
This gallery is independent of Omarchy and imports from the official listing. For each theme it pins the repository to a specific commit, reads colors.toml as data — or derives a palette from a legacy terminal config — caches the published screenshot and any backgrounds, and records the source URL, commit and licence metadata as provenance. Repository code is never cloned, evaluated or run.
You can also submit a public GitHub repository from the gallery, or from the Submit theme link in the header. Submission returns a private receipt link for checking review status. It is not an ownership claim, and the original repository stays the credited source.
Two things follow from that, and both are worth doing before you submit: put colors.toml in the repository root, and make sure your licence is one GitHub recognises, since image publication needs a rights review separate from the palette.