Window Manager and Desktop Environment Setup Guide

Note

As of hints v.0.0.7, these steps are no longer relevant as the setup script will automate this process (with the exception of setting up keybindings). This information is kept here for manual debugging purposes. Read the Setup guide in the project's README before following this guide.

On Linux we have a lot of different window managers and desktop environments, which is great for choice, but can make setting up hints a little difficult to newcomers. The goal of this page is to give you a guide that is specific to your window manager or desktop environment so that you can get setup as quickly as possible. Start with the README for install instructions and then look at X11 (General) or Wayland (General) followed by the guide specific to your window system if one is available below.

X11 (General)

Setup hintsd

Hints comes with a daemon used to perform mouse actions. Without starting the daemon, you won't be able to perform mouse actions. The daemon creates custom uniput devices so your user will need to have the proper permissions to read and write to those devices. The guide below shows you how to do that.

Add your user to the input group:

sudo usermod -a -G input $USER

Create a udev rule to allow users in the input group to read and write uinput devices by creating a file: /etc/udev/rules.d/80-hints.rules with the following:

KERNEL=="uinput", GROUP="input", MODE:="0660"

Then reboot.

Enable and Start hintsd

Enable the hitsd service so that it starts on boot and start the service for the current session:

systemctl --user daemon-reload
systemctl --user enable hintsd
systemctl --user start hintsd

You can check the status of the service with:

systemctl --user status hintsd

In the output, you should see a line like the following which indicates the service is running:

Active: active (running) since Thu 2025-01-16 19:55:47 PST; 2s ago

if you don't want to use the service, you can also run hintsd directly:

hintsd

You will not see any output when hintsd starts, it's just a long running program.

Setup a keyboard shortcuts

Hints are only drawn for the currently focused window. So make using hints easy, you need to bind a keyboard shortcut so that hints are drawn on demand for the currently focused window. You can also bind other functionality like scrolling. This is window system specific.

Wayland (General)

Setup hintsd

See this

Enable and Start hintsd

See this

Setup keyboard shortcuts

Hints are only drawn for the currently focused window. So make using hints easy, you need to bind a keyboard shortcut so that hints are drawn on demand for the currently focused window. You can also bind other functionality like scrolling. This is window system specific.

i3

Setup hintsd

See this

Setup keyboard shortcuts

Add the following to your i3 config to bind mod+i to draw hints and mod+y to start hints in scroll mode. These shortcuts can of course be changed to your liking.

bindsym $mod+i exec hints
bindsym $mod+y exec hints --mode scroll

Depending on how your PATH is setup, you might need to provide the full path to the hints binary. If the above does not work for you try this:

Get the full path to hints:

whereis hints

Then use that path to setup your keybind:

bindsym $mod+i exec /full/path/to/hints
bindsym $mod+y exec /full/path/to/hints --mode scroll

Sway

Setup hintsd

See this

Setup keyboard shortcuts

Follow the i3 guide but add the changes to your sway config

Configuring Gaps

The sway implementation uses swaymsg to get window positions. Unfortunately, the output of swaymsg does not take gaps into account when returning the position of windows. So if you have gaps, you will notice that hints are offset.

To correct this offset you can use the overlay_x_offset and overlay_y_offset options to offset the x and y positions of the overlay window (the window that displays hints over other windows). To use these values, add them to your hints config:

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

You might not need to use both x and y offsets, but both options exist for flexibility.

Hyprland

Setup hintsd

See this

Setup keyboard shortcuts

Add the following to your hyprland config.

bind = SUPER, I, exec, hints
bind = SUPER, Y, exec, hints --mode scroll

Gnome (Wayland)

Setup hintsd

See this

Setup the hints plugin

Because Gnome does not support the layer-shell protocol that hints uses to display the overlay window in other Wayland compositors, a hints plugin has been developed (thanks to @realh).

• copy hints@realh.co.uk to ~/.local/share/gnome-shell/extensions/.
• logout and back in / restart your gnome shell session.
• enable the plugin with gnome-extensions enable hints@realh.co.uk.

Setup keyboard shortcuts

• Open Gnome settings.
• In Gnome setting click on the Keyboard option in the side navigation bar.
• Under Keyboard Shortcuts click on View and Customize Shortcuts.
• In the new window that opens click on Custom Shortcuts.
• Add a new keyboard shortcut by clicking on the + button.
• In the new window that opens type hints in the Name field.
• Type hints in the Command field.
• Click on the Shortcut button and press the keyboard combination you want to use. For example Super+i.
• Click on the Add button.
• Repeat the same steps to add a scroll key binding with the Name hints_scroll, the command hints --mode scroll, and a keyboard shortcut of your choice like Super+y