Runeshape Native

A Hyprland-native Path of Exile 2 price overlay for the Runeshape panel and Ange's Currency Exchange. It uses Hyprland for window detection, grim for capture, Tesseract and RapidOCR for text recognition, POE2Scout for estimated market values, and Quickshell for the click-through overlay.

Launching

On NixOS, only git and Nix are required. The launcher creates a temporary Nix runtime containing the desktop and OCR dependencies; it does not require a system rebuild or direnv.

On CachyOS / Arch, install the system dependencies once:

Install the system dependencies:

sudo pacman -S --needed git uv grim slurp tesseract tesseract-data-eng quickshell gtk3 python-gobject libayatana-appindicator

Clone the repository and run its launcher:

git clone ssh://git@git.ancofazi.de:2222/Andreas/runeshape-native.git
cd runeshape-native
./run.sh

The repository is currently private, so the user's SSH key must have access in Forgejo before cloning. Alternatively, send them a release archive and run the run.sh launcher from the extracted directory.

run.sh creates .venv/ and .data/ inside the repository on first launch, then opens the tray application. It does not install the project, create an autostart entry, register a service, add commands to PATH, or write persistent application data outside the repository. The pacman command above only installs the required system programs and libraries.

After the first setup, launching the complete application is always:

./run.sh

First Setup

1. Start Path of Exile 2 and keep its window open.
2. Run ./run.sh.
3. Open the tray menu and select Run setup.

Choose the league matching the character. The capture area is normally derived from the PoE 2 Hyprland window. If the game cannot be found, slurp opens for a manual region selection.

Open the Runeshape panel or talk to Ange and open Currency Exchange on the I Have tab. The tray menu provides Start overlay, Stop overlay, Restart overlay, Run setup, Refresh prices, and Quit. The watcher only scans while Path of Exile 2 is focused. It does not place orders or interact with the game. Closing the tray stops the watcher and overlay.

The desktop panel must support StatusNotifier/AppIndicator tray items. Waybar's tray module and most full desktop panels provide this.

Files and Logs

./run.sh
tail -f .data/watch.log

All generated files remain local:

.venv/                 Python 3.11 environment and dependencies
.data/config.json      User configuration
.data/prices.json      POE2Scout cache
.data/watch.log        Watcher output
.data/tray.lock        Single-instance lock
.data/runtime/         Quickshell overlay state
.data/uv-cache/        uv package cache
.data/python/          uv-managed Python runtime, when required

Both .venv/ and .data/ are ignored by Git. Remove them to return the checkout to its original state.

Updating

From the cloned repository:

git pull --ff-only
./run.sh

Quit the running tray before updating. run.sh updates the local environment from uv.lock before starting.

Configuration

Portable configuration is stored in:

.data/config.json

Important settings:

Setting	Default	Purpose
league	selected during setup	POE2Scout league short name
auto_detect_area	true	Derive capture areas from the PoE window
display_currency	"exalt"	Runeshape value display below Divine value
min_exchange_exalted	1.0	Minimum estimated stack value for WORTH
interval	0.75	Watch-loop interval in seconds

Currency Exchange values are estimates from POE2Scout, not the live in-game order book:

• WORTH: estimated value is above the configured threshold;
• CHECK: quantity or market data needs manual verification;
• KEEP: estimated value is below the threshold or no quote exists.

Troubleshooting

Verify required commands:

for command in hyprctl grim slurp tesseract qs; do command -v "$command"; done

Verify English OCR data:

tesseract --list-langs | grep '^eng$'

If setup selected the wrong league, select Run setup from the tray again. If overlays are misplaced after changing game resolution or UI scaling, use Restart overlay from the tray with the game open so automatic geometry detection starts fresh.

Development

uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python -e .
.venv/bin/python -m unittest discover -s tests
.venv/bin/runeshape-native watch

The project requires Python 3.11 or newer. The launcher uses Python 3.11 for its local OCR environment to ensure compatible ONNX Runtime wheels across Arch-based systems.