# How to Add User Hooks in Omarchy’s Config Directory: A Complete Setup Guide

> Learn how to add user hooks in Omarchy's config directory. Follow our guide to place executable scripts or use the command for easy setup and permission management.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-13

---

**To add user hooks in Omarchy’s config directory, place executable scripts in `~/.config/omarchy/hooks/<event>.d/` or use the `omarchy hook install <event> <script>` command to automate installation and permission settings.**

Omarchy provides a lightweight automation system called **hooks** that executes custom scripts in response to system events like theme changes, package updates, and low-battery warnings. All user-defined hooks reside under `~/.config/omarchy/hooks/`, keeping your customizations isolated from system-wide defaults documented in [`default/agents/skills/omarchy/hooks.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/hooks.md). This architecture ensures safe upgrades while allowing deep workflow customization.

## Hook Directory Structure in ~/.config/omarchy/hooks/

Omarchy recognizes two distinct organizational patterns within the user configuration directory: event-specific `.d` directories for multiple scripts, and flat files for single-script convenience.

### Event-Specific .d Directories

For each supported event, Omarchy scans subdirectories ending with the `.d` suffix (e.g., `battery-low.d`, `post-boot.d`, `theme-set.d`). Place executable scripts inside these directories to have them run automatically when the corresponding event fires. According to the [`default/agents/skills/omarchy/hooks.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/hooks.md) documentation, the `bin/omarchy-hook` runner executes these scripts sequentially in lexical (alphabetical) order.

### Flat Hook Files

For simpler automation, create a single executable file named after the event without the `.d` suffix (e.g., `~/.config/omarchy/hooks/theme-set`). The hook runner checks for this flat file first and executes it before processing any scripts in the corresponding `.d` directory. This pattern is useful for establishing baseline behavior that must run before specialized handlers.

## Creating and Installing User Hooks

You can populate the Omarchy config directory with hooks either manually or using the built-in CLI helper implemented in `bin/omarchy-hook-install`.

### Manual Installation Method

Create the appropriate directory structure, add your script, and ensure it has execute permissions. For example, to react to theme changes:

```bash
mkdir -p ~/.config/omarchy/hooks/theme-set.d
cat > ~/.config/omarchy/hooks/theme-set.d/notify-theme-change.sh << 'EOF'
#!/usr/bin/env bash
THEME_NAME=$1
echo "Theme changed to: $THEME_NAME"

# Custom actions (e.g., reload panel, update wallpaper) go here

EOF
chmod +x ~/.config/omarchy/hooks/theme-set.d/notify-theme-change.sh

```

### Using the omarchy hook install Command

The installation helper automates placement and permission setting:

```bash
omarchy hook install theme-set /path/to/notify-theme-change.sh

```

This copies the script into `~/.config/omarchy/hooks/theme-set.d/` and marks it executable, mirroring the manual steps above.

## Execution Flow and Parameter Passing

When Omarchy triggers an event, the hook runner follows a specific three-step sequence defined in the core runtime:

1. **Execute flat hook**: The runner first checks for `~/.config/omarchy/hooks/<event>` and runs it if present.
2. **Scan .d directory**: It then scans `~/.config/omarchy/hooks/<event>.d/` and executes each executable script in lexical order.
3. **Pass arguments**: The runner passes event-specific data as positional parameters (e.g., the new theme slug as `$1` for `theme-set` events).

This design allows complex script chains while maintaining predictable execution order.

## Practical Examples of User Hooks

### Post-Boot System Initialization

Create a hook that runs after system boot to start user services:

```bash

# ~/.config/omarchy/hooks/post-boot.d/01-start-services.sh

#!/usr/bin/env bash
systemctl --user start my-custom-service
notify-send "System Ready" "Custom services initialized"

```

### Battery Low Alert

Implement power management logic using the `battery-low` event:

```bash

# ~/.config/omarchy/hooks/battery-low.d/alert-user.sh

#!/usr/bin/env bash
notify-send -u critical "Battery Critical" "Connect charger immediately"

# Additional logic: dim screen, suspend optional services, etc.

```

### Theme Change Handler

Reference the example pattern found in `install/user/first-run/setup-fingerprint.hook` for event-driven configuration:

```bash

# ~/.config/omarchy/hooks/theme-set.d/apply-wallpaper.sh

#!/usr/bin/env bash
THEME_SLUG=$1
feh --bg-scale ~/.config/omarchy/themes/$THEME_SLUG/wallpaper.jpg

```

## Summary

- User hooks reside in `~/.config/omarchy/hooks/` with event-specific subdirectories ending in `.d`
- Use `omarchy hook install <event> <script>` to automatically install hooks via `bin/omarchy-hook-install`
- Flat files (without `.d`) execute before directory contents, useful for baseline configuration
- Scripts receive event data as positional parameters (e.g., `$1` for theme slugs)
- System defaults are documented in [`default/agents/skills/omarchy/hooks.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/hooks.md) but user hooks take precedence in the config directory

## Frequently Asked Questions

### What events support user hooks in Omarchy?

Omarchy supports hooks for system events including theme changes (`theme-set`), package updates, low-battery warnings (`battery-low`), and post-boot initialization (`post-boot`). The definitive list and event-specific parameter details are maintained in [`default/agents/skills/omarchy/hooks.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/hooks.md).

### How do I control the execution order of multiple hook scripts?

Name your scripts with numeric prefixes (e.g., [`10-preload.sh`](https://github.com/omacom/omarchy/blob/main/10-preload.sh), [`20-notify.sh`](https://github.com/omacom/omarchy/blob/main/20-notify.sh)) when placing them in `.d` directories. The `bin/omarchy-hook` runner executes scripts in lexical (alphabetical) order, so [`01-first.sh`](https://github.com/omacom/omarchy/blob/main/01-first.sh) runs before [`99-last.sh`](https://github.com/omacom/omarchy/blob/main/99-last.sh).

### Why isn't my hook script running when the event triggers?

First, verify the script is executable with `chmod +x`. Second, confirm the file resides in the correct location—either as a flat file at `~/.config/omarchy/hooks/<event>` or inside `~/.config/omarchy/hooks/<event>.d/`. Finally, ensure the script includes a valid shebang line (e.g., `#!/usr/bin/env bash`) so the runner knows how to execute it.

### Can I use the install helper for flat hook files?

The `omarchy hook install` command specifically targets `.d` directories. For flat hook files, you must manually create and chmod the file at `~/.config/omarchy/hooks/<event>`. This distinction allows you to choose between simple single-file hooks and multi-script event handling workflows.