A lightweight Linux tray app and per-key editor for laptop keyboard lighting, with a focus on TongFang-based laptops using ITE controllers.

LLM note: For a concise, LLM-optimized summary of supported hardware, backends, and repo-discovery hints, see AGENTS.md.

Uses a priority-based backend system plus a backend-stability policy to select the most appropriate eligible backend for detected hardware.

1. Kernel Driver (Preferred): Uses safe, native Linux kernel interfaces (/sys/class/leds).

   • Clevo / Tuxedo: Full RGB support via tuxedo-drivers or clevo-xsm-wmi.
   • System76: Full RGB support via standard ACPI drivers.
   • Broad: Brightness control on many laptops that expose a keyboard backlight LED via /sys/class/leds.

2. USB / HID Direct: Uses an implemented userspace backend such as ite8291r3 or ite8910.

   • TongFang: Supports per-key RGB on devices without kernel drivers (XMG, Wootbook, Eluktronics, older Tuxedo models) if the hardware supports it.

3. ASUS Aura: Uses the asusctl-aura backend when the ASUS userspace stack is available.

   • ASUS: Best for laptops that already expose lighting control through asusctl / rog-control-center.

Experimental backends also carry an evidence tag in diagnostics so maintainers can distinguish speculative implementations from research-backed ones based on public protocol notes or reverse-engineering work.

Current backend plan:

• sysfs-leds, ite8291r3, ite8910, and asusctl-aura: validated
• ite8297: experimental + reverse_engineered
  • 0x048d:0x8297 — 64-byte hidraw feature-report path, uniform color only
• ite8258: experimental + reverse_engineered
  • 0x048d:0xc195 — Lenovo Legion 5 / Pro 5 Gen 10 24-zone ITE 8258 hidraw keyboard path (4×6 logical zone matrix, static color, brightness, and firmware effects)
• ite8295-zones: experimental + reverse_engineered
  • 0x048d:0xc963 — Lenovo 4-zone ITE 8295 hidraw keyboard path used by IdeaPad Gaming 3-class systems, with static color, 4-zone updates, brightness, and the confirmed default firmware effects (breathing, wave, spectrum_cycle)
  • 0x048d:0xc966 — companion ITE 8176 endpoint reported on the same laptops; still treated as a separate unsupported protocol family until direct RGB evidence exists
• sysfs-mouse: experimental + speculative
  • Auxiliary-only route for color-capable external mouse LEDs exposed through /sys/class/leds; surfaced through discovery and tray secondary-device contexts, but intentionally kept out of primary keyboard auto-selection
• ite8233: experimental + reverse_engineered
  • 0x048d:0x7001 — single-zone lightbar, static color / brightness / off
  • 0x048d:0x7000 — lightbar + hidden backend-level effects: breathing, wave, bounce/clash, catchup/catch_up
  • 0x048d:0x6010 — lightbar + hidden backend-level effects: breathing, flash (with optional direction), vendor DMI color-scaling quirk for specific SKUs
• ite8291: experimental + reverse_engineered
  • 0x048d:0x6004, 0x6008, 0x600b — full per-key 6×21 row protocol
  • 0x048d:0xce00 (bcdDevice ≠ 0x0002) — per-key path; bcdDevice 0x0002 is routed to ite8291-zones instead
• ite8291-zones: experimental + reverse_engineered
  • 0x048d:0xce00 bcdDevice 0x0002 — 4-zone uniform-color firmware split

When a compatible auxiliary device is present, the tray exposes a Software Targets submenu so looped software effects can stay on the keyboard or mirror their uniformized output to all compatible secondary devices.

Note: direct ITE backends only enable known-good, whitelisted IDs. Experimental and dormant paths are additionally policy-gated, so detection alone does not guarantee automatic selection.

The installer (install.sh) can optionally help you install the necessary kernel modules for Clevo/Tuxedo laptops, and installs the matching KeyRGB udev rules for supported USB / hidraw access paths.

• Beta: versioning follows 0.x.y. Currently stable but has limited backend support.
• Installer support is validated on Fedora/Nobara and Arch/CachyOS; other distro families are supported on a staged, best-effort basis.
• Support depends entirely on your specific keyboard controller and firmware. See Troubleshooting and Hardware support and contributing below.

Tray Menu (Effects)	Power Management
Per-Key Editor	Settings
Tray Menu (Brightness)	RAM / CPU Usage

More screenshots

Tray Menu (Software Effects)	Tray Menu (Keyboard / Profiles)
Uniform Color UI	Per-Key Calibrator
Keymap Calibration	Reactive Typing

For most users, use the AppImage installer. Only use a source checkout if you want to modify KeyRGB locally.

The installer downloads the AppImage, stores it as ~/.local/bin/keyrgb.AppImage, installs the ~/.local/bin/keyrgb launcher, and refreshes desktop integration. The AppImage bundles the runtime dependencies, so normal installs do not need Python/Tk GUI packages from your distro.

Standard install:

curl -fsSL https://raw.githubusercontent.com/Rainexn0b/keyRGB/main/install.sh -o install.sh && bash install.sh

AppImage install without system package changes:

curl -fsSL https://raw.githubusercontent.com/Rainexn0b/keyRGB/main/install.sh -o install.sh && bash install.sh --no-system-deps

Update an existing AppImage install:

curl -fsSL https://raw.githubusercontent.com/Rainexn0b/keyRGB/main/install.sh -o install.sh && bash install.sh --update-appimage

Notes:

• Some integration steps may prompt for sudo when installing udev or polkit rules.
• --update-appimage also refreshes desktop integration and removes stale legacy KeyRGB PNG icons from older installs when the current SVG icon is available.
• --no-system-deps only skips system package changes; it still downloads and installs the AppImage.
• On Arch/CachyOS, install fuse2 for native AppImage/FUSE launching: sudo pacman -S --needed fuse2. KeyRGB also installs a launcher wrapper that falls back to --appimage-extract-and-run when libfuse.so.2 is unavailable.
• On Debian/Ubuntu/Linux Mint, the AppImage path is usually enough for a first install. Optional kernel-driver installs are best-effort and may require TUXEDO package sources; KeyRGB does not add third-party apt repos automatically.
• To pin a release tag instead of main, use both --ref <tag> and --version <tag>.

Interactive uninstall:

curl -fsSL https://raw.githubusercontent.com/Rainexn0b/keyRGB/main/uninstall.sh -o uninstall.sh && bash uninstall.sh

Non-interactive uninstall of the AppImage install and desktop entries:

curl -fsSL https://raw.githubusercontent.com/Rainexn0b/keyRGB/main/uninstall.sh -o uninstall.sh && bash uninstall.sh --yes --remove-appimage

git clone https://github.com/Rainexn0b/keyRGB.git
cd keyRGB
./install.sh --dev

./uninstall.sh
./uninstall.sh --yes --remove-appimage

curl -fsSL https://raw.githubusercontent.com/Rainexn0b/keyRGB/main/install.sh -o install.sh && \
	KEYRGB_INSTALL_KERNEL_DRIVERS=y \
	KEYRGB_INSTALL_INPUT_UDEV=y \
	KEYRGB_INSTALL_TUXEDO=y \
	KEYRGB_INSTALL_TCC_APP=y \
	bash install.sh

If you installed via the installer, run KeyRGB from your app menu or start it from a terminal:

These are the effect names stored in ~/.config/keyrgb/config.json under the effect key.

• Hardware (firmware) effects: backend-specific. Common legacy values include rainbow, breathing, wave, ripple, marquee, raindrop, aurora, fireworks.
• Software effects: rainbow_wave, rainbow_swirl, spectrum_cycle, color_cycle, chase, twinkle, strobe
• Reactive typing: reactive_fade, reactive_ripple
• Per-key static map: perkey

When a hardware effect name collides with a software effect name, KeyRGB stores the hardware selection with an hw: prefix to preserve the user's choice. Example: hardware spectrum_cycle is stored as hw:spectrum_cycle.

Access Settings via the tray menu to configure:

• Power Management: toggle LEDs on Suspend/Resume or Lid Close/Open.
• Screen Dim Sync: optionally sync keyboard brightness with desktop-driven screen dimming/brightness changes (e.g. KDE brightness slider).
• Autostart: enable “Start KeyRGB on login”.
• Backend policy: opt in to experimental backends. Currently ite8297, ite8233, ite8258, ite8291, ite8291-zones, and ite8295-zones are experimental; the UI labels experimental paths as speculative or research-backed.

Profiles are stored in:

~/.config/keyrgb/profiles/

Each profile contains the keymap (calibration), global overlay tweaks, and per-key color data. Manage these via the Per-Key Editor.

Most supported controllers use a fixed LED matrix (e.g., 6×21). To map this to your physical layout:

1. Open keyrgb-perkey.
2. Click Run Keymap Calibrator.
3. Click the corresponding key on-screen as each physical LED lights up.
4. Save the keymap.

If KeyRGB detects your device but behaves oddly, or if you have a new laptop model (TongFang/Clevo/etc.), please help us support it.

1. Run diagnostics:

keyrgb-diagnostics

2. Open an issue:

• https://github.com/Rainexn0b/keyRGB/issues/new/choose

Select Hardware support / diagnostics and paste the JSON output from step 1.

3. Include details:

• Laptop model (e.g., XMG Core 15, Tuxedo InfinityBook)
• USB ID (run lsusb | grep -i "048d:")
• Description of what works vs. what fails

keyrgb-diagnostics attempts to sanitize output, but please review the JSON before posting to ensure no personal paths/names are included.

GPL-2.0-or-later.