How Quickshell Desktop is Configured Using shell.json in Omarchy

The Quickshell compositor reads config/omarchy/shell.json to configure idle timers, panel position, and widget layouts through a JSON schema that defines the desktop behavior without requiring code changes.

The omacom/omarchy repository implements a modular desktop environment using the Quickshell compositor. At the heart of its configuration system lies config/omarchy/shell.json, a single JSON file that controls everything from screensaver timing to panel widget placement. Understanding this file allows you to customize your entire desktop layout by editing declarative configuration rather than source code.

Understanding the shell.json Schema Structure

Quickshell validates config/omarchy/shell.json against schema version 1 on startup. The root object contains four primary sections that control distinct aspects of the desktop environment:

• version: An integer defining the configuration schema (currently set to 1)
• idle: Timers for automatic screensaver activation and session locking
• bar: The complete definition of the panel including position, transparency, and widget layout
• plugins: An array of external plugin descriptors (empty by default in Omarchy)

The compositor parses this file during initialization and instantiates the desktop environment according to these specifications.

Configuring Idle Behavior and Session Management

The idle section defines automatic actions triggered by user inactivity. This configuration sits at lines 4-6 of config/omarchy/shell.json and uses time values in seconds:

{
  "idle": {
    "screensaver": 150,
    "lock": 300
  }
}

• screensaver: Seconds of inactivity before the screensaver activates (150 seconds / 2.5 minutes in the default configuration)
• lock: Seconds of inactivity before the session locks automatically (300 seconds / 5 minutes)

Quickshell registers these timers with the underlying compositor to trigger the appropriate security and power management actions.

Customizing the Bar Layout and Widget Positioning

The bar object (lines 7-64) defines the primary panel visible on screen. This section supports four positioning options through the position property: top, bottom, left, or right. The transparent boolean flag controls whether the bar renders with or without a background.

{
  "bar": {
    "position": "top",
    "transparent": true,
    "centerAnchor": true,
    "layout": {
      "left": [...],
      "center": [...],
      "right": [...]
    }
  }
}

The layout object contains three arrays that determine widget placement:

• layout.left: Widgets anchored to the start of the bar
• layout.center: Widgets centered in the bar (requires centerAnchor: true)
• layout.right: Widgets anchored to the end of the bar

Available Widgets and Configuration

Each widget entry requires an id property corresponding to a Quickshell widget implementation. The default Omarchy configuration organizes widgets as follows:

Left section typically contains navigation widgets:

[
  { "id": "omarchy.menu" },
  { "id": "omarchy.workspaces" }
]

Center section hosts status and information widgets with custom formatting options:

[
  { "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 section contains system controls and tray icons:

[
  { "id": "omarchy.tray" },
  { "id": "omarchy.bluetooth" },
  { "id": "omarchy.network" },
  { "id": "omarchy.audio" },
  { "id": "omarchy.monitor" },
  { "id": "omarchy.power" }
]

Widget IDs prefixed with omarchy. correspond to implementations found in the repository's widget configuration files.

Widget Configuration and Supporting Files

While shell.json defines which widgets appear and where, individual widget behavior is configured through separate files in the default/omarchy/ directory. These files use the .jsonc extension and provide the actual implementation details for widgets referenced in the bar layout:

• default/omarchy/omarchy-menu.jsonc: Implements the menu widget (omarchy.menu)
• default/omarchy/omarchy-workspaces.jsonc: Defines the workspace switcher (omarchy.workspaces)
• default/omarchy/omarchy-clock.jsonc: Provides clock formatting options referenced in the center layout
• default/omarchy/omarchy-tray.jsonc: Configures the system tray (omarchy.tray)
• default/omarchy/omarchy-*.jsonc (e.g., omarchy-bluetooth.jsonc, omarchy-network.jsonc): Individual status modules for the right-hand layout

To modify the desktop appearance, edit config/omarchy/shell.json to change widget positions or add new IDs from the available widget pool. For example, changing "position": "bottom" moves the bar to the screen bottom, while adding { "id": "omarchy.brightness" } to layout.right introduces a brightness control widget.

Summary

• Quickshell configuration resides in config/omarchy/shell.json and uses schema version 1
• Idle timers control screensaver activation (150s) and automatic locking (300s)
• Bar positioning supports top, bottom, left, or right placement with optional transparency
• Widget layout uses three arrays (left, center, right) to organize desktop elements
• Supporting files in default/omarchy/*.jsonc define individual widget behavior referenced by ID in the main configuration

Frequently Asked Questions

How do I move the Quickshell bar to the bottom of the screen?

Edit config/omarchy/shell.json and change the position property within the bar object to "bottom". The change takes effect immediately upon restarting Quickshell or reloading the configuration.

What happens if I set the lock timer shorter than the screensaver timer?

If the lock value in the idle section is less than the screensaver value, the session will lock before the screensaver activates. This creates a potential usability issue where the screen locks without visual warning, so Omarchy defaults to 300 seconds for lock and 150 seconds for screensaver.

Can I add custom widgets to the Quickshell layout?

Yes, add new widget objects to any of the three layout arrays (left, center, or right) in shell.json. Each object requires an id property matching a configured widget implementation, such as omarchy.brightness or a custom plugin identifier. Ensure the corresponding .jsonc definition file exists in default/omarchy/ if implementing a new native widget.

Where are the clock format strings defined in Omarchy?

The primary clock format strings reside in default/omarchy/omarchy-clock.jsonc, though they can be overridden per-instance in shell.json using the format, formatAlt, and verticalFormat properties within the clock widget's layout entry. The format follows standard strftime conventions.

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