How to Configure Idle Timers for Screensaver and Lock in Omarchy

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:

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

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:

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:

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 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. 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.

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