Skip to content

BallKey 0.1.2

Choose a tag to compare

@gino8807 gino8807 released this 14 Oct 21:13
· 23 commits to main since this release

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.