{"id":22967070,"url":"https://github.com/moverest/wl-kbptr","last_synced_at":"2026-03-07T06:32:02.681Z","repository":{"id":157754670,"uuid":"630196988","full_name":"moverest/wl-kbptr","owner":"moverest","description":"Control the mouse pointer with the keyboard on Wayland.","archived":false,"fork":false,"pushed_at":"2025-11-30T23:45:55.000Z","size":288,"stargazers_count":430,"open_issues_count":16,"forks_count":24,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-12-03T09:44:40.888Z","etag":null,"topics":["hyprland","mouse-pointer-control","niri","swaywm","wayland"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moverest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-04-19T21:53:26.000Z","updated_at":"2025-12-01T14:56:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"36f75b8b-95b8-4758-99e1-635dea221fcf","html_url":"https://github.com/moverest/wl-kbptr","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/moverest/wl-kbptr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moverest%2Fwl-kbptr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moverest%2Fwl-kbptr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moverest%2Fwl-kbptr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moverest%2Fwl-kbptr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moverest","download_url":"https://codeload.github.com/moverest/wl-kbptr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moverest%2Fwl-kbptr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30209086,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T05:23:27.321Z","status":"ssl_error","status_checked_at":"2026-03-07T05:00:17.256Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hyprland","mouse-pointer-control","niri","swaywm","wayland"],"created_at":"2024-12-14T21:01:00.079Z","updated_at":"2026-03-07T06:32:02.668Z","avatar_url":"https://github.com/moverest.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# wl-kbptr\n\n`wl-kbptr` \u0026mdash; short for Wayland Keyboard Pointer \u0026mdash; is a utility to help move the mouse pointer with the keyboard.\n\nSee [Supported compositors](#supported-compositors) section for compatibility.\n\n## Modes\n\nTo enable to select a target and click, it has four different modes:\n- [`floating`](#floating-mode) \u0026mdash; which uses arbitrary areas either given by the user or detected,\n- [`tile`](#tile-mode) \u0026mdash; which uses a grid to select areas,\n- [`bisect`](#bisect-mode) \u0026mdash; which enables to bisect an area,\n- [`split`](#split-mode) \u0026mdash; which enables to successively split an area,\n- and [`click`](#click-mode) \u0026mdash; which triggers a click in the middle of an area.\n\nThese are set with the `modes` configuration field and can be chained, e.g. `wl-kbptr -o modes=tile,bisect`.\n\nNote that if you make a mistake \u0026mdash; e.g. select the wrong area \u0026mdash; you can always go back on step by pressing the `Backspace` key. This even works between modes.\n\n### Floating mode\n[Floating Mode Demo](https://github.com/user-attachments/assets/1598128b-e03b-4d06-b47a-bc8a0021f4da)\n\nThe `floating` mode uses arbitrary selection areas that can be passed by the user through the standard input. Each input line represents an area defined with the `wxh+x+y` format.\n\n#### Auto-detection\nThe areas can also be automatically detected with `mode_floating.source` configuration set to `detect`, e.g. `wl-kbptr -o modes=floating,click -o mode_floating.source=detect`.\n\nThis requires the `wl-kbptr` binary to be built with the `opencv` feature and the compositor to support the [`wlr-screencopy-unstable-v1`](https://wayland.app/protocols/wlr-screencopy-unstable-v1) protocol \u0026mdash; see the [supported compositors](#supported-compositors) section and [build instructions](#from-sources) for details. Whilst it doesn't noticeably change the size of the program itself, OpenCV is a 100 MB+ dependency which is not ideal if you want a very small system which is why this is an optional feature.\n\nMost distributions will package the program with the option enabled. If not, they will usually provide two packages. You can check if the binary you have has been built with it with `wl-kbptr --version` \u0026mdash; it should print `opencv` if supported.\n\n### Tile mode\n[Tile Mode Demo](https://github.com/user-attachments/assets/d8c9c8dc-2733-4835-9d82-d0f5b093c382)\n\nThe `tile` mode displays a grid. To select an area, simply type the label associated with the tile you want to select.\n\n### Bisect mode\n[Bisect Mode Demo](https://github.com/user-attachments/assets/8f8f7fb4-1bb9-4180-9eda-78ee1ff14181)\n\nThe `bisect` mode enables to bisect a given area. At any point the cursor can be moved at the location marked by the red marker by pressing `Enter` or `Space`.\n\nA left, right and middle click can be made by pressing the `g`, `h` and `b` keys respectively on a QWERTY keyboard layout. Note that other layout will use the same keys positions, e.g. `i`, `d`, and `x` with a Dvorak keyboard layout.\n\n### Split mode\n[Split Mode Demo](https://github.com/user-attachments/assets/760fa154-ce50-47b4-8f9a-26c5ac79a55b)\n\nThe `split` mode enables to successively split an area with the arrow keys.\n\nJust like the `bisect` mode, a left, right and middle click can be made by pressing the `g`, `h` and `b` keys respectively on a QWERTY keyboard layout.\n\n### Click mode\n\nThe `click` mode simply triggers a click in the middle of the selection area.\n\n## Supported compositors\n\nFor `wl-kbptr` to work, it requires the following protocols:\n - [`wlr-layer-shell-unstable-v1`](https://wayland.app/protocols/wlr-layer-shell-unstable-v1) for the program to display on top,\n - [`wlr-virtual-pointer-unstable-v1`](https://wayland.app/protocols/wlr-virtual-pointer-unstable-v1) to control the mouse pointer,\n - and [`wlr-screencopy-unstable-v1`](https://wayland.app/protocols/wlr-screencopy-unstable-v1) (optional) to capture the screen for target detection in the `floating` mode.\n\nHere are the compositors with which it has been tested:\n\n| Compositor |     | Notes |\n| ---------- | --- | ----- |\n| [Sway](https://swaywm.org) | ✅ | - |\n| [Hyprland](https://hyprland.org) | ✅ | - |\n| [niri](https://github.com/YaLTeR/niri) | ✅ | - |\n| [dwl](https://codeberg.org/dwl/dwl) | ✅ | - |\n| [labwc](https://labwc.github.io) | ✅ | - |\n| [Wayfire](https://wayfire.org) | ✅ | The pointer doesn't move to the right location with multiple display outputs. See [#56](https://github.com/moverest/wl-kbptr/issues/56#issuecomment-3087922040). |\n| [KWin](https://github.com/KDE/kwin) | ❗ | The compositor doesn't support the [`wlr-virtual-pointer-unstable-v1`](https://wayland.app/protocols/wlr-virtual-pointer-unstable-v1) and [`wlr-screencopy-unstable-v1`](https://wayland.app/protocols/wlr-screencopy-unstable-v1) protocols. It can still work with the `--print-only` option and the mouse pointer can then be moved with `ydotool` or similar. |\n| [Mutter](https://mutter.gnome.org) | ❌ | The compositor doesn't support any of the required protocols. |\n\n## Installation\n\n### Arch Linux\n\nIf you are using Arch Linux, you can install the [`wl-kbptr` AUR package](https://aur.archlinux.org/packages/wl-kbptr).\n\nRecommended way to build and install the package directly from the AUR (gets all required files):\n```bash\ngit clone https://aur.archlinux.org/wl-kbptr.git\ncd wl-kbptr\nmakepkg -si\n```\n\nAlternatively, if you only want the `PKGBUILD`:\n```bash\ncurl -L 'https://aur.archlinux.org/cgit/aur.git/plain/PKGBUILD?h=wl-kbptr' -o PKGBUILD\nmakepkg -si\n```\n\n### NixOS\n\nIf you are using NixOS, you can install the [`wl-kbptr` package](https://search.nixos.org/packages?query=wl-kbptr). Nix can also be used to install `wl-kbptr` on other distributions.\n\n### Chimera Linux\n\nIf you are using Chimera Linux, you can install the [`wl-kbptr` package](https://pkgs.chimera-linux.org/package/current/contrib/x86_64/wl-kbptr) which is available in the [contrib repository](https://chimera-linux.org/docs/apk#repositories).\n\n```bash\napk add chimera-repo-contrib\napk add wl-kbptr\n```\n### Fedora\n\nAs of now there is no official package through dnf. So you will need to install the dependencies and then run the steps described in the **From sources** section.\n\n```bash\nsudo dnf install -y \\\n    meson \\\n    wayland-protocols-devel \\\n    gcc \\\n    libwayland-client  \\\n    cmake \\\n    wayland-devel \\\n    libxkbcommon-devel \\\n    cairo-devel\n```\n\n### From sources\n\nYou can build from sources with:\n\n```bash\nmeson setup build --buildtype=release\nmeson compile -C build\n```\n\nIf you want to build the target detection feature (see [floating mode](#floating-mode)), you need to enable the `opencv` feature:\n\n```bash\nmeson setup build --buildtype=release -Dopencv=enabled\nmeson compile -C build\n```\n\nThen install with:\n\n```bash\nmeson install -C build\n```\n\n## Setting the bindings\n\n### Sway\n\n```\nmode Mouse {\n    bindsym a mode default, exec 'wl-kbptr-sway-active-win; swaymsg mode Mouse'\n    bindsym Shift+a mode default, exec 'wl-kbptr; swaymsg mode Mouse'\n\n    # Mouse move\n    bindsym h seat seat0 cursor move -15 0\n    bindsym j seat seat0 cursor move 0 15\n    bindsym k seat seat0 cursor move 0 -15\n    bindsym l seat seat0 cursor move 15 0\n\n    # Left button\n    bindsym s seat seat0 cursor press button1\n    bindsym --release s seat seat0 cursor release button1\n\n    # Middle button\n    bindsym d seat seat0 cursor press button2\n    bindsym --release d seat seat0 cursor release button2\n\n    # Right button\n    bindsym f seat seat0 cursor press button3\n    bindsym --release f seat seat0 cursor release button3\n\n    bindsym Escape mode default\n}\n\nbindsym $mod+g exec wl-kbptr-sway-active-win -o modes=floating','click -o mode_floating.source=detect\nbindsym $mod+Shift+g mode Mouse\n```\n\n### Hyprland\n\n```\n# Cursor submap (similar to the Mouse mode in Sway)\nsubmap=cursor\n\n# Jump cursor to a position\nbind=,a,exec,hyprctl dispatch submap reset \u0026\u0026 wl-kbptr \u0026\u0026 hyprctl dispatch submap cursor\n\n# Cursor movement\nbinde=,j,exec,wlrctl pointer move 0 10\nbinde=,k,exec,wlrctl pointer move 0 -10\nbinde=,l,exec,wlrctl pointer move 10 0\nbinde=,h,exec,wlrctl pointer move -10 0\n\n# Left button\nbind=,s,exec,wlrctl pointer click left\n# Middle button\nbind=,d,exec,wlrctl pointer click middle\n# Right button\nbind=,f,exec,wlrctl pointer click right\n\n# Scroll up and down\nbinde=,e,exec,wlrctl pointer scroll 10 0\nbinde=,r,exec,wlrctl pointer scroll -10 0\n\n# Scroll left and right\nbinde=,t,exec,wlrctl pointer scroll 0 -10\nbinde=,g,exec,wlrctl pointer scroll 0 10\n\n# Exit cursor submap\n# If you do not use cursor timeout or cursor:hide_on_key_press, you can delete its respective calls.\nbind=,escape,exec,hyprctl keyword cursor:inactive_timeout 3; hyprctl keyword cursor:hide_on_key_press true; hyprctl dispatch submap reset \n\nsubmap = reset\n\n# Entrypoint\n# If you do not use cursor timeout or cursor:hide_on_key_press, you can delete its respective calls.\nbind=$mainMod,g,exec,hyprctl keyword cursor:inactive_timeout 0; hyprctl keyword cursor:hide_on_key_press false; hyprctl dispatch submap cursor\n```\n\n## Configuration\n\n`wl-kbptr` can be configured with a configuration file. See [`config.example`](./config.example) for an example and run `wl-kbptr --help-config` for help.\n\n## Dependencies\n\n- [`xkbcommon`](https://xkbcommon.org)\n- [`cairo`](https://cairographics.org)\n- [`wayland`](https://wayland.freedesktop.org)\n- [`wayland-protocols`](https://gitlab.freedesktop.org/wayland/wayland-protocols)\n- With the `opencv` feature enabled:\n  - C++ compiler\n  - [`OpenCV`](https://opencv.org)\n  - [`Pixman`](https://www.pixman.org)\n\n\n## License\n\n[GPL-3.0](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoverest%2Fwl-kbptr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoverest%2Fwl-kbptr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoverest%2Fwl-kbptr/lists"}