Understanding post_theme_commands in Omarchy: Automating Post-Activation Hooks

Post theme commands in Omarchy are configurable shell hooks defined in JSON-C theme configurations that execute automatically after theme assets are applied, enabling services like Waybar to restart immediately when themes change.

The omacom/omarchy repository implements a sophisticated theme system that extends beyond static color definitions by supporting executable post-activation hooks. Post theme commands allow administrators to define arbitrary shell operations that run automatically after a theme transition completes, ensuring desktop environments remain synchronized with new color schemes and templates.

What Are Post Theme Commands in Omarchy?

Omarchy’s theme architecture separates asset deployment from environment synchronization. While the core theme files define colors and QML templates, post theme commands handle the operational aftermath—restarting services, reloading compositors, or purging caches immediately after installation.

The Configuration Structure

The commands are stored as a JSON-C array named postthemecommands within the theme configuration file. According to the Omarchy source, this array resides in default/omarchy/omarchy-theme.jsonc and contains shell fragments executed sequentially via bash -c.

Each entry is a plain string representing a command to execute:

{
  "postthemecommands": [
    "systemctl --user restart waybar.service",
    "omarchy-refresh-config hypr/hyprland.lua"
  ]
}

Execution Context and Safety

These commands execute as the current user, never as root, inheriting only environment variables explicitly passed by Omarchy's sandboxed execution context. Failures are logged to the system journal but do not abort the theme application—the UI reflects new colors even if a hook crashes, preventing configuration errors from locking users out of theme functionality.

How Post Theme Commands Work in the Omarchy Source Code

The implementation spans both the QML interface layer and shell script backends, orchestrated through specific files in the repository.

Theme Application Flow

When a user runs omarchy theme apply <name>, the system processes the transition through three distinct phases:

1. Asset Loading: The parser reads default/themes/<name>/colors.toml and associated QML templates.
2. Template Deployment: Files copy to the user's config directory using the refresh pattern.
3. Hook Execution: The applyTheme() function in shell/shell.qml invokes the helper script bin/omarchy/theme-apply, which iterates over the postthemecommands array.

Core Execution Logic

The helper script bin/omarchy/theme-apply handles the actual shell invocation. After copying theme assets, it reads the JSON-C configuration and executes each command string. Additionally, the script checks for user-level overrides in ~/.config/omarchy/theme-hooks/postthemecommands.sh, sourcing any custom hooks found there to extend functionality without modifying system themes.

Practical Implementation Examples

Restarting Services After Theme Changes

To ensure Waybar picks up new color values and the compositor refreshes its shaders automatically:

// In default/omarchy/omarchy-theme.jsonc
{
  "postthemecommands": [
    "systemctl --user restart waybar.service",
    "omarchy reload"
  ]
}

Applying the theme triggers both operations:

omarchy theme apply my-dark

Creating Persistent User Hooks

Users can create global post-theme hooks that persist across all theme changes without modifying individual theme files:

mkdir -p ~/.config/omarchy/theme-hooks
cat > ~/.config/omarchy/theme-hooks/postthemecommands.sh <<'EOF'

# Clear Qt's cached color palette

qt5ct-qt5-config --reset
EOF
chmod +x ~/.config/omarchy/theme-hooks/postthemecommands.sh

The bin/omarchy/theme-apply helper automatically sources this script after processing theme-specific commands, applying the user's custom environment adjustments.

Summary

• Post theme commands are shell hooks defined in default/omarchy/omarchy-theme.jsonc via the postthemecommands array that execute after theme assets deploy.
• The bin/omarchy/theme-apply script processes these commands via bash -c, running them strictly as the current user.
• Execution failures are non-blocking; the theme change persists and the UI updates even if individual hooks fail.
• Users can extend functionality through ~/.config/omarchy/theme-hooks/postthemecommands.sh without editing system-wide theme definitions.
• The applyTheme() function in shell/shell.qml orchestrates the entire workflow from the QML interface to the shell execution layer.

Frequently Asked Questions

What file format does Omarchy use for post_theme_commands?

Omarchy stores post theme commands as a JSON-C array property named postthemecommands in default/omarchy/omarchy-theme.jsonc. Each array element is a string containing a shell command that is executed sequentially via bash -c after theme assets are copied.

Do post theme commands run as root or the current user?

Commands execute strictly as the current user, not root. Omarchy's security model prevents privilege escalation by running hooks in a sandboxed environment with limited environment variable exposure, ensuring theme changes cannot inadvertently compromise system security.

What happens if a post theme command fails during theme application?

Omarchy logs the failure but continues execution. The theme change completes successfully and the UI updates to reflect new colors regardless of hook success or failure, preventing configuration errors from locking users out of theme functionality or leaving the desktop in an inconsistent state.

Can I add post theme commands without modifying theme files?

Yes. Create an executable script at ~/.config/omarchy/theme-hooks/postthemecommands.sh. The bin/omarchy/theme-apply helper automatically detects and sources this file after executing theme-specific commands, allowing persistent custom hooks that apply across all theme changes without altering the underlying theme packages.

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