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

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

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

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

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:

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 to control bar layout, gestures, and plugins—changes apply instantly without merge logic
• Create themes in ~/.config/omarchy/themes/<name>/ with 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 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 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.

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