Click, scroll, and drag with your keyboard

Navigate GUIs without a mouse by typing hints in combination with modifier keys.

• click once (jk)
• click multiple times (2jk)
• right click (SHIFT + jk)
• drag (ALT + jk)
• Note for wayland users: Due to how different wayland compositors handle overlay windows, dragging might not always work for your compositor.
• hover (CTRL + jk)
• scroll/move the mouse using vim key bindings (h,j,k,l)

Don't like the keybindings? That's ok, you can change them.

Installing

[!IMPORTANT]

• You need to have some sort of compositing setup so that you can properly see hints on top of windows with the correct level of transparency. If you run hints and see an opaque/black window rather than a transparent window; this is probably why.

[!NOTE]
The install script below does the following:

1. Installs any required system dependencies for Ubuntu, Arch, and Fedora systems. If you don't run any of those distros, you can look at the install script to see what you need to install.
2. Temporarily installs UV.
3. Uses uv tool to install the latest version of hints.
4. Cleans up leftover files.

Run the install script:

curl -fsSL https://raw.githubusercontent.com/AlfredoSequeida/hints/main/install.sh | bash

[!NOTE]
By default, the install script installs the latest release. If you want to install a specific version add -s -- --version {version} to the end of the command. A version can be a release, commit, tag, or branch. Here are some examples:

curl -fsSL https://raw.githubusercontent.com/AlfredoSequeida/hints/main/install.sh | bash -s -- --version main

curl -fsSL https://raw.githubusercontent.com/AlfredoSequeida/hints/main/install.sh | bash -s -- --version 0.0.7

Setup

1. To facilitate setup, hints ships with a setup script.

To setup hints run:

sudo env XDG_SESSION_TYPE=$XDG_SESSION_TYPE env XDG_CURRENT_DESKTOP=$XDG_CURRENT_DESKTOP $(whereis hints | awk '{print $2}') --setup

1. At this point you're pretty much done. You can verify this by running hints in a terminal emulator. However, you should bind hints to your keyboard so that you can summon hints on command. This is very desktop environment / window manager specific, but to get you started here are some examples for popular systems:

2. i3/sway

3. Hyprland
4. Gnome

[!NOTE]
If you still don't see any hints, the application you're testing could need a bit of extra setup. Please see the Help,-hints-doesn't-work-with-X-application page in the wiki.

Documentation

For a guide on configuring and using hints, please see the Wiki.

Contributing

The easiest ways to contribute are to:

• Become a sponsor. Hints is a passion project that I really wanted for myself and I am working on it in my spare time. I chose to make it free and open source so that others can benefit. If you find it valuable, donating is a nice way to say thanks. You can donate any amount you want.
• Report bugs. If you notice something is not working as expected or have an idea on how to make hints better, open up an issue. This helps everyone out.
• If you can code, feel free to commit some code! You can see if any issues need solutions or you can create a new feature. If you do want to create a new feature, it's a good idea to create an issue first so we can align on why this feature is needed and if it has a possibility of being merged.

Development

If you want to help develop hints, first setup your environment:

1. Create a virtual environment for the project.

python3 -m venv venv

1. Activate your virtual environment for development. This will differ based on OS/shell. See the table here for instructions.

2. Install hints as an editable package (from the repository's root directory):

pip install -e .

At this point, hints should be installed locally in the virtual environment, you can run hints in your shell to launch it. Any edits you make to the source code will automatically update the installation. For future development work, you can simply re-enable the virtual environment (step 2).

Development tips

• If you are making updates that impact hints, you will most likely need to test displaying hints and might find yourself executing hints but not being quick enough to switch to a window to see hints. To get around this, you can execute hints with a short pause in your shell: sleep 0.5; hints. This way you can have time to switch to a window and see any errors / logs in your shell.
• If hints is consuming all keyboard inputs and you're trapped: switch to a virtual terminal with e.g. CTRL+ALT+F2, login, and run killall hints. You can then exit with exit and switch back to the the previous session (most likely 1): CTRL+ALT+F1