• xidlehook
  • Example
  • Installation
    • Other installation methods
  • Socket API
  • Caffeinate
  • Configuring via systemd
  • Troubleshooting

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 through chain 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/bin/env 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 60 \
    'xrandr --output "$PRIMARY_DISPLAY" --brightness .1' \
    'xrandr --output "$PRIMARY_DISPLAY" --brightness 1' \
  `# Undim & lock after 10 more seconds` \
  --timer 10 \
    'xrandr --output "$PRIMARY_DISPLAY" --brightness 1; i3lock' \
    '' \
  `# Finally, suspend an hour after it locks` \
  --timer 3600 \
    'systemctl suspend' \
    ''

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

As of currently, you will need to use the Rust 1.39.0 higher when building xidlehook.

Recommended installation is through the Nix package manager, which will get you a sane default configuration of xidlehook as well as all required libraries.

nix-env -iA nixpkgs.xidlehook

will install xidlehook regardless of whether you have rust installed, regardless of whether you have libxcb and friends installed, whatever. Nix just works.

If you instead would like to use the latest master, you can install it using the following.

nix-env -if https://gitlab.com/jD91mZM2/xidlehook/-/archive/master.tar.gz

While I do definitely encourage you to try Nix if you haven't already, there are other ways to install xidlehook, of course. But it will involve some system-specific trouble I can't really help you with.

Arch Linux users can avoid that, however, thanks to an unofficial AUR package!

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

After getting these native libraries, one way of installing is with cargo, the official rust package manager that works almost everywhere with rust installed.

cargo install xidlehook --bins

Or if you want to clone it manually:

git clone https://gitlab.com/jD91mZM2/xidlehook
cd xidlehook
cargo build --release --bins

The socket API can be communicated with over JSON. The full data and types for these structures can be seen in all the struct definitions of xidlehook/src/socket/models.rs.

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 first decide what ID the timer has, either by counting the indexes yourself of the timers you inform xidlehook of (starting from 0), or by querying timer information after starting it:

# Check what timer(s) you want to trigger...
xidlehook-client --socket /path/to/xidlehook.sock query

And then bind a hotkey or bash alias to lock it:

# Trigger it/them
xidlehook-client --socket /path/to/xidlehook.sock control --action trigger --timer <my timer id>

If you're looking for a more elaborate client to temporarily disable xidlehook, take a look at caffeinate which has timers and PID based monitoring.

If you use a distribution that uses systemd for its init system, you may wish to use it to ensure that xidlehook is always started when you log in. You can do this at the level of an individual user by placing the following service file at $XDG_CONFIG_HOME/systemd/user/xidlehook.service (typically $HOME/.config/systemd/user/xidlehook.service):

[Unit]
Description=Automatic Screen Locker

[Service]
Type=simple
Environment=DISPLAY=:0
Environment=XIDLEHOOK_SOCK=%t/xidlehook.socket
ExecStart=/usr/bin/xidlehook --not-when-audio --not-when-fullscreen --socket $XIDLEHOOK_SOCK --timer 900 '/usr/bin/slock' ''

[Install]
WantedBy=multi-user.target

The above service file example locks the screen using the slock program after 15 minutes of inactivity, but you can edit it the xidlehook command to do anything you wish. We need to thread the DISPLAY environment variable down so that xidlehook knows how to open up a connection to the X server.

If you have redshift running, the brightness of your screen will be quickly overriden by redshift. You can specify the brightness of the screen via redshift instead of xrandr to fix this issue.