How Idle, Lock, and Screensaver Are Configured in Omarchy

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:

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

# 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:

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

Add the configuration:

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

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

omarchy-shell call idle status

Temporarily Disable Idle Lock

For presentations or long-running tasks:

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

Force Immediate Screensaver (Testing)

Bypass the idle timer for immediate testing:

omarchy launch screensaver

Query Detailed Service Status

Retrieve complete idle state information:

omarchy-shell call idle status

Sample output includes:

{
  "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.
• 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. 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.

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