DEV Community: Plexescor (Abhijot Singh)

How I built a scriptable Lua extension engine inside my C++ activity tracker (and almost lost my mind to deadlocks)

Plexescor (Abhijot Singh) — Mon, 01 Jun 2026 11:46:27 +0000

Hey!

I've been building HPR, an open source activity tracker and window tracker written in C++23. It watches your active window, builds a history of where your time went, and runs locally with zero accounts and zero telemetry. Think of it as a lightweight ActivityWatch alternative with native Wayland support.

At some point I decided it wasn't enough to just track windows. I wanted people to be able to extend it. So I built a Lua extension engine into it. Here's how that went.

The basic idea

Every .lua file you drop into the extensions folder gets picked up automatically. HPR scans the directory recursively, loads each file into its own sol::state, registers the API, and spins up a dedicated thread for it. Each extension runs completely isolated from everything else. A slow or broken extension can't freeze the UI or corrupt the tracking loop.

The lifecycle is simple. You define three functions:

function init()
    return 500 -- tick interval in ms
end

function onTick(delta)
    -- called every 500ms
end

function onExit()
    -- cleanup
end

init returns how often you want onTick to fire. That's it. Everything else is opt-in through the API.

The API

This is where it gets actually useful. From Lua, an extension can:

Read the currently focused window with HPR.getCurrentWindow_E()
Query and write to the SQLite database directly with HPR.dbQuery_E() and HPR.dbExecute_E()
Subscribe to internal events like WINDOW_CHANGED, MIDNIGHT_ROLLOVER, HISTORY_LOADED_SINGULAR
Register completely custom window detection backends for compositors HPR doesn't natively support
Set UI properties and register callbacks on the Slint UI from Lua
Make HTTP requests, start an HTTP server, parse JSON, read and write CSV files
Stop and resume the window tracking loop entirely

That last one sounds weird but its how the AFK detection works in one of the extensions I built, more on that in a second.

The hardest parts

Honestly the code itself wasnt the worst part. The worst part was deadlocks.

The Lua state is not thread safe. The Slint UI is also not thread safe and must only be touched from its event loop thread. The shared app state has its own mutex. So you have extension threads, the Slint event loop thread, the window poller thread, and the database writer thread all needing to talk to each other without stepping on each other.

The solution was a recursive_mutex per extension that wraps every Lua call, and slint::invoke_from_event_loop for anything that touches the UI. Callbacks registered from Lua that get fired by Slint acquire the Lua mutex before calling back into Lua. It took a while to get right.

The other fun one was cyclic table detection. If a Lua extension pushes a self referential table into a UI property, without protection you get a stack overflow and a segfault. I added a visited set that tracks table pointers during the conversion and bails out with an error message if it sees a cycle instead of recursing forever.

A real example: impersonating ActivityWatch

One of the extensions I wrote is called AW Parasite. It starts an HTTP server on port 5600, which is the default ActivityWatch port. aw-watcher-web and aw-watcher-afk both think they're talking to a real ActivityWatch instance. They send heartbeats, the extension processes them, accumulates URL time and AFK status, writes everything into the HPR SQLite database, and updates the UI through HPR.setUiProperty_E.

When the user goes AFK, the extension calls HPR.stopTracking_E() to pause the main activity window tracker. When they come back it calls HPR.startTracking_E(). The whole thing is about 200 lines of Lua and it works on both Wayland and Windows because its just HTTP.

Hot reload

You can load, unload and reload individual extensions from the UI without restarting HPR. There's also a rescan button that picks up new .lua files you dropped in after launch. Unloading sets running = false on the extension's thread and gives it 450ms to exit cleanly. If it doesnt, the thread gets detached and a warning is logged. Native extensions (.dll / .so) are also supported for cases where Lua isnt enough, though those run outside the sandbox.

HPR is fully free and open source. If any of this sounds interesting the repo is at Github. Would appreciate a star if you find it useful.

How I built native Wayland window tracking across Hyprland, GNOME and KDE in C++23

Plexescor (Abhijot Singh) — Sat, 16 May 2026 11:24:22 +0000

If you've ever tried to get the currently focused window on Wayland, you know it's a mess. There's no unified API. Every compositor does it differently. X11 had _NET_ACTIVE_WINDOW and everyone just used that. Wayland deliberately doesn't have an equivalent for security reasons, which means every tracker, every productivity tool, every anything that needs to know what you're looking at has to implement a different solution per compositor.

I ran into this while building HPR, an activity tracker that watches your active window every 50ms and logs time per app. Here's how I solved it for the three most common Wayland compositors.

Hyprland

Easiest of the three. Hyprland exposes an IPC socket and a CLI tool called hyprctl. One command gives you the active window as JSON:

hyprctl activewindow -j | jq -r '.class'

That's it. No extension, no setup, no workarounds. Just works on first launch. The .class field gives you the application class which is consistent and clean. I call this every 50ms from a background thread and it holds up fine.

GNOME

GNOME on Wayland is the painful one. There's no official API for getting the active window from outside the compositor. The only working solution I found is a shell extension called window-calls-extended which exposes a DBus interface you can query:

gdbus call --session --dest org.gnome.Shell \
  --object-path /org/gnome/Shell/Extensions/WindowsExt \
  --method org.gnome.Shell.Extensions.WindowsExt.FocusClass

This returns the window class wrapped in some dirty output you have to parse. HPR checks on startup whether the extension is active. If it isn't, it tells the user exactly what to do instead of silently returning garbage. Because GNOME can't hot-reload shell extensions you log out and back in once after installing. Every launch after that is automatic.

One thing worth knowing: GNOME shell extensions are sandboxed differently across GNOME versions and some distributions patch the shell in ways that break extension APIs. If you're supporting GNOME you need to test across versions.

KDE Plasma

KDE was the one I expected to be easy and wasn't. KDE exposes KWin scripting via qdbus6 which lets you inject JavaScript into the compositor and read the output. The active window class comes from workspace.activeWindow.resourceClass.

The problem is KWin doesn't give you a clean return value. The script runs, prints output to the system journal with a js: prefix, and you have to scrape it back out:

echo 'print(workspace.activeWindow.resourceClass);' > /tmp/kwin_active.js
S=$(qdbus6 org.kde.KWin /Scripting org.kde.kwin.Scripting.loadScript /tmp/kwin_active.js kwin_tmp_$$)
T=$(date '+%Y-%m-%d %H:%M:%S')
qdbus6 org.kde.KWin /Scripting/Script$S org.kde.kwin.Script.run > /dev/null 2>&1
sleep 0.1
journalctl --since "$T" -o cat | grep '^js:' | tail -n 1 | sed 's/^js: //'

Yes this is a hack. It forks a shell, injects JS, scrapes the journal, and cleans up after itself every 50ms. Somehow it lands at around 1% CPU. I tested every other approach I could find. None of them worked reliably across KDE configurations. This one does.

One side effect: during the JS injection, KWin's own runtime briefly appears as the active window. If you don't filter it out, strings like js::kwin_tmp_1234 silently accumulate time in your logs. HPR filters anything containing js:: before it ever touches the data.

The normalization layer

Each backend returns a raw string. Raw strings from OS window APIs are inconsistent and noisy. HPR runs every return value through a shared normalization function before doing anything with it. This filters out compositor artifacts, plasma shell entries, null strings, and KWin JS runtime noise. New backends inherit this filtering automatically.

Platform detection

HPR reads $XDG_CURRENT_DESKTOP and matches substrings. Simple, works for 99% of setups. Non-standard session variables or nested compositors can confuse it but that's an edge case worth documenting rather than engineering around.

The project

HPR is open source, C++23, Slint UI, SQLite3 bundled. If you're on Wayland and want an activity tracker that actually works without a Python runtime or an embedded web server, give it a try.

GitHub: github.com/plexescor/HPR

If you've solved Wayland window detection in a cleaner way especially on KDE, I'd genuinely like to know.