Installation

Get running in seconds.

AUR package, Windows installer, universal install script, or build from source. Pick your path.

Quick Install

Choose your platform.

HPR ships as a single compiled binary. No runtime dependencies. No package managers pulling in half the internet.

AUR Package

HPR is available on the AUR. Install with your preferred AUR helper.

Terminal 
yay -S hpr

Or with paru: 

paru -S hpr
AUR

The AUR package handles everything — building, dependencies, and placing config files. The simplest path for Arch users.

System-Wide Desktop Entry

When installed via the AUR, the system-wide desktop entry at /usr/share/applications/hpr.desktop is managed by the package. HPR detects this automatically and skips the per-user entry entirely.

After Install

Launch HPR from your application menu or terminal. Config files are placed automatically. Start tracking immediately.

Universal Install Script

Install or update HPR on Linux automatically with a single command:

Terminal 
curl -fsSL https://raw.githubusercontent.com/plexescor/HPR/main/install.sh | bash
What does the installation script do?
  • Dependency Verification: Checks for required CLI tools (curl, tar, xz, dbus-send, git).
  • Version Check: Queries the GitHub API to fetch and download the latest release asset package (HPRv{VERSION}-Linux.tar.xz).
  • System Binary Installation: Prompts you for your preferred system-wide installation path (defaults to /usr/local/bin/HPR) and installs the binary (uses sudo for binary copy only).
  • Configuration Setup: Creates the config directories (~/.config/HPR and ~/.local/share/HPR) and writes default CSV configurations if they don't exist.
  • User Customization Protection: Detects if you have modified your CSV configuration files or the custom ui/ folder, and preserves your changes. Only untouched default configurations are updated.
  • GNOME Extension Installation: Detects if you are running the GNOME Desktop and prompts you to install the custom window-tracking extension (lol-another-window-extension) if it's missing.
  • Launcher Creation: Configures high-resolution app icon paths, creates a desktop launcher entry (~/.local/share/applications/hpr.desktop), and refreshes application menu databases.

File Locations

Config:
~/.config/HPR/
  ├── config.csv
  ├── aliases.csv
  ├── tabAliases.csv
  ├── projectAliases.csv
  ├── extensions/
  │   └── your-extension.lua
  └── ui/
      └── app-window.slint

Data:
~/.local/share/HPR/HPR_DB/
  └── MM-YY/
      └── DD-MM-YY.db

Platform Requirements

Hyprland: No extras (native JSON parsing)
niri: No extras (uses niri msg)
GNOME: gdbus + extension
KDE 6+: No extras (uses KWin scripting)
Cinnamon: No extras

Windows Installer

Download and run the setup executable. Inno Setup handles everything automatically.

What the installer does

1 Places aliases.csv, tabAliases.csv, projectAliases.csv, config.csv, and ui/ folder into your config directory
2 Prompts before overwriting any existing customized files
3 Drops latest default UI into ui-REFERENCEONLY/ for diffing
Download Latest Release

File Locations

Config:
%APPDATA%\HPR\HPR_Config\
  ├── config.csv
  ├── aliases.csv
  ├── tabAliases.csv
  ├── projectAliases.csv
  ├── extensions\
  │   └── your-extension.lua
  └── ui\
      └── app-window.slint

Data:
%APPDATA%\HPR\HPR_DB\
  └── MM-YY\
      └── DD-MM-YY.db
Tray Mode

Built without a console window on Windows. Sits in your system tray and stays out of your way. No terminal flash on launch.

Build From Source

Clone, install Slint, build. HPR bundles and uses slightly patched versions of sol2, lua, and sqlite3 to ensure clean, warning-free builds on modern compilers.

Clone 
git clone https://github.com/plexescor/HPR
cd HPR
Install Slint (Linux) 
# System-wide (requires sudo)
sudo ./installDependencies.sh

# User-local (no sudo needed)
./installDependencies.sh
Install Slint (Windows) 
# Pulls Slint 1.16.1, slint-lsp, slint-viewer
installDependencies.bat
Build 
mkdir build && cd build

# If install script ran without sudo:
cmake .. -DCMAKE_PREFIX_PATH="$HOME/.local"

# If install script ran with sudo:
cmake ..

cmake --build . --parallel 8

Requirements

req CMake 3.21+
req GCC 13+, Clang 16+, or MSVC 2022+
req C++23 support
auto Slint 1.16.1 (install script handles)
bundled Patched sol2, lua, & sqlite3 in external/

Linux-Only Dependencies

Runtime: gdbus for GNOME and Cinnamon · KWin scripting for KDE Plasma 6+ (auto-detected) · hyprctl for Hyprland · niri for niri

Build-time and Extensions (Linux): libdbus-1 (needed to compile the tray) and libcurl development library (e.g. libcurl4-openssl-dev on Debian/Ubuntu, libcurl-devel on Fedora/RHEL) for extension networking support.

Build-time (Windows): The native notification backend uses the bundled WinToast library which compiles completely out-of-the-box (no external Windows dependencies required).

Patched Dependencies

HPR uses slightly patched versions of sol2, lua, and sqlite3 to mitigate compile errors and warnings. Swapping these for unpatched or system-installed libraries may cause compile errors, strict C++23 const-correctness warnings, or linker warnings (e.g., regarding tmpnam). Using the bundled versions ensures a warning-free build.

Build Output

CMake copies aliases.csv, tabAliases.csv, projectAliases.csv, config.csv, ui/, assets/, and install scripts next to the output binary automatically. A fresh build is immediately runnable from the build directory.

After Installing

First run checklist.

HPR works out of the box. These are optional enhancements.

1

Check Platform

HPR auto-detects your desktop via $XDG_CURRENT_DESKTOP. GNOME users need to install the extension first. If it's missing, HPR doesn't crash silently — it sets its own "active window" display to the exact command you need to run, printing it directly in the UI header bar so the fix is impossible to miss:

# What HPR shows in the top bar if extension is missing:
RUN THE "installWindowCallsExtension.sh" SCRIPT
NEXT TO THE HPR BINARY AND THEN RESTART PC
2

Customize Aliases

Edit aliases.csv to add your own application name mappings. Hot-reloads — no restart needed. Format: raw,Display Name.

3

Try Interpreted Mode

Set use-interpreter,true in config.csv to load the UI from disk. Edit app-window.slint to customize HPR's entire interface.

4

Set App Limits or Goals

Open the sidebar and click the Goals icon to set per-app daily time limits or usage goals. No restart required. Click any app row to expand its settings inline.

Contributing

Read the codebase in one sitting.

Go in this order and the entire architecture makes sense.

Reading Order 
main.cpp              →  startup, config loading, thread orchestration
appState.hpp          →  the shared data model, the center of everything
getCurrentWindow.cpp  →  platform-specific window polling per backend
databaseManager.cpp   →  persistence, lock file, midnight rollover, historical load
limitsManager.cpp     →  per-app usage limit and goal monitoring, notification dispatch
extensionManager.cpp  →  Lua VM lifecycle, sol2 bindings, hot-reload, RAII subscription tracking
uiModelManager.cpp    →  how C++ state becomes Slint models in both UI modes
One Rule

Anything that touches shared state goes through AppState::stateMutex. Lock, copy, release, work on the copy. Every existing access follows this pattern.

View Source on GitHub ☕ Support Development