# How to Customize Omarchy User Configuration: Complete Guide to Themes, Shell Layout, and Hooks

> Master Omarchy user configuration with our guide. Learn to customize themes, shell layout, and hooks using JSON/TOML files in ~/.config/omarchy/ without recompilation.

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

---

**Omarchy stores all user‑editable settings in `~/.config/omarchy/` and applies them through JSON/TOML files, lifecycle hooks, and template processing—no recompilation required.**

This guide walks you through every layer of Omarchy user customization using the actual source structure from the omacom/omarchy repository. Whether you want to rearrange your status bar, create a custom color theme, or automate post‑update actions, all changes happen in plain text files under your home directory.

---

## Where Configuration Lives

According to the Omarchy file layout documentation, user configuration follows a predictable path: defaults ship with the **omarchy‑settings** package, then the `omarchy‑provision‑user` step runs once per account to prepare home‑directory files that cannot use static `/etc/skel` templates. After that initial setup, you own `~/.config/omarchy/`.

| Location | Purpose |
|----------|---------|
| `~/.config/omarchy/shell.json` | Bar widgets, gestures, and plugin configuration |
| `~/.config/omarchy/themes/<name>/` | Color schemes and application‑specific overrides |
| `~/.config/omarchy/hooks/<stage>.d/` | Executable scripts triggered at lifecycle moments |
| `~/.config/omarchy/themed/*.tpl` | Template files processed before config deployment |

---

## Customize Shell Layout with shell.json

The **shell.json** file at `~/.config/omarchy/shell.json` is the single source of truth for your desktop's appearance and behavior. Unlike many Linux tools, Omarchy does **not** deep‑merge this file—any edit completely replaces the default, so you start with full control.

### Key Sections in shell.json

| Section | Controls |
|---------|----------|
| `bar.widgets` | Which widgets appear and where (left/center/right) |
| `gesture` | Touchpad and mouse gestures bound to commands |
| `plugins` | Per‑plugin settings like update check intervals |

### Example: Custom Bar Layout

```bash
cat > ~/.config/omarchy/shell.json <<'EOF'
{
  "bar": {
    "widgets": [
      { "id": "workspaces", "placement": "left" },
      { "id": "window-title", "placement": "center" },
      { "id": "cpu", "placement": "right" },
      { "id": "memory", "placement": "right" },
      { "id": "clock", "placement": "right" }
    ]
  },
  "gesture": {
    "swipe-up": "omarchy toggle overview",
    "swipe-down": "omarchy toggle launcher"
  }
}
EOF

```

Save the file and Quickshell detects the change automatically—no session restart needed.

---

## Create and Apply Custom Themes

Omarchy themes live in `~/.config/omarchy/themes/<name>/`. Each theme is a directory containing at minimum a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file, plus optional overrides for terminal emulators and other applications.

### Theme Directory Structure

```

~/.config/omarchy/themes/midnight/
├── colors.toml          # Required: base color palette

├── alacritty.toml       # Optional: terminal overrides

└── *.tpl                # Optional: processed templates

```

### Example: Minimal Dark Theme

```bash
mkdir -p ~/.config/omarchy/themes/midnight

cat > ~/.config/omarchy/themes/midnight/colors.toml <<'EOF'
background = "#0a0a0a"
foreground = "#e4e4e4"
accent = "#7c3aed"
warning = "#f59e0b"
critical = "#ef4444"
EOF

omarchy theme set midnight

```

The `omarchy theme set` command activates your theme immediately and persists the choice for future sessions.

---

## Automate with Lifecycle Hooks

Hooks in `~/.config/omarchy/hooks/` run executable scripts at defined stages. Place scripts in subdirectories named `<stage>.d/` and ensure they have execute permission.

| Hook Stage | When It Runs |
|------------|--------------|
| `post-update.d/` | After `omarchy update` completes |
| `theme-set.d/` | Immediately after `omarchy theme set` |
| `pre-shutdown.d/` | Before the session ends |

### Example: Post-Update Notification Hook

```bash
mkdir -p ~/.config/omarchy/hooks/post-update.d

cat > ~/.config/omarchy/hooks/post-update.d/notify <<'EOF'
#!/usr/bin/env bash
omarchy-notification-send \
  "Update Complete" \
  "Omarchy packages refreshed at $(date +%H:%M)"
EOF

chmod +x ~/.config/omarchy/hooks/post-update.d/notify

```

Next time you run `omarchy update`, your notification script triggers automatically.

---

## Work with Templates

Files in `~/.config/omarchy/themed/*.tpl` pass through Omarchy's template engine before landing in their final locations. This lets you generate dynamic configuration using variables like `$HOME`, current theme colors, or runtime state.

Template processing occurs when you run `omarchy-theme-refresh` or restart the shell. Use templates when you need computed values that static config files cannot provide.

---

## Reset to Factory Defaults

To discard all customizations and restore the original configuration tree:

```bash
omarchy-reinstall-configs

```

This command overwrites `~/.config/omarchy/` with the current defaults from the omarchy‑settings package. Back up any files you want to preserve before running it.

---

## Summary

- All Omarchy user configuration lives in `~/.config/omarchy/` as plain JSON, TOML, and shell scripts
- Edit [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) to control bar layout, gestures, and plugins—changes apply instantly without merge logic
- Create themes in `~/.config/omarchy/themes/<name>/` with [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and optional overrides, then activate with `omarchy theme set`
- Add executable scripts to hook directories for automation at update, theme change, or shutdown events
- Use `omarchy-reinstall-configs` to reset everything to upstream defaults

---

## Frequently Asked Questions

### Where is the default shell.json located in the repository?

The default ships at [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) in the omacom/omarchy repo. The omarchy‑settings package copies this to `~/.config/omarchy/shell.json` during initial user provisioning if no file exists yet.

### Do I need to restart Quickshell after editing shell.json?

No. Quickshell watches `~/.config/omarchy/shell.json` for changes and reloads the layout automatically. This is documented in [`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md) where the configuration system is described as having no deep‑merge behavior.

### Can I version‑control my Omarchy configuration?

Yes. All files in `~/.config/omarchy/` are plain text—JSON, TOML, and shell scripts—making them ideal for Git-based dotfile management. The directory structure remains stable across Omarchy updates.

### What happens if my shell.json is malformed?

Since Omarchy does not deep‑merge, an invalid JSON file may prevent the shell from loading entirely. Keep a backup of working configurations, or run `omarchy-reinstall-configs` to restore defaults if you encounter issues.