# How to Configure Omarchy: Complete Guide to Shell, Themes, and Plugins

> Easily configure Omarchy with this complete guide. Customize shell layout, apply themes, and manage plugins to personalize your Omarchy experience.

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

---

**To configure Omarchy, edit `~/.config/omarchy/shell.json` to customize the top bar layout and idle timers, use `omarchy theme set <name>` for appearance changes, and run `omarchy-shell shell reloadConfig` to apply changes immediately.**

All user-facing configuration for the `basecamp/omarchy` desktop environment lives in `~/.config/omarchy/`. The central [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json) file controls the top bar layout, idle behavior, and active plugins, while separate TOML files handle theming and Git-based repositories provide third-party extensions.

## Core Shell Configuration via shell.json

The **primary configuration file** is `~/.config/omarchy/shell.json`, which defines idle timers, bar positioning, and widget arrangement. The default version ships at [`config/omarchy/shell.json`](https://github.com/basecamp/omarchy/blob/main/config/omarchy/shell.json) in the repository and seeds to `/etc/skel` during installation.

### Understanding the Configuration Structure

The JSON schema contains four main sections:

- **`idle`** – Controls screensaver and lock delays in seconds
- **`bar`** – Defines position, transparency, and widget layout
- **`plugins`** – Array of third-party plugin IDs to activate
- **`version`** – Configuration schema version (currently `1`)

Default values from the source:

```json
{
  "version": 1,
  "idle": {
    "screensaver": 150,
    "lock": 300
  },
  "bar": {
    "position": "top",
    "transparent": false,
    "centerAnchor": "omarchy.clock",
    "layout": {
      "left": [
        { "id": "omarchy.menu" },
        { "id": "omarchy.workspaces" }
      ],
      "center": [
        { "id": "omarchy.indicators" },
        { "id": "omarchy.clock", "format": "dddd HH:mm", "formatAlt": "d MMMM 'W'ww yyyy", "verticalFormat": "HH\n—\nmm" },
        { "id": "omarchy.keyboard-layout" },
        { "id": "omarchy.weather" },
        { "id": "omarchy.system-update" }
      ],
      "right": [
        { "id": "omarchy.tray" },
        { "id": "omarchy.agents" },
        { "id": "omarchy.bluetooth" },
        { "id": "omarchy.network" },
        { "id": "omarchy.audio" },
        { "id": "omarchy.monitor" },
        { "id": "omarchy.power" }
      ]
    }
  },
  "plugins": []
}

```

### Customizing the Top Bar Layout

Modify the `bar.layout` object to rearrange, add, or remove widgets. The layout divides into three zones: `left`, `center`, and `right`. Each widget is an object with an `id` field and optional configuration parameters.

To move the clock to the left side with a custom format:

```json
{
  "layout": {
    "left": [
      { "id": "omarchy.clock", "format": "HH:mm" },
      { "id": "omarchy.menu" }
    ],
    "center": [
      { "id": "omarchy.indicators" }
    ],
    "right": [
      { "id": "omarchy.tray" },
      { "id": "omarchy.power" }
    ]
  }
}

```

Available widget IDs include `omarchy.menu`, `omarchy.workspaces`, `omarchy.indicators`, `omarchy.clock`, `omarchy.keyboard-layout`, `omarchy.weather`, `omarchy.system-update`, `omarchy.tray`, `omarchy.agents`, `omarchy.bluetooth`, `omarchy.network`, `omarchy.audio`, `omarchy.monitor`, and `omarchy.power`.

### Reloading Configuration Changes

After editing [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json), apply changes without restarting the session:

```bash
omarchy-shell shell reloadConfig

```

This command re-parses the configuration and updates the running Quickshell instance immediately.

## Theming and Visual Customization

Omarchy uses a two-part theme system split between [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) (palette definitions) and [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) (structural tokens like spacing and font sizes). Default themes reside in `/usr/share/omarchy/themes/default/` and copy to `~/.local/state/omarchy/current/` at runtime.

### Creating Custom Themes

Create a new theme directory structure:

```bash
mkdir -p ~/.config/omarchy/themes/mytheme
cp -r /usr/share/omarchy/themes/default/* ~/.config/omarchy/themes/mytheme/

```

Edit [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) to modify foreground, background, and accent colors, or adjust [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) to change bar dimensions and spacing. The TOML format uses simple key-value pairs for tokens that the shell compiles into runtime stylesheets.

### Applying Theme Changes

Activate your custom theme:

```bash
omarchy theme set mytheme

```

This writes generated files to `~/.local/state/omarchy/current/` and updates the active background symlinks. To revert to the default appearance, specify `default` as the theme name.

## Managing Plugins

Plugins are standard Git repositories containing a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) file. The system clones them into `~/.config/omarchy/plugins/<id>/` and registers capabilities with the shell.

### Installing Third-Party Plugins

Add a plugin from any Git URL:

```bash
omarchy plugin add https://github.com/acme/omarchy-weather.git

```

This clones the repository into the plugins directory but does not activate it.

### Enabling and Disabling Plugins

Enable a plugin by its manifest ID:

```bash
omarchy plugin enable community.weather-extra

```

After adding or enabling plugins, rescan and reload:

```bash
omarchy-shell shell rescanPlugins
omarchy-shell shell reloadConfig

```

To remove a plugin, delete its directory from `~/.config/omarchy/plugins/` and remove its ID from the `plugins` array in [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json).

## Restoring Default Settings

To completely reset configuration to the shipped defaults:

```bash
omarchy-reinstall-configs

```

**Warning:** This command copies files from `/etc/skel` (the package seed directory) into your home directory, overwriting existing files under `.config/omarchy/`, `.bashrc`, and other standard locations. Use this when configuration files become corrupted or when you want to start fresh after manual edits.

## Configuration File Locations

Understanding the directory layout helps when troubleshooting or backing up settings:

- **`~/.config/omarchy/shell.json`** – User-editable core configuration (idle timers, bar layout, plugin list)
- **`~/.config/omarchy/themes/`** – Custom theme directories containing [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) and [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml)
- **`~/.config/omarchy/plugins/`** – Cloned Git repositories for third-party extensions
- **`~/.local/state/omarchy/current/`** – Generated theme state and active color schemes (do not edit directly)
- **`~/.local/state/omarchy/done/`** – Idempotency markers for first-run initialization steps
- **`/etc/skel/.config/omarchy/`** – Package defaults that seed new user accounts
- **`/usr/share/omarchy/themes/default/`** – System-wide default theme files

## Summary

- **Primary configuration** happens in `~/.config/omarchy/shell.json`, which controls idle timers, bar position, and widget layout according to the `basecamp/omarchy` source code.
- **Apply changes immediately** by running `omarchy-shell shell reloadConfig` after editing any JSON or TOML configuration file.
- **Customize appearance** by copying `/usr/share/omarchy/themes/default/` to `~/.config/omarchy/themes/<name>` and running `omarchy theme set <name>`.
- **Extend functionality** using `omarchy plugin add <url>` and `omarchy plugin enable <id>`, followed by `omarchy-shell shell rescanPlugins`.
- **Reset to defaults** with `omarchy-reinstall-configs` to restore the original files from `/etc/skel`.

## Frequently Asked Questions

### Where is the main configuration file for Omarchy?

The main configuration file is `~/.config/omarchy/shell.json`. This JSON file defines idle timers (screensaver and lock delays), the top bar position and transparency, the layout of widgets across left/center/right zones, and which third-party plugins are active. If this file does not exist, you can copy it from [`/etc/skel/.config/omarchy/shell.json`](https://github.com/basecamp/omarchy/blob/main//etc/skel/.config/omarchy/shell.json) or create it manually following the schema defined in the repository's [`config/omarchy/shell.json`](https://github.com/basecamp/omarchy/blob/main/config/omarchy/shell.json).

### How do I change the bar position or make it transparent?

You can change the bar position using the CLI command `omarchy bar set position bottom` (replace `bottom` with `top`, `left`, or `right`). For transparency, run `omarchy bar toggleBarTransparency`. Alternatively, edit `~/.config/omarchy/shell.json` directly to set `"position": "bottom"` or `"transparent": true` within the `bar` object, then reload with `omarchy-shell shell reloadConfig`.

### What command reloads the configuration without restarting?

Run `omarchy-shell shell reloadConfig` to re-parse [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json) and apply new widget layouts, idle timers, or theme changes immediately. If you have installed or removed plugins, run `omarchy-shell shell rescanPlugins` first to update the plugin registry, followed by `reloadConfig` to activate the changes.

### How do I restore default configuration if I break something?

Execute `omarchy-reinstall-configs` from a terminal. This command copies the original default files from `/etc/skel` (as defined in the [`file-layout.md`](https://github.com/basecamp/omarchy/blob/main/file-layout.md) documentation) back into your home directory, overwriting any customizations in `.config/omarchy/`, `.bashrc`, and related files. Use this as a last resort when configuration errors prevent the shell from starting correctly.