# AlfredoSequeida/hints: Keyboard Hints for Linux GUI Applications

> AlfredoSequeida/hints overlays typeable hints on Linux GUI elements so keyboard users can click, right-click, drag, hover, scroll, and move the pointer. It supports customizable bindings, but requires compositing and desktop-specific configuration, with drag support varying under Wayland.

**AlfredoSequeida/hints** — Hints lets you navigate GUI applications in Linux without your mouse by displaying "hints" you can type on your keyboard to interact with GUI elements.

- Repository: https://github.com/AlfredoSequeida/hints
- Stars: 1,386 · Forks: 52
- Language: Python
- License: GPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/alfredosequeida-hints

## Why hints Targets Mouse-Dependent Linux Workflows

AlfredoSequeida/hints addresses a specific gap in Linux desktop use: many graphical controls are visually obvious but still require the pointer. The project places a short text hint over an interactive GUI element. A user types that hint, optionally with modifier keys, and hints turns the selection into an action such as a click, multiple click, right click, drag, or hover.

The intended audience is clear from the interaction model. It suits people who want Vim-style spatial navigation, already depend heavily on keyboard shortcuts, use tiling window managers, or find repeated mouse movement inconvenient. The README describes click once through `j` followed by `k`, multiple clicks through `2` followed by the same keys, and modifier-assisted variants. Pointer movement and scrolling also use the familiar `h`, `j`, `k`, and `l` directions.

This is not a replacement for every desktop shortcut. Window management, application commands, and workspace actions still need bindings supplied by the desktop environment or window manager. Hints instead acts at the GUI-element level, where applications expose buttons, links, fields, and other visible controls without application-specific configuration.

## How Typed Hints Become Pointer Actions

The documented interaction has two layers. The first is a keyboard sequence, such as a character pair or a character pair combined with `SHIFT`, `ALT`, or `CTRL`. The second is an operation performed against the GUI element carrying the matching hint. The README gives `SHIFT` plus the example sequence for a right click, `ALT` for drag, and `CTRL` for hover.

The overlay itself depends on compositing. Hints describes a transparent layer above application windows, which means correct alpha rendering is part of the operating path rather than a cosmetic preference. If the display is opaque or black, the README points to the compositing requirement first. That constraint also explains why the project cannot guarantee identical presentation across every Linux display stack.

Based on the repository layout, `hintsd.desktop` and the installation code connect the command to a background service, while `setup.py` contains post-install handling for that service. The README does not expose the internal communication protocol or describe the component boundaries in detail. It does, however, document the observable model clearly enough to understand the feature as an overlay, typed selector, and mouse-action bridge.

## Installing hints and Running the First Setup

The documented installation path is a remote shell script. On Ubuntu, Arch, and Fedora, it installs required system dependencies, temporarily installs UV, uses `uv tool` to install the latest hints release, and removes leftover files. Other Linux distributions need to inspect the script for their own dependencies.

This command downloads and executes `install.sh`:

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

A specific release, commit, tag, or branch can be selected by adding the documented arguments. This example pins installation to `0.0.7`:

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

After installation, run the setup command with elevated privileges. It passes the current session type and desktop name into the installed binary:

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

The first direct verification is to launch `hints` from a terminal emulator and then inspect an application window for visible hints. If they do not appear, check compositing first and then follow the project's X application help page because the target application may require extra configuration.

## Desktop Bindings, Compositing, and the Wayland Drag Boundary

Installation is only the first part of a usable configuration. Hints must be summoned from a keyboard shortcut, but the exact binding belongs to the active desktop environment or window manager. The repository links separate setup instructions for i3 and Sway, Hyprland, and GNOME. This delegation avoids pretending that Linux desktops expose one universal binding mechanism.

Compositing is the first technical checkpoint. The README says an opaque or black overlay usually indicates missing or unsuitable compositing. That symptom can prevent the core selection interface from being legible, so it should be resolved before evaluating keybindings or changing application settings.

Wayland presents a separate boundary. The project warns that overlay-window behavior differs among compositors and that dragging may not always work. Consequently, hints can be useful under Wayland without being a dependable replacement for dragging in every compositor. The limitation is specific to drag behavior, not to the existence of the tool under Wayland.

There is also a recovery path for accidental input capture. If hints consumes all keyboard input, the README directs the user to a virtual terminal, authenticate, and run `killall hints`. This is an operational escape hatch rather than proof that every keyboard capture failure is resolved by configuration.

## hints Compared with Desktop-Native Keyboard Shortcuts

The practical alternative is a set of desktop-native shortcuts that invoke application commands or focus controls directly. A window manager or desktop environment can bind commands without placing text hints over arbitrary GUI controls. Those bindings are also the right choice when an application has stable, documented keyboard shortcuts, because the user can invoke commands without first locating a visual element.

Hints takes a different approach. It works from visible GUI elements and assigns hints that can be typed, with modifiers selecting pointer actions. That makes it relevant to controls that lack a predictable application shortcut and to cross-application navigation. The trade-off is dependence on accurate overlay placement, compositing, compositor behavior, and a visual targeting workflow. Native shortcuts avoid the overlay, while hints accepts that dependency in exchange for reaching visible controls without application-specific mappings.

A tiled-window-manager user may also compare hints with a browser extension inspired by Vim-style hints. The README explicitly positions hints as a Linux desktop equivalent of that interaction concept, but it does not document browser scope, supported browser versions, or compatibility details. The defensible difference is therefore platform focus: hints targets Linux GUI applications through a desktop command rather than documenting browser extensions.

## Release History, GPL-3.0, and Upgrade Work

The repository is not archived, and its last push was on 2026-06-28. The listed releases are `0.1.1` on 2026-06-28, `0.1.0` on 2026-06-01, and `0.0.7` on 2026-06-01. Those dates show recent project activity in the repository, but the README does not publish a compatibility policy or a migration guide for upgrades.

The standard installer obtains the latest release unless a version is supplied. Users who require repeatable configuration can therefore use the documented `--version` argument with a release, commit, tag, or branch. Development users can instead create a virtual environment and install the checkout as editable:

```bash
python3 -m venv venv
```

After activating that environment, install from the repository root:

```bash
pip install -e .
```

This development path is not a release upgrade mechanism. It keeps the command available from the local environment and reflects source edits as described in the README.

Hints is distributed under `GPL-3.0`. The license governs use and redistribution according to its terms, but this review does not interpret those terms. Organizations should review the actual `LICENSE` file and any planned distribution or modification against it.

## Conclusion

Linux users who regularly interact with GUI elements from the keyboard, especially i3, Sway, or Hyprland users, should first verify that their compositor renders transparent overlays correctly. Users who need predictable Wayland dragging, X11 application compatibility without extra setup, or a fully documented zero-configuration installation should review the linked wiki first. The immediate project-specific check is to run `hints` after setup and confirm that typed hints produce the intended action.

## FAQ

### How do I install AlfredoSequeida/hints on Linux?

Run the documented `curl` and `bash` installer, then execute the binary with `--setup`. The installer supports Ubuntu, Arch, and Fedora dependencies, while other distributions require checking the script manually.

### What should I check if AlfredoSequeida/hints does not display overlay hints?

Check whether the desktop has the required compositing setup, especially if the overlay is opaque or black. The application being targeted may also need the extra X application configuration described in the project wiki.

### Does AlfredoSequeida/hints support dragging under Wayland?

Wayland users should expect compositor-dependent behavior. The README warns that dragging might not always work because compositors handle overlay windows differently.

## Sources

- [AlfredoSequeida/hints on GitHub](https://github.com/AlfredoSequeida/hints)
- [Issues](https://github.com/AlfredoSequeida/hints/issues)
- [License: GPL-3.0](https://github.com/AlfredoSequeida/hints/blob/main/LICENSE)
- [README](https://github.com/AlfredoSequeida/hints/blob/main/README.md)
- [Releases](https://github.com/AlfredoSequeida/hints/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alfredosequeida-hints