# Keyboard Listener (kl)

## Description

`kl` is a lightweight, command-line global keystroke monitoring and echoing tool for GNU/Linux systems.

This tool is compiled directly to native binary with zero runtime dependencies. No Node.js, No Electron, No Python, **written in pure C**.

## Install

You can install it with the AUR.

```bash
paru -S kl
```

or build from source

```
git clone https://github.com/yingyu5658/keyboard-listener.git
cd keyboard-listener
sudo make install
```

## Usage

`kl` is desiged to interact with low-level kernel input events directly via `/dev/input/eventx`. We need to find the keyboard event file.

```bash
λ ~/ ls /dev/input/by-path
pci-0000:00:14.0-usb-0:1:1.0-event-mouse  pci-0000:00:14.0-usb-0:9:1.1-event
pci-0000:00:14.0-usb-0:1:1.0-mouse        pci-0000:00:14.0-usb-0:9:1.1-event-kbd
pci-0000:00:14.0-usb-0:9:1.0-event-kbd    platform-pcspkr-event-spkr
```

Find a file which includes words like "keyboard", "kbd" and so on. For the first time of running `kl`, it will create a config file: `~/.klrc`, here is an example: 


```
# kl config file (v0.0.1)
#
# Please see your README for details.
#
# This file was auto-generated because it was missing.

device = /dev/input/by-path/pci-0000:00:14.0-usb-0:9:1.0-event-kbd

time = true
```

then run `sudo kl`:

```
λ ~/ sudo kl
Device: /dev/input/by-path/pci-0000:00:14.0-usb-0:9:1.0-event-kbd
2026-05-17 21:54:22.210831: P
2026-05-17 21:54:22.330827: R
2026-05-17 21:54:22.602797: O
2026-05-17 21:54:22.866822: G
2026-05-17 21:54:22.954814: R
2026-05-17 21:54:23.026817: A
2026-05-17 21:54:23.146814: M
2026-05-17 21:54:23.378821: M
2026-05-17 21:54:23.546794: I
2026-05-17 21:54:23.626831: N
2026-05-17 21:54:23.802818: G
2026-05-17 21:54:23.898808: 
2026-05-17 21:54:24.082826: I
2026-05-17 21:54:24.554789: N
2026-05-17 21:54:24.746833: 
2026-05-17 21:54:24.890809: P
2026-05-17 21:54:25.066811: U
2026-05-17 21:54:25.170807: R
2026-05-17 21:54:25.210811: E
2026-05-17 21:54:25.570792: 
2026-05-17 21:54:25.762816: C
```

You can also disable time echo with `time = false`:

```
λ ~/dev/key-catcher/ main* sudo kl    
Device: /dev/input/by-path/pci-0000:00:14.0-usb-0:9:1.0-event-kbd
L
E
S
S

I
S

M
O
R
E
.
```

---

## SECURITY & PERMISSIONS

Due to the security model of modern Linux distributions (especially on Wayland/systemd-logind), direct access to these device nodes from an unprivileged GUI session is blocked to prevent unauthorized key logging.

If it can't work properly, add your user to the `input` group, and reboot your computer.

```bash
sudo usermod -aG input $USER
```

## Report Bug

Email: `im@verdant.ee`