How to Configure the Omarchy Shell: Complete Guide to shell.json

The Omarchy shell reads its configuration from a JSON file named shell.json located at ~/.config/omarchy/shell.json, which overrides the default configuration at config/omarchy/shell.json in the repository.

Omarchy is a Wayland compositor with an integrated shell system that renders the status bar, widgets, and plugin interfaces. Understanding how to configure the Omarchy shell is essential for customizing your desktop environment. This guide covers the configuration file structure, CLI commands, and programmatic interfaces based on the Omarchy source code.

Configuration File Locations

The Omarchy shell uses a two-tier configuration system:

• config/omarchy/shell.json — Shipped with the repository as the baseline configuration
• ~/.config/omarchy/shell.json — User-editable file that completely overrides the default when present and valid

In shell/shell.qml, the shell defines these paths as:

property var defaultsPath: omarchyPath + "/config/omarchy/shell.json"
property var userConfigPath: home + "/.config/omarchy/shell.json"

The loading algorithm at lines 73–102 follows this priority:

1. If userConfigPath exists and parses to a valid object, use it
2. Otherwise, load defaultsPath
3. If parsing fails, log a warning and fall back to builtin defaults

Structure of shell.json

The shell.json file follows a strict schema validated on load. Here is the complete structure:

{
  "version": 1,
  "bar": {
    "id": "local.demo-bar",
    "transparent": false,
    "layout": {
      "left": [
        {"type": "command", "command": "date", "settings": {}}
      ],
      "center": [],
      "right": []
    }
  },
  "plugins": []
}

Required Fields

Field	Type	Description
version	integer	Schema version; must be 1
bar	object	Bar configuration container
bar.layout	object	Contains left, center, right arrays

Bar Layout Widgets

Each widget entry in the layout arrays supports:

• type — Either "command" (executes shell command) or "qml" (loads QML component)
• command — For command type: the shell command to execute
• id — Optional identifier for the widget instance
• settings — Per-widget configuration object

The transparent boolean controls whether the bar background renders transparent.

Plugin System

The top-level plugins array contains plugin IDs that should be enabled. The shell/services/PluginRegistry.qml processes this list to activate corresponding features.

CLI Configuration Commands

Omarchy provides built-in CLI helpers for managing shell.json without manual editing:

omarchy bar set

Creates or updates a widget entry in the specified bar section:

omarchy bar set \
  --section=center \
  --id=my.custom.clock \
  --type=command \
  --command='date "+%H:%M:%S"' \
  --settings='{"interval": 1000}'

omarchy bar position

Updates bar positioning fields without touching other configuration:

omarchy bar position --anchor=top --margin=4

omarchy-refresh-config

Copies the default configuration to the user location with automatic backup:

omarchy-refresh-config omarchy/shell.json

This command is idempotent: it preserves existing user files by renaming them with timestamps before overwriting.

omarchy bar reload

Triggers the running shell to re-read shell.json without restarting the compositor:

omarchy bar reload

Programmatic Configuration Access

The shell exposes the effective configuration through shell.getEffectiveConfig() (line 991 in shell/shell.qml). This method returns the merged configuration after processing user overrides and applying defaults.

For development sessions, the shell watches shell.json for filesystem changes. In production builds, explicit omarchy bar reload is required.

Practical Configuration Examples

Add a Custom Status Widget

# Add CPU usage display to the right side of the bar

omarchy bar set \
  --section=right \
  --id=custom.cpu \
  --type=command \
  --command="grep -o '^[0-9]*' /proc/stat | head -1 | awk '{print \"CPU: \" $1}'" \
  --settings='{"interval": 2000}'

omarchy bar reload

Enable Multiple Plugins

# Modify plugins array directly with jq

jq '.plugins = ["weather", "system-monitor", "notifications"]' \
  ~/.config/omarchy/shell.json > /tmp/shell.json.tmp \
  && mv /tmp/shell.json.tmp ~/.config/omarchy/shell.json

omarchy bar reload

Reset to Factory Defaults

# Backup current config and restore defaults

omarchy-refresh-config omarchy/shell.json
omarchy bar reload

Create Transparent Bar

# Edit directly for settings not exposed via CLI

jq '.bar.transparent = true' ~/.config/omarchy/shell.json > /tmp/shell.json.tmp \
  && mv /tmp/shell.json.tmp ~/.config/omarchy/shell.json

omarchy bar reload

Schema Validation

The Omarchy test suite validates shell.json structure in test/shell.d/config-test.sh (lines 16–17). Invalid configurations trigger fallback to defaults with console warnings. Required validation rules include:

• version field must exist and equal 1
• bar must be an object with layout containing three array properties
• plugins must be an array of strings

Key Source Files

File	Purpose
shell/shell.qml	Core loader and configuration watching logic
config/omarchy/shell.json	Repository default configuration
shell/services/PluginRegistry.qml	Plugin enablement based on plugins array
shell/README.md	Human-readable schema documentation
test/shell.d/config-test.sh	Automated schema validation tests

Summary

• User configuration lives at ~/.config/omarchy/shell.json and completely overrides repository defaults
• Required fields are version, bar.layout.left/center/right, and optionally plugins
• CLI commands (omarchy bar set, omarchy bar reload) provide safe editing without syntax errors
• Changes require explicit reload via omarchy bar reload in production builds
• Invalid configurations fall back to defaults with logged warnings per shell/shell.qml lines 73–84

Frequently Asked Questions

What happens if my shell.json has a syntax error?

The Omarchy shell validates the user file on load. If parsing fails or the version field is missing, the shell falls back to the repository default at config/omarchy/shell.json and prints a warning to the console. This behavior is implemented in shell/shell.qml lines 73–84.

Can I use the shell without a user configuration file?

Yes. If ~/.config/omarchy/shell.json does not exist, Omarchy automatically uses the default configuration shipped with the repository. This is the standard experience for new installations.

How do I reload configuration without losing my open windows?

Use omarchy bar reload from a terminal or keybinding. This command signals the running shell process to re-parse shell.json and update the bar layout without restarting the Wayland compositor or affecting running applications.

Where is the complete schema documentation?

The authoritative schema reference is shell/README.md in the repository. Additionally, the test file test/shell.d/config-test.sh contains the machine-validated assertions that define valid configuration structures.

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