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

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

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:

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:

# ~/.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:

# ~/.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:

# ~/.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 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.

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

Name your scripts with numeric prefixes (e.g., 10-preload.sh, 20-notify.sh) when placing them in .d directories. The bin/omarchy-hook runner executes scripts in lexical (alphabetical) order, so 01-first.sh runs before 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.

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