{"id":16336786,"url":"https://github.com/jd91mzm2/xidlehook","last_synced_at":"2025-04-05T19:12:27.043Z","repository":{"id":38898103,"uuid":"119992165","full_name":"jD91mZM2/xidlehook","owner":"jD91mZM2","description":"GitLab: https://gitlab.com/jD91mZM2/xidlehook","archived":false,"fork":false,"pushed_at":"2023-02-13T17:11:12.000Z","size":417,"stargazers_count":398,"open_issues_count":34,"forks_count":35,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-29T18:07:22.163Z","etag":null,"topics":["lockscreen","x11","xautolock"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jD91mZM2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-02-02T14:34:48.000Z","updated_at":"2025-03-24T13:09:20.000Z","dependencies_parsed_at":"2024-01-14T04:34:40.160Z","dependency_job_id":"a0b16d40-7d2d-4248-b8b6-1fdc9ec16543","html_url":"https://github.com/jD91mZM2/xidlehook","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jD91mZM2%2Fxidlehook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jD91mZM2%2Fxidlehook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jD91mZM2%2Fxidlehook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jD91mZM2%2Fxidlehook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jD91mZM2","download_url":"https://codeload.github.com/jD91mZM2/xidlehook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247386265,"owners_count":20930619,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lockscreen","x11","xautolock"],"created_at":"2024-10-10T23:44:59.342Z","updated_at":"2025-04-05T19:12:27.010Z","avatar_url":"https://github.com/jD91mZM2.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"-   [xidlehook](#xidlehook)\n    -   [Example](#example)\n    -   [Installation](#installation)\n        -   [Other installation methods](#other-installation-methods)\n    -   [Socket API](#socket-api)\n    -   [Caffeinate](#caffeinate)\n    -   [Configuring via `systemd`](#configuring-via-systemd)\n    -   [Troubleshooting](#troubleshooting)\n\n# xidlehook\n\n*Because xautolock is annoying to work with.*\n\nxidlehook is a general-purpose replacement for\n[xautolock](https://linux.die.net/man/1/xautolock). It executes a\ncommand when the computer has been idle for a specified amount of time.\n\n**Improvements over xautolock:**\n\n-   Allows \"cancellers\" which can undo a timer action when new user\n    activity is detected.\n-   Unlimited amount of timers (provided necessary resources).\n-   Not specific to locking.\n-   Multiple instances can run at the same time.\n-   Optionally only run through chain once.\n-   Optionally prevent locking when an application is fullscreen.\n-   Optionally prevent locking when any application plays audio.\n\n**Missing features:**\n\n-   Magic corners\n-   All the instance related stuff (you should use unix sockets with\n    –socket).\n\n## Example\n\nHere's a lock using i3lock, with screen dim support:\n\n``` bash\n#!/usr/bin/env bash\n\n# Only exported variables can be used within the timer's command.\nexport PRIMARY_DISPLAY=\"$(xrandr | awk '/ primary/{print $1}')\"\n\n# Run xidlehook\nxidlehook \\\n  `# Don't lock when there's a fullscreen application` \\\n  --not-when-fullscreen \\\n  `# Don't lock when there's audio playing` \\\n  --not-when-audio \\\n  `# Dim the screen after 60 seconds, undim if user becomes active` \\\n  --timer 60 \\\n    'xrandr --output \"$PRIMARY_DISPLAY\" --brightness .1' \\\n    'xrandr --output \"$PRIMARY_DISPLAY\" --brightness 1' \\\n  `# Undim \u0026 lock after 10 more seconds` \\\n  --timer 10 \\\n    'xrandr --output \"$PRIMARY_DISPLAY\" --brightness 1; i3lock' \\\n    '' \\\n  `# Finally, suspend an hour after it locks` \\\n  --timer 3600 \\\n    'systemctl suspend' \\\n    ''\n```\n\n*Note: Every command is passed through `sh -c`, so you should be able to\nmostly use normal syntax.*\n\n## Installation\n\n*As of currently, you will need to use the Rust 1.39.0 higher when\nbuilding xidlehook.*\n\nRecommended installation is through the [Nix package\nmanager](https://nixos.org/nix/), which will get you a sane default\nconfiguration of xidlehook as well as all required libraries.\n\n``` bash\nnix-env -iA nixpkgs.xidlehook\n```\n\nwill install xidlehook regardless of whether you have rust installed,\nregardless of whether you have libxcb and friends installed, whatever.\nNix just works.\n\nIf you instead would like to use the latest master, you can install it\nusing the following.\n\n``` bash\nnix-env -if https://gitlab.com/jD91mZM2/xidlehook/-/archive/master.tar.gz\n```\n\n### Other installation methods\n\nWhile I do definitely encourage you to try Nix if you haven't already,\nthere are other ways to install xidlehook, of course. But it will\ninvolve some system-specific trouble I can't really help you with.\n\nArch Linux users can avoid that, however, thanks to an [unofficial AUR\npackage](https://aur.archlinux.org/packages/xidlehook/)!\n\nXidlehook with the default settings requires **libxcb**,\n**libXScrnSaver** (or libxss) and **libpulseaudio**. On debian/ubuntu,\ndon't forget to install the `-dev` versions of all the mentioned\ndependencies, also.\n\n| Which feature flag?                  | Native dependency                  |\n|--------------------------------------|------------------------------------|\n| Always                               | libxcb, libXScrnSaver (aka libxss) |\n| When using –features pulse (default) | libpulseaudio                      |\n\nAfter getting these native libraries, one way of installing is with\ncargo, the official rust package manager that works almost everywhere\nwith rust installed.\n\n``` bash\ncargo install xidlehook --bins\n```\n\nOr if you want to clone it manually:\n\n``` bash\ngit clone https://gitlab.com/jD91mZM2/xidlehook\ncd xidlehook\ncargo build --release --bins\n```\n\n## Socket API\n\nThe socket API can be communicated with over JSON. The full data and\ntypes for these structures can be seen in all the struct definitions of\n`xidlehook/src/socket/models.rs`.\n\nFor convenience, there is now an xidlehook-client (see\n[\\#18](https://github.com/jD91mZM2/xidlehook/pull/18)), which will\ncommunicate with this API for you. See\n\n``` bash\nxidlehook-client --help\n```\n\nfor details.\n\nA common use case of `xidlehook` is using it to run a lockscreen. To\nthen manually lock the screen, you could first decide what ID the timer\nhas, either by counting the indexes yourself of the timers you inform\nxidlehook of (starting from 0), or by querying timer information after\nstarting it:\n\n``` bash\n# Check what timer(s) you want to trigger...\nxidlehook-client --socket /path/to/xidlehook.sock query\n```\n\nAnd then bind a hotkey or bash alias to lock it:\n\n``` bash\n# Trigger it/them\nxidlehook-client --socket /path/to/xidlehook.sock control --action trigger --timer \u003cmy timer id\u003e\n```\n\n## Caffeinate\n\nIf you're looking for a more elaborate client to temporarily disable\n`xidlehook`, take a look at\n[caffeinate](https://github.com/rschmukler/caffeinate) which has timers\nand PID based monitoring.\n\n## Configuring via `systemd`\n\nIf you use a distribution that uses `systemd` for its init system, you may wish\nto use it to ensure that `xidlehook` is always started when you log in. You can\ndo this at the level of an individual user by placing the following service\nfile at `$XDG_CONFIG_HOME/systemd/user/xidlehook.service` (typically\n`$HOME/.config/systemd/user/xidlehook.service`):\n\n``` systemd\n[Unit]\nDescription=Automatic Screen Locker\n\n[Service]\nType=simple\nEnvironment=DISPLAY=:0\nEnvironment=XIDLEHOOK_SOCK=%t/xidlehook.socket\nExecStart=/usr/bin/xidlehook --not-when-audio --not-when-fullscreen --socket $XIDLEHOOK_SOCK --timer 900 '/usr/bin/slock' ''\n\n[Install]\nWantedBy=multi-user.target\n```\n\nThe above service file example locks the screen using the `slock` program after\n15 minutes of inactivity, but you can edit it  the `xidlehook` command to do\nanything you wish. We need to thread the `DISPLAY` environment variable down so\nthat `xidlehook` knows how to open up a connection to the X server.\n\n## Troubleshooting\n\nIf you have `redshift` running, the brightness of your screen will be\nquickly overriden by `redshift`. You can specify the brightness of the\nscreen via `redshift` instead of `xrandr` to fix this issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjd91mzm2%2Fxidlehook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjd91mzm2%2Fxidlehook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjd91mzm2%2Fxidlehook/lists"}