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

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

{
  "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:

{
  "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, apply changes without restarting the session:

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 (palette definitions) and 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:

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

Edit colors.toml to modify foreground, background, and accent colors, or adjust 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:

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

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:

omarchy plugin enable community.weather-extra

After adding or enabling plugins, rescan and reload:

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.

Restoring Default Settings

To completely reset configuration to the shipped defaults:

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 and 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 or create it manually following the schema defined in the repository's 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 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 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.

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