app xidlehook

xautolock rewrite in Rust, with a few extra features

19 unstable releases (5 breaking)

0.7.1 Apr 29, 2019
0.6.2 Mar 13, 2019
0.6.1 Nov 17, 2018
0.4.9 Jun 25, 2018
0.4.4 Feb 6, 2018

#20 in GUI

Download history 7/week @ 2019-01-12 4/week @ 2019-01-19 6/week @ 2019-01-26 7/week @ 2019-02-02 4/week @ 2019-02-09 20/week @ 2019-02-16 8/week @ 2019-02-23 34/week @ 2019-03-02 37/week @ 2019-03-09 5/week @ 2019-03-16 113/week @ 2019-03-23 3/week @ 2019-03-30 31/week @ 2019-04-06 19/week @ 2019-04-13 5/week @ 2019-04-20

98 downloads per month

Custom license

652 lines


Because xautolock is annoying to work with.

xidlehook is a general-purpose replacement for xautolock. It executes a command when the computer has been idle for a specified amount of time.

Improvements over xautolock:

  • Allows "cancellers" which can undo a timer action when new user activity is detected.
  • Unlimited amount of timers (provided necessary resources).
  • Not specific to locking.
  • Multiple instances can run at the same time.
  • Optionally only run once.
  • Optionally prevent locking when an application is fullscreen.
  • Optionally prevent locking when any application plays audio.

Missing features:

  • Magic corners.
  • All the instance related stuff (you should use unix sockets with --socket).


Here's a lock using i3lock, with screen dim support:

#!/usr/env/bin bash

# Only exported variables can be used within the timer's command.
export PRIMARY_DISPLAY="$(xrandr | awk '/ primary/{print $1}')"

# Run xidlehook
xidlehook \
  `# Don't lock when there's a fullscreen application` \
  --not-when-fullscreen \
  `# Don't lock when there's audio playing` \
  --not-when-audio \
  `# Dim the screen after 60 seconds, undim if user becomes active` \
  --timer normal 60 \
    'xrandr --output "$PRIMARY_DISPLAY" --brightness .1' \
    'xrandr --output "$PRIMARY_DISPLAY" --brightness 1' \
  `# Undim & lock after 10 more seconds` \
  --timer primary 10 \
    'xrandr --output "$PRIMARY_DISPLAY" --brightness 1; i3lock' \
    '' \
  `# Finally, suspend an hour after it locks` \
  --timer normal 3600 \
    'systemctl suspend' \

Note: Every command is passed through sh -c, so you should be able to mostly use normal syntax.


Installation using cargo:

cargo install xidlehook

Xidlehook with the default settings requires libXScrnSaver (or libxss) and libpulseaudio. On debian/ubuntu, don't forget to install the -dev versions, also.

It's also available on Nix and the AUR (not officially maintained).

Or if you want to clone it manually:

git clone
cd xidlehook
cargo build --release

Too bloaty?

Not using pulseaudio?
Disable that requirement completely with --no-default-features!
This, however, will get rid of the --not-when-audio option.

Socket API

The socket API is very simple. Each command is a single byte, sent over a unix socket. Bind a file using --socket /path/to/xidlehook.sock (where the path is whatever you want), and then you can send one of the following bytes:

Byte Command
0 Deactivate
1 Activate
2 Run the timer command immediately

For convenience, there is now an xidlehook-client (see #18), which will communicate with this API for you. See

xidlehook-client --help

for details.

A common use case of xidlehook is using it to run a lockscreen. To then manually lock the screen, you could bind this bash command to a shortcut:

xidlehook-client --trigger --socket /path/to/xidlehook.sock

Alternatively, you can use the API directly using, for example, socat:

echo -ne "\x0" | socat - UNIX-CONNECT:/path/to/xidlehook.sock

(You have no reason to run this for the most cases anymore)


~58K SLoC