#time #extra #gitlab #command #xautolock #rewrite #work #computer

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
Download history 96/week @ 2019-03-21 20/week @ 2019-03-28 19/week @ 2019-04-04 31/week @ 2019-04-11 4/week @ 2019-04-18 21/week @ 2019-04-25 9/week @ 2019-05-02 49/week @ 2019-05-09 30/week @ 2019-05-16 30/week @ 2019-05-23 24/week @ 2019-05-30 25/week @ 2019-06-06 83/week @ 2019-06-13 65/week @ 2019-06-20 65/week @ 2019-06-27

124 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 https://gitlab.com/jD91mZM2/xidlehook
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)


~60K SLoC