Configuration Options for Omarchy: A Complete Guide to Customizing Your Desktop Environment

Omarchy provides a modular configuration system centered on JSON and TOML files under config/omarchy/, allowing you to customize the bar layout, enable plugins, define menu entries, and set themes through declarative files and CLI commands.

Omarchy, the open-source desktop environment maintained in the basecamp/omarchy repository, relies on a structured filesystem-based configuration approach. Mastering the available configuration options for Omarchy enables you to modify shell behavior, widget placement, and system hooks without recompiling the application. All defaults reside in the repository’s config/omarchy/ directory, which the omarchy-refresh-config helper copies to ~/.config/omarchy/ where user overrides take precedence.

Core Configuration Architecture

Omarchy organizes settings into four primary file types: the central shell configuration, menu extensions, theme templates, and lifecycle hooks.

The Central shell.json

The config/omarchy/shell.json file serves as the primary configuration source that the long-running omarchy-shell process reads at startup. This JSON file defines the entire desktop shell structure, including the bar position, enabled plugins, and widget-specific parameters.

Key sections include:

• bar: – Controls visual properties such as position (top or bottom), opacity levels, and transparency toggles.
• plugins: – Lists enabled plugins (for example, omarchy.bar, omarchy.menu, omarchy.audio).
• widgets: – Stores per-widget settings (for example, omarchy.clock.format for time display formats).

According to the source code in shell/plugins/bar/README.md, the schema for the bar: subtree defines these specific keys.

Menu Extensions with omarchy-menu.jsonc

To customize the application menu, Omarchy uses config/omarchy/extensions/omarchy-menu.jsonc. This JSONC file (JSON with comments) extends or overrides the default menu definition found in default/omarchy/omarchy-menu.jsonc.

The primary configuration key is:

• items: – An array of menu objects, each containing label, command, and icon properties.

You can add, remove, or reorder top-level menu entries by modifying this file.

Theme Templates in themed/

Visual theming operates through TOML template files located in config/omarchy/themed/. The omarchy-theme-set command consumes these *.toml.tpl.sample files to apply color schemes and font choices.

Key template types include:

• colors.toml – Defines accent colors, background, foreground, and bright variants.
• alacritty.toml.tpl.sample – Provides terminal-specific theme configurations.

Users copy these .sample files, remove the extension, and customize values to create persistent themes.

Lifecycle Hooks

The config/omarchy/hooks/ directory contains executable scripts that run at specific system events. Files use the .sample extension by default; you must remove the extension and mark them executable to activate them.

Common hook directories include:

• post-boot.d/ – Scripts like weather.sample that fetch data after system initialization.
• battery-low.d/ – Alert scripts such as play-warning-sound.sample.
• post-update.d/ – Maintenance tasks following system updates.

These hooks integrate with the omarchy-shell lifecycle management system.

Customizing the Bar and Widgets

The Omarchy bar acts as the primary user interface element, fully configurable through both configuration files and CLI commands.

Bar Position and Appearance

To adjust the bar location and transparency, modify the bar: section in your user configuration file at ~/.config/omarchy/shell.json or use the CLI:

# Move bar to the top of the screen (writes to ~/.config/omarchy/shell.json)

omarchy bar position top

This command updates the JSON structure under the bar.position key.

Plugin Management

Enable or disable plugins by manipulating the plugins: array in shell.json or via command-line utilities:

# Enable a custom plugin (requires installation under ~/.config/omarchy/plugins/)

omarchy plugin enable my.custom.plugin

Disabled plugins are removed from the active plugins list, preventing the shell from loading their associated widgets.

Per-Widget Settings

Individual widget parameters reside under the widgets: section. For example, to change the clock format or disable Bluetooth indicators:

# Set 12-hour time format for the clock widget

omarchy bar set omarchy.clock format "hh:mm a"

# Disable the Bluetooth widget entirely

omarchy bar set omarchy.bluetooth enabled false

These commands write directly to the user copy of shell.json, specifically targeting keys like widgets.omarchy.clock.format and widgets.omarchy.bluetooth.enabled.

Working with User Overrides

Omarchy implements a cascading configuration system. The repository defaults in config/omarchy/ provide base functionality, but files in ~/.config/omarchy/ take precedence.

When you execute commands like omarchy bar set or omarchy plugin enable, the system writes changes to ~/.config/omarchy/shell.json. Any keys omitted from the user file fall back to the default values defined in the repository copy.

For menu customizations, editing ~/.config/omarchy/extensions/omarchy-menu.jsonc allows you to inject custom entries without altering the default menu structure:

{
  "items": [
    { "label": "My App", "command": "my-app-launcher", "icon": "app-icon" }
  ]
}

Practical Configuration Examples

The following snippets demonstrate complete workflows for common customization tasks:

1. Relocate the bar and adjust opacity:

   omarchy bar position top
   omarchy bar set bar.opacity 0.95

2. Add a custom launcher to the main menu:

   Edit ~/.config/omarchy/extensions/omarchy-menu.jsonc:

   {
     "items": [
       { "label": "Development", "command": "/usr/bin/code", "icon": "code-icon" }
     ]
   }

3. Create a post-boot weather hook:

   cp ~/.config/omarchy/hooks/post-boot.d/weather.sample \
      ~/.config/omarchy/hooks/post-boot.d/weather
   # Edit the file to call your weather API client
   
   chmod +x ~/.config/omarchy/hooks/post-boot.d/weather

4. Apply a custom color theme:

   Copy and modify the sample template:

   cp config/omarchy/themed/colors.toml.tpl.sample \
      ~/.config/omarchy/themed/my-theme.toml
   # Edit my-theme.toml with custom hex values
   
   omarchy theme set my-theme

Summary

• Omarchy configuration centers on JSON files (shell.json, omarchy-menu.jsonc) and TOML theme templates stored in config/omarchy/.
• The bar: section in shell.json controls position, opacity, and transparency; the plugins: array manages loaded extensions; the widgets: subtree stores per-component settings.
• Menu customizations occur in config/omarchy/extensions/omarchy-menu.jsonc through the items: array.
• Lifecycle hooks in config/omarchy/hooks/ (such as post-boot.d/ and battery-low.d/) execute scripts at specific events.
• User overrides in ~/.config/omarchy/ take precedence over repository defaults, with the CLI (omarchy bar set, omarchy plugin enable) writing automatically to the user configuration files.

Frequently Asked Questions

Where are Omarchy configuration files stored?

Default configuration files reside in the repository’s config/omarchy/ directory. At runtime, the omarchy-refresh-config helper copies these to ~/.config/omarchy/, where user-specific modifications take precedence. Commands like omarchy bar set automatically write to the user copy in the home directory.

How do I change the bar position in Omarchy?

Use the omarchy bar position command followed by top or bottom. This updates the bar.position key in ~/.config/omarchy/shell.json. Alternatively, manually edit the bar: section in that JSON file and restart the omarchy-shell process to apply changes.

Can I add custom menu entries to Omarchy?

Yes. Create or edit ~/.config/omarchy/extensions/omarchy-menu.jsonc and add objects containing label, command, and icon keys to the items: array. The full menu schema is documented in docs/menu.md, and changes take effect immediately.

What is the difference between default and user configuration files?

Default files in config/omarchy/ provide baseline settings for the bar, plugins, and themes. When you modify settings via CLI commands or manual edits, Omarchy writes to files in ~/.config/omarchy/. The system merges configurations by checking the user directory first; any undefined keys fall back to the repository defaults, allowing safe upgrades without losing customizations.

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