Omarchy Shell Configuration (shell.json) Reference: A Complete Guide

The shell.json file in ~/.config/omarchy/ is the central configuration that controls the Omarchy Quickshell environment, including the status bar layout, plugins, and idle behavior, with hot-reloading support that applies changes instantly without restarting.

The Omarchy shell configuration drives every aspect of the Quickshell desktop environment, from widget placement to screen locking behavior. This JSON-based configuration file defines how the status bar renders, which plugins are active, and when the screensaver activates. Understanding its structure is essential for customizing the Omarchy experience according to the omacom/omarchy source code.

Configuration File Location and Loading Behavior

The shell loads configuration from two possible locations, prioritizing user customizations over system defaults shipped in the repository.

Default vs. User Configuration

When no personal configuration exists, the shell loads defaults from config/omarchy/shell.json within the Omarchy repository. This file ships with the application and provides the baseline settings for the status bar, plugins, and idle timers. However, once you create or modify ~/.config/omarchy/shell.json, the shell switches to user-mode operation exclusively.

Canonical Mode and Hot-Reloading

After you edit ~/.config/omarchy/shell.json, the file becomes canonical—the shell stops merging default values and uses your file verbatim. This means new default widgets added in future Omarchy releases will not appear automatically; you must add them manually to your configuration if desired. The shell hot-reloads this file on every save, so no restart is required to see changes.

Key Configuration Sections

The shell.json structure consists of several top-level blocks that control specific shell behaviors, documented in shell/README.md.

Bar Settings (bar block)

The bar object holds all status-bar-related settings, including position and layout. This block controls where the bar appears on screen and how widgets are arranged within it. You can modify bar position using the CLI helper:

omarchy bar set position top

This command updates the bar.position field in your user configuration file and triggers an immediate reload.

Plugin Management (plugins and disabledPlugins)

The plugins[] array lists third-party plugins that should be enabled, while disabledPlugins[] contains first-party plugins that have been turned off. As documented in manual/32-shell-plugins.md, Omarchy distinguishes between built-in plugins (which you disable) and external plugins (which you explicitly enable).

To enable a third-party plugin, add its ID to the plugins array:

jq '.plugins += ["myWidget"]' ~/.config/omarchy/shell.json > tmp && mv tmp ~/.config/omarchy/shell.json

To disable a built-in plugin like "network":

jq '.disabledPlugins += ["network"]' ~/.config/omarchy/shell.json > tmp && mv tmp ~/.config/omarchy/shell.json

The plugin remains present in the codebase but will not be loaded by the shell.

Idle and Screensaver Settings (idle block)

The idle block controls screensaver and lock timers. For example, setting idle.lock to 600 locks the screen after ten minutes of inactivity, as explained in manual/13-toggles-idle-screensaver.md. This section manages power management and security behaviors.

To set the idle lock timeout:

jq '.idle.lock = 600' ~/.config/omarchy/shell.json > tmp && mv tmp ~/.config/omarchy/shell.json

Inspecting and Managing Configuration

Omarchy provides CLI helpers to interact with shell.json without manual JSON editing, documented in docs/omarchy-shell.md.

Viewing Effective Configuration

To see the complete configuration currently in use—including merged defaults when no user file exists—run:

omarchy listShellConfig

This outputs the full JSON view that the shell is actively using, helpful for debugging configuration issues and verifying your changes.

CLI Configuration Helpers

Instead of editing JSON directly, you can use commands like omarchy bar set and omarchy bar defaults to manipulate specific values. These helpers validate input and ensure proper JSON structure while safely updating ~/.config/omarchy/shell.json.

Summary

• shell.json is the single source of truth for Omarchy Quickshell configuration, stored in ~/.config/omarchy/shell.json.
• The file becomes canonical once edited, meaning new default widgets from updates won't appear unless manually added to your configuration.
• Configuration changes hot-reload instantly without requiring a shell restart.
• Key sections include bar (layout), plugins[] (third-party), disabledPlugins[] (built-in), and idle (screensaver/lock).
• Use omarchy listShellConfig to view the effective configuration and omarchy bar set for simple modifications.

Frequently Asked Questions

Where is the Omarchy shell configuration file located?

The user-specific configuration file is located at ~/.config/omarchy/shell.json. If this file does not exist, the shell falls back to the default configuration shipped with the application at config/omarchy/shell.json in the Omarchy repository at omacom/omarchy.

How do I view the current effective configuration?

Run omarchy listShellConfig in your terminal. This command prints the complete JSON configuration that the shell is currently using, showing either the merged defaults or your canonical user configuration depending on whether you have customized the file.

Why aren't new default widgets appearing after an Omarchy update?

Once you edit ~/.config/omarchy/shell.json, it becomes a canonical configuration file. The shell stops merging new default widgets from updates into your setup. To add new default features introduced in updates, you must manually edit your configuration file to include them.

How do I disable a built-in plugin without deleting its files?

Add the plugin ID to the disabledPlugins array in your shell.json. For example, to disable the network plugin, use jq '.disabledPlugins += ["network"]' ~/.config/omarchy/shell.json. The plugin files remain in the codebase at their original locations but will not be loaded by the shell.

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