Troubleshooting

Overlay doesn’t appear

Check you’re on X11:

echo $XDG_SESSION_TYPE  # should say "x11"

Verify AT-SPI is running:

systemctl --user status at-spi-dbus-bus.service

Run from a terminal with -v to see logs:

./qhints-rs -v

The keyboard grab can fail with some window managers. Click on the overlay to dismiss it (acts as safety net). Use -vv for trace-level logs.

Some applications (VS Code, browsers) don’t expose accessibility info. Try adding imageproc to your backends:

{ "backends": ["imageproc"] }

If that works but AT-SPI doesn’t, your app may need --force-renderer-accessibility or similar flags.

The lock file at /tmp/qhints.lock prevents concurrent instances. If qhints crashed, remove it:

rm /tmp/qhints.lock

Use overlay_x_offset and overlay_y_offset to shift. With i3 + multi-monitor, the overlay may need adjustments:

{
  "overlay_x_offset": 1920,
  "overlay_y_offset": 0
}

Config path: ~/.config/qhints/config.json. Create it if missing — all fields are optional.

Adjust hint_font_size and hint_height:

{
  "hints": {
    "hint_font_size": 12,
    "hint_height": 18
  }
}

Decrease nudge step values for finer control:

{
  "hints": {
    "text_select_nudge_step_x": 0.01,
    "text_select_nudge_step_y": 0.01
  }
}

Ensure system deps are installed:

sudo apt install xdotool libgtk-3-dev librsvg2-dev clang libclang-dev

For the OCR feature (enabled by default), you need clang + libclang-dev. Disable OCR if you don’t need it:

cargo build --release --no-default-features

The overlay uses software rendering via Cairo. On slower systems, increase marker_pulse_interval_ms to reduce redraw frequency:

{
  "hints": {
    "marker_pulse_interval_ms": 50
  }
}

qhints-rs depends on:

Wayland support would require:

Contributions welcome.