Understanding the Omarchy-Hook System: Events, Triggers, and Custom Scripts

The omarchy-hook system is a lightweight automation framework in Omarchy that executes custom scripts at specific system events such as post-boot, post-update, theme changes, and battery warnings.

The omacom/omarchy repository provides this hook infrastructure to let users extend their desktop environment without modifying core system files. The framework follows Unix conventions by using executable directories and flat files to organize event-driven automation.

How the Omarchy-Hook System Works

Directory Structure and Hook Locations

All hook scripts reside under the user's configuration directory at ~/.config/omarchy/hooks/. For each supported event, the framework recognizes two installation patterns:

• Event directories: Named <event>.d/ (e.g., post-boot.d/, theme-set.d/), containing any number of executable scripts
• Flat files: Optional single files named <event> (e.g., ~/.config/omarchy/hooks/post-update) that execute first if present

This structure allows both granular, modular scripts and simple single-file implementations depending on your use case.

The Hook Installation Process

Instead of manually creating directories and setting permissions, users install hooks through the helper command omarchy hook install <event> <script>. As implemented in bin/omarchy-hook-install, this command:

1. Copies the specified script into the appropriate <event>.d/ directory
2. Automatically sets executable permissions via chmod +x
3. Ensures parent directories exist under ~/.config/omarchy/hooks/

Built-In Events That Trigger Hooks

According to the source documentation in default/agents/skills/omarchy/hooks.md, the framework ships with six fixed events automatically triggered by Omarchy core components:

Event	Trigger Condition	Arguments
post-boot	Immediately after the desktop environment finishes starting	None
post-update	During omarchy update, after packages upgrade and migrations complete	None
pre-refresh-pacman	Right before omarchy refresh pacman re-syncs the package database	None
theme-set	After a theme change occurs	New theme slug passed as $1
font-set	After a font change occurs	New font name passed as $1
battery-low	When battery reaches low-percentage threshold	Current percentage passed as $1

These events cover the full lifecycle of a desktop session, from initialization through system maintenance to runtime state changes.

The Hook Execution Mechanism

The actual execution is handled by bin/omarchy-hook, the binary runner that iterates through installed scripts for a specific event. When invoked (typically by Omarchy core components), the runner:

1. Checks for the presence of ~/.config/omarchy/hooks/<event> flat file and executes it first
2. Discovers all executable files inside ~/.config/omarchy/hooks/<event>.d/
3. Runs each script sequentially, passing relevant arguments (such as theme names or battery percentages) as $1

This execution model ensures predictable ordering while maintaining flexibility for user customization.

Installing Custom Hooks

You can create hooks either through the CLI helper or manually. Here are practical examples for common automation tasks:

# Install a hook via CLI that logs theme changes

omarchy hook install theme-set <<'EOF'
#!/usr/bin/env bash
new_theme=$1
echo "Theme switched to $new_theme" | systemd-cat -t theme-hook

# Add custom actions here, e.g., reload a compositor configuration

EOF

For manual installation or complex multi-script setups:

# Create a battery-low notification hook manually

mkdir -p ~/.config/omarchy/hooks/battery-low.d

cat > ~/.config/omarchy/hooks/battery-low.d/notify <<'EOS'
#!/usr/bin/env bash
percentage=$1
omarchy-notification-send "Battery low: ${percentage}%"
EOS

chmod +x ~/.config/omarchy/hooks/battery-low.d/notify

Running omarchy-hook theme-set solarized-dark (normally invoked internally by the theme subsystem) would execute any installed scripts in ~/.config/omarchy/hooks/theme-set.d/ with solarized-dark as the first argument.

Integration with System Components

The hook framework integrates deeply with Omarchy's underlying infrastructure through several key files:

• default/libalpm/hooks/00-omarchy-update-guard.hook: An ALPM (pacman) pre-transaction hook that bridges package upgrades to the Omarchy post-update hook system
• default/libalpm/hooks/10-omarchy-hyprland-reload-pause.hook and 90-omarchy-hyprland-reload-resume.hook: Coordinate Hyprland reloads around package transactions to prevent crashes
• etc/mkinitcpio.conf.d/omarchy_hooks.conf: Ensures hook infrastructure is available during early boot stages

These integration points demonstrate how the omarchy-hook system serves as the canonical extension point for system-level automation.

Summary

• The omarchy-hook system stores automation scripts in ~/.config/omarchy/hooks/ using either flat files or <event>.d/ directories
• Six built-in events trigger execution: post-boot, post-update, pre-refresh-pacman, theme-set, font-set, and battery-low
• Use omarchy hook install <event> <script> for CLI-based installation, or manually create executables in the appropriate directories
• The bin/omarchy-hook binary handles script discovery and execution, passing event-specific arguments (such as theme slugs or battery percentages) to scripts
• System integration occurs through ALPM hooks and mkinitcpio configuration, ensuring hooks run during package updates and early boot phases

Frequently Asked Questions

How do I manually create a hook without using the install command?

Create the appropriate directory structure under ~/.config/omarchy/hooks/, place your script in either the flat file <event> or inside <event>.d/, and ensure the file has executable permissions (chmod +x). The bin/omarchy-hook runner will discover and execute it during the next trigger of that event.

What arguments are passed to hook scripts?

Arguments vary by event. The theme-set and font-set events pass the new theme slug or font name as $1, while battery-low passes the current battery percentage. Events like post-boot, post-update, and pre-refresh-pacman receive no arguments.

Can I have multiple scripts for the same event?

Yes. Place multiple executable scripts inside the <event>.d/ directory (e.g., ~/.config/omarchy/hooks/post-boot.d/). The bin/omarchy-hook runner executes them in alphabetical order after running the flat file <event> (if it exists).

When exactly does the post-update hook run during system updates?

The post-update hook fires during omarchy update after all system packages have been upgraded and database migrations have completed. This is orchestrated through default/libalpm/hooks/00-omarchy-update-guard.hook, which ensures the hook executes only once the transaction successfully finishes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}