# How Idle, Lock, and Screensaver Are Configured in Omarchy

> Configure Omarchy idle, lock, and screensaver settings in shell.json. Learn how the idle service plugin manages system idle time and triggers actions with default delays.

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

---

**Idle, lock, and screensaver behavior in Omarchy is controlled via the `idle` block in `~/.config/omarchy/shell.json` and enforced by the idle service plugin at `shell/plugins/services/idle/Service.qml`, which monitors system idle time and triggers actions after default delays of 150 seconds (screensaver) and 300 seconds (lock).**

Omarchy’s idle management system is implemented as a first-party service plugin that watches system activity through an `IdleMonitor` and automates session security. The configuration lives in a simple JSON structure that controls when the screensaver activates and when the session locks.

## Configuration File Structure

The idle, lock, and screensaver timings are defined in the `idle` block of your user configuration file. Create or edit `~/.config/omarchy/shell.json` to customize the behavior:

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

```

- **`screensaver`**: Seconds of inactivity before the screensaver launches (default: 150, or 2 minutes 30 seconds)
- **`lock`**: Seconds of inactivity before the session locks (default: 300, or 5 minutes)

If the `idle` block is omitted, the service falls back to constants defined as `defaultScreensaverSeconds` and `defaultLockSeconds` in the service implementation.

## Core Service Architecture

The idle service is implemented in `shell/plugins/services/idle/Service.qml`. This service registers an `"idle"` IPC target via `IpcHandler`, exposing methods including `status`, `enable`, `disable`, and `toggle` for external control.

When the `IdleMonitor` detects an idle transition (`idleMonitor.isIdle` becomes `true`), the service initiates an idle cycle by calling `startIdleCycle`.

### Timer Calculation and Scheduling

The service calculates timeouts dynamically to ensure efficient scheduling:

1. **Calculate earliest timeout**: The service determines `firstIdleTimeoutSeconds` as the minimum of the configured screensaver and lock values.
2. **Schedule delays**: It computes `screensaverDelaySeconds` and `lockDelaySeconds` as the offset from the earliest timeout to each specific action.
3. **Initialize timers**: The `screensaverTimer` and `lockTimer` are started with these calculated delays.

The helper functions in [`shell/plugins/services/idle/IdleModel.js`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/services/idle/IdleModel.js)—specifically `secondsFromConfig`—handle validation of numeric values from the JSON configuration and enforce safe fallbacks.

### Screensaver and Lock Execution

When timers fire, the service executes specific system commands:

- **Screensaver launch**: Triggered by `screensaverTimer`, calling `omarchy-launch-screensaver` unless the system is already locked (checked via `omarchy-shell lock isLocked`).
- **Session lock**: Triggered by `lockTimer`, executing `omarchy-system-lock`.

A third timer, `screensaverLaunchGraceTimer`, handles edge cases such as the screensaver being dismissed manually before the lock deadline expires.

## Stay-Awake Mode and Manual Control

Omarchy provides a **stay-awake** state that prevents idle actions regardless of system inactivity. Toggle this mode using the keyboard shortcut `Super + Ctrl + I` or via the command line:

```bash

# Toggle stay-awake on/off

omarchy toggle idle

# Check current status

omarchy toggle idle status

```

When `stayAwake` is enabled, `idleEnabled` becomes `false`, canceling any pending idle cycle and preventing timer initialization. The stay-awake flag persists across shell restarts by writing to `~/.local/state/omarchy/indicators/stay-awake`, which the service watches for external changes to keep the UI synchronized.

## Practical Configuration Examples

### Modify Idle Timings

To set the screensaver to activate after 1 minute and lock after 3 minutes:

```bash
$EDITOR ~/.config/omarchy/shell.json

```

Add the configuration:

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

```

Changes are picked up automatically. Verify the active configuration via IPC:

```bash
omarchy-shell call idle status

```

### Temporarily Disable Idle Lock

For presentations or long-running tasks:

```bash
omarchy toggle idle
omarchy toggle idle status | jq '.stayAwake'

```

### Force Immediate Screensaver (Testing)

Bypass the idle timer for immediate testing:

```bash
omarchy launch screensaver

```

### Query Detailed Service Status

Retrieve complete idle state information:

```bash
omarchy-shell call idle status

```

Sample output includes:

```json
{
  "enabled": true,
  "stayAwake": false,
  "idle": false,
  "screensaver": 150,
  "lock": 300,
  "screensaverDelay": 0,
  "lockDelay": 150
}

```

## Summary

- **Configuration location**: Define timings in the `idle` block of `~/.config/omarchy/shell.json` using numeric seconds.
- **Default behavior**: Screensaver activates after 150 seconds; lock engages after 300 seconds.
- **Implementation**: Core logic resides in `shell/plugins/services/idle/Service.qml` with helpers in [`IdleModel.js`](https://github.com/basecamp/omarchy/blob/main/IdleModel.js).
- **Manual override**: Use `omarchy toggle idle` or `Super + Ctrl + I` to enable stay-awake mode, persisting state to `~/.local/state/omarchy/indicators/stay-awake`.
- **IPC interface**: Query and control the service via `omarchy-shell call idle <command>`.

## Frequently Asked Questions

### How do I change the idle lock time in Omarchy?

Edit `~/.config/omarchy/shell.json` and set the `idle.lock` value to the desired number of seconds. For example, `"lock": 600` sets the lock timer to 10 minutes. The service automatically reloads this configuration without requiring a restart.

### What files control the idle, lock, and screensaver behavior?

The primary service implementation is located at `shell/plugins/services/idle/Service.qml`, with configuration parsing handled by [`shell/plugins/services/idle/IdleModel.js`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/services/idle/IdleModel.js). User settings are read from `~/.config/omarchy/shell.json`, and the stay-awake state is stored in `~/.local/state/omarchy/indicators/stay-awake`.

### Why does my screensaver not start even after the configured time?

Check if stay-awake mode is active by running `omarchy toggle idle status`. If `stayAwake` returns `true`, idle detection is disabled. Additionally, the screensaver will not launch if the session is already locked, as the service checks `omarchy-shell lock isLocked` before invoking `omarchy-launch-screensaver`.

### Can I disable the idle lock temporarily without editing the config file?

Yes. Run `omarchy toggle idle` to immediately disable idle detection for the current session. This sets `idleEnabled` to false and cancels any pending timers. Toggle again to resume normal idle behavior. This state persists across shell restarts via the stay-awake indicator file.