Dotfiles

Omarchy is primarily configured through the so-called dotfiles that live in ~/.config. Those are considered your files for your changes. The files that live in /usr/share/omarchy belong to Omarchy itself, and you shouldn’t be messing with those. If you need to change anything in /usr/share/omarchy, you should be overwriting the value in ~/.config instead.

The key configs can be edited straight from the Omarchy menu (Super + Space), like Setup > Monitors, Setup > Keybindings, Setup > Input, and Setup > Config > [file]. When you do it this way, any process that needs restarting after config edits automatically will be after you quit the editor (Neovim by default — :wq, remember! — but you can change that via Setup > Defaults > Editor).

Here’s a list of the key files in ~/.config and what they control:

If you end up making a lot of changes to tweak your own setup, it’s a good idea to backup all these dotfiles. Stow is a great way to do that.

Starting your own apps with the session

If you want something to run every time you log in — a sync daemon, a chat app, your own script — put it in ~/.config/hypr/autostart.lua:

o.launch_on_start("my-service")

That starts the command as part of the session, so it’s properly cleaned up when you log out again.

Running scripts on system events

Omarchy fires hooks at a handful of moments, and you can hang your own scripts off them. They live in ~/.config/omarchy/hooks/<event>.d/, one directory per event, and every executable file in there runs when the event happens:

Each of those directories already holds a .sample file showing the shape of a hook — drop the .sample from the name to put it to work. To install a script you’ve written elsewhere, use omarchy hook install post-boot ~/my-hook, which copies it in and makes it executable.

Adding your own menu entries

The Omarchy menu (Super + Space) can be extended with your own rows by editing ~/.config/omarchy/extensions/omarchy-menu.jsonc. Entries are keyed by a dotted id, and the id is what places them in the tree, so personal shows up on the root menu and personal.notes shows up inside it:

"personal": {"icon":"","label":"Personal"},
"personal.notes": {"icon":"󰎞","label":"Notes","action":"omarchy-launch-editor ~/notes"},

Reuse an existing id and you override that row instead of adding a new one. The file ships with all the available fields documented as comments.

Adding your own shell exports, functions, and aliases

Omarchy ships with a bunch of ergonomic aliases and helpful functions, but it’s very common to want to add your own. You should add both aliases, functions, and exports in ~/.bashrc. This file will not be overwritten on updates. If you want to change any of the Omarchy defaults, you can also safely add them here.

Changing internal Omarchy files

Look, this is your computer. You can do whatever you want with it, but I would advise against making changes to the files in /usr/share/omarchy directly. They belong to the Omarchy pacman package, so your changes will simply be overwritten on the next update. You’re better off just overwriting any default values you don’t like in the ~/.config/* folder instead.

You can change just about everything that way, like the default keybindings. Just edit ~/.config/hypr/bindings.lua to, say, replace Obsidian with Joplin (install with omarchy-pkg-add joplin-bin):

hl.unbind("SUPER + SHIFT + O")
o.bind("SUPER + SHIFT + O", "Joplin", "joplin-desktop")

If you insist on hacking on the internal Omarchy files, switch to the dev channel via Update > Channel > Dev. That links Omarchy to a git checkout of the source code in ~/omarchy, which you’re free to change to your heart’s content. Ain’t nobody here to tell you what to do!

Resetting any changes

If you end up making a mess of the configurations, you can always revert them to the defaults via Update > Config in the Omarchy menu. Or by running omarchy reinstall configs to reset everything.