skip to content
MusesΜοῦσαιdocs

basics / 01 of 13

Introduction

stochos clicks for you from the keyboard, on Wayland, X11 and macOS. Press its key, type where you want to click, and press Space.

What stochos is

Bound to a key, stochos covers the screen with a grid of letter pairs. Type a cell’s two letters and the pointer jumps to it. One more letter picks a spot inside the cell, and Space clicks there. That’s four keys, and no reach for the mouse.

The grid is normal mode. Three other modes aim differently:

  • Bisect mode splits the screen into four and zooms into the quarter you pick, again and again, until the pointer is where you want it.
  • Hint mode puts a label on every button, link and field it can find, and you type the label.
  • Free mode steers the pointer a step at a time with h, j, k and l.

Every mode can click, double-click, triple-click, right-click and middle-click, and every mode but hint mode scrolls with the arrow keys. The grid also drags, and records macros: clicks in sequence that you replay with two keys.

What it isn’t

  • A daemon. stochos starts when you press its key and exits after the click. Nothing runs in between.
  • Tied to one program. Browser extensions like Vimium label links inside the browser. stochos works over the whole screen. The grid doesn’t care what’s under it, and reaches into programs that publish nothing to click on, like a remote desktop.
  • For GNOME on Wayland. It needs a compositor with wlr-layer-shell and wlr-virtual-pointer, such as Hyprland or Sway. On GNOME, run an X11 session.

Timeline

  1. 2026

    1. v1.0.1

      • On X11 under a compositor, the grid shows instead of a black screen.

    2. v1.0.0

      • Hint mode labels what looks clickable, from the accessibility tree or a screenshot, with --hint.
      • Middle click on macOS.

    3. v0.6.2

      • Home, End, Page Up and Page Down are read right on Wayland.

    4. v0.6.1

      • Keys follow the keyboard layout on Linux.

    5. v0.6.0

      • Triple click, on m.
      • Middle click, on Insert, on Linux.

    6. v0.5.0

      • Free mode, with --free and --free-center.
      • Macros wait between steps as long as you did, scaled by playback_speed.
      • Holding an arrow key keeps scrolling on Wayland.
      • The install script works on macOS.

    7. v0.4.0

      • macOS.
      • stochos writes config.toml on its first run, and --print-default-config prints the defaults.

      • On crates.io, for cargo install stochos.

    9. v0.3.5

      • Bisect mode, with --bisect.

    10. v0.3.4

      • Control and Alt can be bound on their own.
      • GNOME on X11.

    11. v0.3.3

      • The first letter moves the pointer to its column, so the arrows scroll there.

    12. v0.3.2

      • One stochos at a time, unless --allow-multiple.

    13. v0.3.1

      • font_size scales the letters up for high-DPI screens.

    14. v0.3.0

      • Colours in config.toml.
      • target_cell_size fits the grid to the screen.
      • On Wayland, the grid opens on the focused display.
      • A Nix flake, with a Home Manager module.

    15. v0.2.0

      • X11.

    16. v0.1.0

      • Keys and letters in config.toml.
      • The install script, and the first release binaries.

      • Scrolling with the arrow keys.
      • Right click, and Backspace to step back.

      • Macros.

      • The grid: two letters pick a cell, and one more picks a spot in it.
      • Double click on Enter, and dragging with /.

  2. 2025

      • The first commit: a click synthesised on Wayland.

Where to go next

  • Installing stochos, and the permissions it needs on macOS.
  • A first click: a key binding, and the grid from the first letter to the click.
  • Keys: every key in every mode.