# How Quickshell Desktop is Configured Using shell.json in Omarchy

> Configure Quickshell desktop using shell.json in Omarchy. Define idle timers, panel position, and widget layouts through a JSON schema without code changes.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-08

---

**The Quickshell compositor reads [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) and uses time values in seconds:

```json
{
  "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.

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

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

```

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

```json
[
  { "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:

```json
[
  { "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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/shell.json) using the `format`, `formatAlt`, and `verticalFormat` properties within the clock widget's layout entry. The format follows standard strftime conventions.