Hooks and extension points
Omarchy runs every executable in these directories under ~/.config/omarchy/hooks/ when the matching event happens. Install one with omarchy hook install. Data from v4.0.4.
battery-low
Directory: ~/.config/omarchy/hooks/battery-low.d. Fired by omarchy-battery-low.
Shipped sample: play-warning-sound.sample
This hook is called with the current battery percentage when the low battery notification is sent. To put it into use, remove .sample from this file name.
#!/bin/bash
# This hook is called with the current battery percentage when the low battery
# notification is sent. To put it into use, remove .sample from this file name.
SOUND_FILE="/usr/share/sounds/freedesktop/stereo/dialog-warning.oga"
if omarchy-cmd-present mpv && [[ -f $SOUND_FILE ]]; then
mpv --no-video "$SOUND_FILE" >/dev/null 2>&1
fi
font-set
Directory: ~/.config/omarchy/hooks/font-set.d. Fired by omarchy-font-set.
Shipped sample: show-font-notification.sample
This hook is called with the snake-cased name of the font that has just been set. To put it into use, remove .sample from this file name.
#!/bin/bash
# This hook is called with the snake-cased name of the font that has just been set.
# To put it into use, remove .sample from this file name.
# Example: Show the name of the font that was just set.
# omarchy-notification-send -u low "New font" "Your new font is $1"
post-boot
Directory: ~/.config/omarchy/hooks/post-boot.d. Fired by default/hypr/autostart.lua.
Shipped sample: weather.sample
Show the weather status notification after Omarchy has started. To put it into use, remove .sample from this file name.
#!/bin/bash
# Show the weather status notification after Omarchy has started.
# To put it into use, remove .sample from this file name.
weather=$(omarchy-weather-status 2>/dev/null) || true
if [[ -n $weather && $weather != "Weather unavailable" ]]; then
omarchy-notification-send -u low "$weather"
fi
post-update
Directory: ~/.config/omarchy/hooks/post-update.d. Fired by omarchy-update.
Shipped sample: show-update-notification.sample
This hook is called after an Omarchy system update has been performed. To put it into use, remove .sample from this file name.
#!/bin/bash
# This hook is called after an Omarchy system update has been performed.
# To put it into use, remove .sample from this file name.
# Example: Show notification after the system has been updated.
# omarchy-notification-send -u low "Update Performed" "Your system is now up to date"
pre-refresh-pacman
Directory: ~/.config/omarchy/hooks/pre-refresh-pacman.d. Fired by omarchy-refresh-pacman.
Shipped sample: add-custom-repo.sample
This hook is called by `omarchy refresh pacman` AFTER the channel template is copied to /etc/pacman.conf and BEFORE `pacman -Syyuu` runs. Use it to layer customizations onto the freshly-written pacman.conf so they're respected by the upgrade — common cases are adding a custom repository (e.g. CachyOS, Chaotic-AUR, an internal company repo) or extra IgnorePkg lines. The hook runs as the invoking user with a warm sudo cache. To put it into use, remove .sample from this file name.
#!/bin/bash
# This hook is called by `omarchy refresh pacman` AFTER the channel template
# is copied to /etc/pacman.conf and BEFORE `pacman -Syyuu` runs. Use it to
# layer customizations onto the freshly-written pacman.conf so they're
# respected by the upgrade — common cases are adding a custom repository
# (e.g. CachyOS, Chaotic-AUR, an internal company repo) or extra IgnorePkg
# lines.
#
# The hook runs as the invoking user with a warm sudo cache.
#
# To put it into use, remove .sample from this file name.
# Example: add an Include line above [core] for a custom repo.
# Maintain the repo entries in /etc/pacman.d/custom-repos.conf yourself.
CONF=/etc/pacman.conf
SNIPPET=/etc/pacman.d/custom-repos.conf
MARKER="Include = $SNIPPET"
[[ -r $SNIPPET ]] || exit 0
grep -qxF "$MARKER" "$CONF" && exit 0
sudo sed -i "0,/^\[core\]/s||$MARKER\n\n[core]|" "$CONF"
theme-set
Directory: ~/.config/omarchy/hooks/theme-set.d. Fired by omarchy-theme-set.
Shipped sample: show-theme-notification.sample
This hook is called with the snake-cased name of the theme that has just been set. To put it into use, remove .sample from this file name.
#!/bin/bash
# This hook is called with the snake-cased name of the theme that has just been set.
# To put it into use, remove .sample from this file name.
# Example: Show the name of the theme that was just set.
# omarchy-notification-send -u low "New theme" "Your new theme is $1"
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:
| Event | When it runs |
|---|---|
post-boot |
Right after the desktop has started |
post-update |
During omarchy update, after packages and migrations |
pre-refresh-pacman |
Before omarchy refresh pacman re-syncs the package config |
theme-set |
After a theme change (theme name in $1) |
font-set |
After a font change (font name in $1) |
battery-low |
When the battery gets low (percentage in $1) |
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.