# Understanding post_theme_commands in Omarchy: Automating Post-Activation Hooks

> Discover post_theme_commands in Omarchy to automate post-activation hooks. Learn how these JSON-C hooks run shell commands after theme assets apply, enabling immediate service restarts like Waybar.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-03

---

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

```jsonc
{
  "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:

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

```

Applying the theme triggers both operations:

```bash
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:

```bash
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.