# How to Configure Idle Timers for Screensaver and Lock in Omarchy

> Learn how to configure idle timers for screensaver and lock in Omarchy. Easily adjust settings in shell.json or use the omarchy toggle CLI for custom idle durations.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-21

---

**Omarchy uses a Quickshell-based idle service that reads timer values from `~/.config/omarchy/shell.json`, defaulting to 150 seconds for the screensaver and 300 seconds for the lock, which you can override by editing the `idle` block or control via the `omarchy toggle` CLI.**

Omarchy is a custom desktop environment developed by Basecamp that manages session idle behavior through a dedicated idle service. Configuring idle timers for screensaver and lock in Omarchy involves modifying a JSON configuration file or using command-line toggles to adjust when the screensaver launches and when the session locks after inactivity. The system reads these values from the `idle` block in your shell configuration and applies them immediately without requiring a restart.

## How the Idle Service Works

Omarchy's idle handling is driven by the **idle service** (`omarchy.idle`), implemented in `shell/plugins/services/idle/Service.qml`. This service monitors user inactivity through an **idle monitor** (`idleMonitor`) that reports the system idle state.

When the system becomes idle, the service executes `startIdleCycle()`, which manages two independent timers:

- **Screensaver timer**: Triggers the screensaver after the configured seconds of inactivity (default: **150 seconds**)
- **Lock timer**: Engages the session lock after the configured seconds of inactivity (default: **300 seconds**)

The service loads these values via the `idleConfig` property and converts them using `secondsFromConfig`, falling back to defaults if the configuration is missing or malformed. If the lock timer expires, the service calls `lockSystem("lock-timeout")`, which invokes the lock plugin at `shell/plugins/lock/Service.qml`.

The idle service also respects a **stay awake** flag. When enabled via `omarchy toggle idle`, the `stayAwake` property disables both timers until the flag is cleared.

## Configuring Timer Values in shell.json

Edit `~/.config/omarchy/shell.json` to customize the idle timers. Add or modify the `idle` block with your preferred values in seconds:

```json
{
  "idle": {
    "screensaver": 180,
    "lock": 420
  }
}

```

- **`screensaver`**: Seconds of inactivity before the screensaver launches.
- **`lock`**: Seconds of inactivity before the session locks.

The file is re-read automatically by the shell; no restart is required. Values are coerced to integers, and invalid entries fall back to the defaults of 150 seconds for the screensaver and 300 seconds for the lock.

## Controlling Idle Behavior via CLI

Omarchy provides command-line tools to manage idle state without editing configuration files.

### Toggle Stay-Awake Mode

Prevent idle timers from triggering entirely:

```bash
omarchy toggle idle

```

This sets the `stayAwake` flag in the idle service, disabling both the screensaver and lock timers until toggled off.

### Query Current Status

Check the current idle configuration and state:

```bash
omarchy toggle idle status

```

This returns a JSON summary including enabled status, idle state, and current timeout values. You can also use `shell_ipc idle status` for direct IPC queries.

### Force Screensaver

Launch the screensaver immediately, bypassing the stay-awake flag:

```bash
omarchy toggle screensaver

```

This invokes the screensaver directly through the `omarchy-toggle-idle` binary wrapper.

## Key Source Files

Understanding the implementation requires examining these specific files in the `basecamp/omarchy` repository:

- **`shell/plugins/services/idle/Service.qml`**: Core idle detection, timer calculation using `secondsFromConfig`, and IPC handling. This file contains the `idleConfig` property and `startIdleCycle()` method.
- **`shell/plugins/lock/Service.qml`**: Implements the lock action triggered when `lockSystem("lock-timeout")` is called by the idle service.
- **`bin/omarchy-toggle-idle`**: CLI wrapper that invokes the idle service's public methods for toggling the `stayAwake` flag and querying state.

## Summary

- Omarchy's idle timers are configured in `~/.config/omarchy/shell.json` under the `idle` block with `screensaver` and `lock` keys.
- Default values are **150 seconds** for the screensaver and **300 seconds** for the session lock.
- The idle service (`shell/plugins/services/idle/Service.qml`) uses `secondsFromConfig` to parse values and triggers `lockSystem("lock-timeout")` when the lock timer expires.
- Use `omarchy toggle idle` to enable stay-awake mode and prevent idle actions temporarily.
- Changes to [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json) take effect immediately without restarting the shell.

## Frequently Asked Questions

### How do I completely disable the idle lock in Omarchy?

Set the `lock` value to a very large number or use `omarchy toggle idle` to enable stay-awake mode. The toggle sets the `stayAwake` flag in the idle service, which prevents both the screensaver and lock timers from triggering until you toggle it again.

### What happens if I set the lock timer lower than the screensaver timer?

The timers operate independently based on the idle start time. If you set `lock` to 120 seconds and `screensaver` to 180 seconds, the session will lock after 120 seconds of inactivity, and if activity resumes, the screensaver timer resets accordingly. The lock timer does not wait for the screensaver to finish.

### Where does Omarchy store the default idle timer values?

Default values (150 seconds for screensaver, 300 seconds for lock) are hardcoded in `shell/plugins/services/idle/Service.qml` as fallbacks when `secondsFromConfig` cannot parse valid integers from the `idle` block in [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json). The service checks these defaults when the configuration entries are missing or malformed.

### Can I trigger the screensaver manually while stay-awake is active?

Yes. Use `omarchy toggle screensaver` to force the screensaver immediately. This command bypasses the `stayAwake` flag and invokes the screensaver window creation directly through the idle service's public methods.