Repository navigation
BallKey 0.1.2
First public release of BallKey, a simple graphical button remapper for any mouse or trackball on Linux.
Pick your device, choose what each button does (Back, Forward, Copy, Paste, Undo, Double-click, custom key combos, Do nothing, …), click Apply. Settings apply at every boot and when the device is reconnected. Works on Wayland and X11, with any brand.
Install
Download the file for your distribution below, then:
| Distribution | File | Install |
|---|---|---|
| Fedora 44+ | ballkey-0.1.2-1.noarch.rpm |
Double-click it, or sudo dnf install ./ballkey-0.1.2-1.noarch.rpm |
| Debian 13+, Ubuntu 26.04+ | ballkey_0.1.2-1_all.deb |
sudo apt install ./ballkey_0.1.2-1_all.deb |
| Arch Linux | ballkey-0.1.2-1-any.pkg.tar.zst |
sudo pacman -U ballkey-0.1.2-1-any.pkg.tar.zst |
Then open BallKey from your app menu. Ubuntu 24.04 isn't supported (no PySide6 package). SHA256SUMS lets you verify the downloads.
Features
- Identify button: press a button to find it in the list
- Custom key combos, recorded by just pressing them
- Lockout protection: if no button does a left click any more, the old settings come back after 15 seconds unless you confirm
- "Start remapping at boot" toggle
- "Forget" to remove a mouse you no longer have
- Changes ask for your password in the normal system prompt (polkit); no terminal needed
- If the service stops or crashes, your mouse goes straight back to normal
About this project
BallKey was vibecoded, and it's my first project: an AI coding assistant (Claude Code) wrote the code while I tested each step on Fedora KDE with a Logitech G403. The Debian, Ubuntu and Arch packages have only been tested in containers, not on real hardware, and no experienced Linux developer has reviewed it yet. Bug reports and code review are very welcome.
License: GPL-3.0-or-later.