HellRazr

The definitive Razer Naga companion for Arch Linux and Hyprland.

Native USB control — no OpenRazer daemon needed.

What it does

HellRazr maps the 12-button side panel on any Razer Naga mouse to Hyprland workspace management, with optional RGB lighting, DPI configuration, profiles, macros, and a GTK4 desktop GUI.

Workspace Bindings

Action	Effect
Naga button 1-10	Switch to workspace 1-10
SHIFT + button	Move focused window to workspace (follow)
CTRL + button	Move focused window to workspace (stay)

How it works

1. A udev hwdb rule remaps the Naga's number key scancodes (1-0) to F13-F22 at the kernel level. Only the Naga is affected — your keyboard is untouched.
2. Hyprland keybinds map F13-F22 to workspace actions. Since F13-F22 don't exist on standard keyboards, only the Naga triggers them.
3. Native USB HID communicates directly with the mouse for RGB, DPI, polling, and battery — no kernel driver or daemon required.

Features

• Workspace switching — kernel-level button remap, zero dependencies
• Native USB driver — direct HID communication, no OpenRazer needed
• RGB lighting — static, breathing, spectrum, wave, reactive effects
• DPI configuration — per-axis, DPI stages (100-30000)
• Polling rate — 125, 250, 500, 1000 Hz
• Battery monitoring — level, charging, idle time, low threshold (wireless models)
• Profile system — named presets with all settings, TOML-based
• Per-app profiles — auto-switch based on active Hyprland window
• Macro recording/playback — evdev recording, ydotool playback
• GTK4 desktop GUI — full-featured graphical interface with Adwaita
• Terminal UI — Textual-based interactive TUI
• Waybar integration — JSON module for DPI, battery, profile display
• 17 Naga models — from the original Naga to the V2 HyperSpeed

Installation

Interactive installer (recommended)

./setup.sh

Presents a menu with three options:

1. Workspace switching only — no Python, just hwdb + Hyprland keybinds
2. Full application — CLI + RGB + DPI + profiles + macros
3. Full app + Desktop GUI — everything + GTK4 launcher entry

Non-interactive flags:

./setup.sh --minimal    # Option 1 (no menu)
./setup.sh --full       # Option 3 (no menu)
./setup.sh --check      # Verify all components
./setup.sh --uninstall  # Remove everything

From source (pip)

pip install .            # Core CLI
pip install .[gui]       # With GTK4 GUI
pip install .[gui,macros,tui]  # Everything

Arch Linux (PKGBUILD)

makepkg -si

Usage

CLI

hellrazr install              # Install hwdb + Hyprland keybinds
hellrazr check                # Verify setup
hellrazr uninstall            # Remove configuration

hellrazr devices              # List connected Naga mice
hellrazr supported            # List all 17 supported models
hellrazr info                 # Full device info

hellrazr rgb static ff0000    # Set static red
hellrazr rgb breathing ff0000 00ff00  # Dual-color breathing
hellrazr rgb spectrum         # Spectrum cycling
hellrazr rgb wave left        # Wave effect
hellrazr rgb off              # Turn off lighting

hellrazr dpi get              # Show current DPI
hellrazr dpi set 1600         # Set DPI (both axes)
hellrazr dpi set 1600 800     # Set per-axis DPI

hellrazr profile list         # List profiles
hellrazr profile activate gaming  # Apply a profile
hellrazr profile create myprofile # Create new profile

hellrazr daemon enable        # Enable systemd autostart
hellrazr daemon status        # Check daemon status

GUI

hellrazr-gui    # Launch desktop application

Or find HellRazr in your app launcher (after setup.sh mode 3 or PKGBUILD install).

TUI

hellrazr-tui    # Launch terminal interface

Requirements

• Arch-based Linux distribution
• Hyprland window manager
• Python >= 3.11 (for full app; workspace switching works without Python)

Optional system packages

Package	Required for
gtk4, libadwaita, python-gobject	Desktop GUI (hellrazr-gui)
python-textual	Terminal UI (hellrazr-tui)
python-evdev	Macro recording
ydotool	Macro playback (Wayland)

OpenRazer is not required — HellRazr has its own native USB driver. If OpenRazer is installed, it serves as a fallback.

Supported Devices

PID	Model
0015	Razer Naga (Original)
002e	Razer Naga 2012
0036	Razer Naga Hex (Red)
003e	Razer Naga Epic Chroma (Wired)
003f	Razer Naga Epic Chroma (Wireless)
0040	Razer Naga 2014
0041	Razer Naga Hex
0053	Razer Naga Chroma
0067	Razer Naga Trinity
008d	Razer Naga Left-Handed Edition
008f	Razer Naga Pro (Wired)
0090	Razer Naga Pro (Wireless)
0093	Razer Naga Classic Edition
0096	Razer Naga X
00a7	Razer Naga V2 Pro (Wired)
00a8	Razer Naga V2 Pro (Wireless)
00b4	Razer Naga V2 HyperSpeed

Architecture

hellrazr
├── usb/            # Native USB HID driver (direct device control)
├── core/           # Device detection, hwdb rules, udev
├── openrazer/      # OpenRazer bridge (optional fallback)
├── gui/            # GTK4 + libadwaita desktop application
├── tui/            # Textual terminal UI
├── hyprland/       # IPC, keybinds, config injection
├── profiles/       # Profile CRUD, auto-switching
├── macros/         # Recording, playback, binding engine
├── integrations/   # Waybar JSON module
├── cli.py          # Click-based CLI (all commands)
└── config.py       # XDG-compliant TOML configuration

The native USB driver communicates directly with the mouse via HID control transfers — the same 90-byte protocol that OpenRazer's kernel driver uses, but implemented in pure Python with hidapi. No kernel module, no daemon, no DBus.

License

GPL-3.0-only