GitHub - jconley88/keyboard_notifier: A simple keyboard monitor that notifies when issues occur. Designed to help diagnose intermittent problems.

Stuck Key Monitor

Logs and sends Linux desktop notifications when keys get stuck or unstuck. Modify stuck_key_notifier.sh to check for other conditions. Runs on startup as a systemd background service. Works with any keyboard accessible via Linux input events.

Should run on most Linux distributions with minimal changes to package dependencies.

AI Disclosure

AI assistance was used to generate and review code in this project. All AI output was fully reviewed, understood, refactored and validated by a human.

tldr install for Debian

Everything can be run exactly as is except where noted as MANUAL💪STEP

# Install dependencies and copy example files
sudo apt install evtest
sudo apt install libnotify-bin
cp stuck_key_notifier.conf.example stuck_key_notifier.conf
# Configure Keyboard
grep "Name=" /proc/bus/input/devices  # MANUAL💪STEP Identify keyboard name
nano stuck_key_notifier.conf          # MANUAL💪STEP replace `KEYBOARD_NAME` variable
# Configure systemd services
sudo sed -e "s|%ACTUAL_USER%|$USER|g" \
         -e "s|%ACTUAL_UID%|$(id -u)|g" \
         -e "s|%INSTALL_DIR%|$(pwd)|g" \
         stuck-key-monitor.service | sudo tee /etc/systemd/system/stuck-key-monitor.service
sudo sed -e "s|%ACTUAL_USER%|$USER|g" \
         -e "s|%ACTUAL_UID%|$(id -u)|g" \
         stuck-key-monitor-failure@.service | sudo tee /etc/systemd/system/stuck-key-monitor-failure@.service
# Configure passwordless sudo so evtest can run in the background
echo "$USER ALL=(root) NOPASSWD: /usr/bin/evtest" # IMPORTANT! use visudo; do not pipe directly to file
sudo visudo -f /etc/sudoers.d/stuck-key-monitor  # MANUAL💪STEP add the echoed output
# Auto-start the service
sudo systemctl daemon-reload
sudo systemctl enable stuck-key-monitor.service
sudo systemctl start stuck-key-monitor.service

How It Works

The service uses evtest to monitor keyboard events from /dev/input/eventX
It tracks key repeat events (value 2 in the event stream)
When a key repeats more than the threshold, it sends a notification
When the key is released (value 0), it sends an "unstuck" notification
systemd ensures the service restarts if it crashes and starts on boot

Requirements

Linux system with systemd
Any keyboard accessible via /dev/input/eventX
evtest package
- sudo apt install evtest debian
notify-send (usually part of libnotify-bin package)
- sudo apt install libnotify-bin debian

Installation

Step 1: Find and Set Your Keyboard

Find your keyboard name:

grep "Name=" /proc/bus/input/device

Instead, you could run sudo evtest to see a list, select and verify.

Copy the configuration file and replace the KEYBOARD_NAME variable name in stuck_key_notifier.conf with your keyboard name.

cp stuck_key_notifier.conf.example stuck_key_notifier.conf

Step 1: Configure Passwordless Sudo for Input Device Permissions

sudo visudo -f /etc/sudoers.d/stuck-key-monitor

Add the following line, replacing $USER with your username:

$USER ALL=(root) NOPASSWD: /usr/bin/evtest

Save and exit. The visudo command will automatically set the correct permissions (0440).

Step 2: Install the Systemd Service

Copy the example service file and customize it with your user and directory information:

cp stuck-key-monitor.service stuck-key-monitor.service
sudo sed -e "s|%ACTUAL_USER%|$USER|g" \
         -e "s|%ACTUAL_UID%|$(id -u)|g" \
         -e "s|%INSTALL_DIR%|$(pwd)|g" \
         stuck-key-monitor.service | sudo tee /etc/systemd/system/stuck-key-monitor.service

Install the failure notification service (sends alerts when the monitor fails):

sudo sed -e "s|%ACTUAL_USER%|$USER|g" \
         -e "s|%ACTUAL_UID%|$(id -u)|g" \
         stuck-key-monitor-failure@.service | sudo tee /etc/systemd/system/stuck-key-monitor-failure@.service

Enable and start the service:

sudo systemctl daemon-reload                     # Rescan /etc/systemd/system directory
sudo systemctl enable stuck-key-monitor.service  # Enable service to start on boot
sudo systemctl start stuck-key-monitor.service   # Start the service

Usage

Once installed, the service runs automatically in the background. No user interaction is needed.

Managing the Service

sudo systemctl status stuck-key-monitor     # Check service status
sudo systemctl stop stuck-key-monitor       # Stop the service
sudo systemctl start stuck-key-monitor      # Start the service
sudo systemctl restart stuck-key-monitor    # Restart the service
sudo systemctl disable stuck-key-monitor    # Disable service from starting on boot
sudo systemctl enable stuck-key-monitor     # Enable service to start on boot

Viewing Logs

sudo journalctl -u stuck-key-monitor -f     # View live logs
sudo journalctl -u stuck-key-monitor        # View all logs
sudo journalctl -u stuck-key-monitor -b     # View logs from the last boot

View Stuck Key History

To view only stuck/unstuck events:

sudo journalctl -u stuck-key-monitor | grep -E 'STUCK:'                       # all
sudo journalctl -u stuck-key-monitor -f | grep -E 'STUCK:'                    # live
sudo journalctl -u stuck-key-monitor -b | grep -E 'STUCK:'                    # since boot
sudo journalctl -u stuck-key-monitor --since "2025-11-29" | grep -E 'STUCK:'  # since date

Configuration

You can modify the behavior by editing stuck_key_notifier.conf:

KEYBOARD_NAME: Change if your keyboard has a different name
THRESHOLD: Number of repeat events before considering a key stuck (default: 100)

After making changes, restart the service:

sudo systemctl restart stuck-key-monitor

Uninstallation

Stop and disable the service:

sudo systemctl stop stuck-key-monitor     # Stop the service
sudo systemctl disable stuck-key-monitor  # Disable service from starting on boot

Remove the service files:

sudo rm /etc/systemd/system/stuck-key-monitor.service
sudo rm /etc/systemd/system/stuck-key-monitor-failure@.service
sudo systemctl daemon-reload
sudo rm /etc/sudoers.d/stuck-key-monitor               # Remove passwordless sudo

Troubleshooting

Service won't start

Check the service status and logs:

sudo systemctl status stuck-key-monitor
sudo journalctl -u stuck-key-monitor -n 50
systemctl reset-failed                      # reset fail counter

Keyboard not detected

Verify your keyboard name:

cat /proc/bus/input/devices | grep -A4 "Name="

If your keyboard has a different name, edit stuck_key_notifier.conf and update the KEYBOARD_NAME variable.

Notifications not appearing

Ensure notify-send is installed and working:

notify-send "Test" "This is a test notification"

If notifications don't appear, you may need to adjust the DBUS_SESSION_BUS_ADDRESS in the service file.

Permission denied errors

Check passwordless sudo:

sudo cat /etc/sudoers.d/stuck-key-monitor

Should contain: your_username ALL=(root) NOPASSWD: /usr/bin/evtest

Security Considerations

Allows sudo evtest without password prompt
Limited to only the evtest command at /usr/bin/evtest
Service runs as your user, only elevates for evtest
evtest only reads input; does not output

License

This project is provided as-is for personal use.