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

> Explore Omarchy configuration options to customize your desktop environment. Learn to modify layouts, plugins, menus, and themes with JSON and TOML files.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-19

---

**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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/shell.json) or via command-line utilities:

```bash

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

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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:

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

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

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

3. **Create a post-boot weather hook:**

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

   ```bash
   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`](https://github.com/basecamp/omarchy/blob/main/shell.json), `omarchy-menu.jsonc`) and TOML theme templates stored in `config/omarchy/`.
- The `bar:` section in [`shell.json`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.