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

> Discover the Omarchy-Hook system, an automation framework for Omarchy. Learn how system events like post-boot, post-update, and theme changes trigger custom scripts.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-11

---

**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`](https://github.com/omacom/omarchy/blob/main/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:

```bash

# 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:

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/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.