Skip to content

mjrusso/scoot

Repository files navigation

Scoot

Meet Scoot, your friendly cursor teleportation and actuation tool.

Scoot helps you efficiently move your mouse cursor, using keyboard shortcuts!

For updates, follow @mjrusso on Twitter.

build status

Scoot, MacOS Cursor Actuator


Scoot App Icon

Scoot is a tiny utility app that provides fast, keyboard-driven control over the mouse pointer. Scoot lets you move your mouse—and click and drag, too—all from the comfort of your keyboard.

Scoot supports two primary navigation modes: element-based, and grid-based.

  • Element-based navigation: MacOS accessibility APIs are used to find user interface elements, such as buttons and links, on the user's screen. (In this mode, Scoot will look for elements in the focused window of the frontmost app.) Here, for example, Scoot has identified the only link on the page ("More information..."), and assigned it the key sequence "aa":

Scoot using the element-based navigation mode

  • Grid-based navigation: all connected screens are subdivided into a grid of equally-sized cells.

Scoot using the grid-based navigation mode

Each location is identified by a unique character sequence, making each element (or cell) uniquely addressable with the keyboard — simply type the associated key sequence to teleport your mouse cursor to that location.

Scoot also supports moving the mouse cursor using text editing keyboard shortcuts that you're likely already familiar with (specifically, those for moving the insertion point). Scoot supports standard MacOS text editing shortcuts, as well as Emacs and vi keybindings. For a full breakdown, see the usage documentation.

There's also a supplementary usage mode:

  • Freestyle: a freeform usage mode that offers no special navigation assistance. It's like using the grid-based navigation mode, but without bringing up the grid.

Freestyle mode is particularly handy for those cases where you want to quickly nudge the cursor using the (re-purposed) text editing keyboard shortcuts, and would prefer to not have the grid or element-based views on screen.

About

  • This project started as an experiment: an attempt to craft a keyboard-driven mouse movement utility that's efficient, and (more importantly) that users will actually want to use. It has met that bar, at least for the primary author. (Scoot may not be for you, and that's totally fine!)

  • Scoot is not intended to replace the mouse or trackpad entirely. It's here to augment them.

  • Scoot runs on MacOS 11 (Big Sur), and 12 (Monterey).

  • Scoot is an AppKit app, written in Swift. (There's still some Carbon in here, too! Yes, really.)

  • Scoot complements mouse-related accessibility tools that ship as part of MacOS, such as Mouse Keys and other accessibility shortcuts, in addition to mouse emulation provided via keyboard firmware (QMK, for example).

Usage

To activate Scoot in the element-based navigation mode, use the ⇧⌘J global keyboard shortcut. Alternatively, to activate Scoot in the grid-based navigation mode, use the ⇧⌘K global keyboard shortcut. And for freestyle mode, use the ⇧⌘L global keyboard shortcut. (These shortcuts can be customized.)

As long as Scoot is running, any of these hotkeys will bring the app to the foreground, and activate the requested mode.

When Scoot is in the foreground:

  • You can jump directly to a cell (a UI element, or a location in the grid, depending on the active navigation mode). Each cell is marked with a label (e.g. “aaa”, “aas”, “aad”); type the characters, one letter at a time, and, as soon as a complete sequence is entered, the mouse cursor will move directly to the center of the corresponding cell. (This approach, including the use of a char-based decision tree, is heavily inspired by avy.)

    • If you make a mistake while entering a label, hit the escape key (⎋) to cancel and start over. (Alternatively, you can type ⌘. or C-G.)
    • This feature is not available in freestyle mode, which does not present any special UI, or otherwise offer any navigation assistance via a char-based decision tree.
  • You can also move the cursor via the standard Mac keyboard shortcuts for moving the insertion point. (This means that keyboard shortcuts intended for navigating around in a document have been re-purposed to control movement on a 2-dimensional grid. Some liberties have been taken with this mapping; hopefully you find these keybindings intuitive.) This feature works in all modes (element-based, grid-based, and freestyle).

  • You can click with the left mouse button (at the current cursor location) by hitting the Return (↵) key.

  • You can hold the left mouse button down by pressing =. (To release the button, press ↵.)

    • To perform a drag-and-drop operation: situate the cursor above the object you want to drag and press =, then move the mouse cursor to the desired drag destination (using one or more of the mechanisms that Scoot makes available), and then press ↵ to perform the drop.
  • You can double-click with the left mouse button (at the current cursor location) by hitting the Shift and Return keys together (⇧↵).

  • You can scroll, by pressing the Shift key in conjunction with the arrow key (↑, ↓, ←, →) pointing in the desired scroll direction.

After clicking, any overlaid UI elements (such as the element view, or the grid) will automatically hide. You can also hide these UI elements (and send Scoot to the background) at any time by pressing ⌘H.

Scoot includes a menu bar icon (an illustration of a Vespa-inspired scooter).

Scoot Menu Bar Icon

  • When Scoot is not active (i.e., running in the background), the icon will render in an outlined mode.
  • When Scoot is in the foreground, the icon will render with a fill (see screenshot), to make it clearer that Scoot is currently active. (This shouldn't generally be a concern, but it is especially handy when you're in freestyle mode.)
  • Additional options are exposed when clicking on the menu bar icon, including a help menu item — which currently opens this README in the user's default browser.

Scoot is fully compatible with Spaces (and can be used in conjunction with apps that are running in native fullscreen mode).

Scoot also works on systems with multiple connected displays.

Using Scoot with multiple connected displays

If you use multiple displays, and experience an issue with Scoot's windows drawing in an incorrect location when the app launches (e.g. all Scoot windows appearing on the same display), please post your findings in this issue, and note the value of your “Displays have separate Spaces” checkbox in Mission Control. If you do happen to find yourself in this state, you should be able to fix the window arrangement by clicking Scoot's menu bar icon, then “Debug”, and finally “Rebuild Jump Windows”.

To customize Scoot's settings, click Scoot's menu bar icon, then “Preferences…”, or type ⌘, while Scoot is in the foreground. In addition to modifying keybindings, it is also possible to modify Scoot's appearance (including font sizes, colours, opacity, etc.).

Keybindings

Not sure what these symbols mean? See the symbol reference, and Emacs key notation.

Global Keybindings

Global keybindings are always active, as long as Scoot is currently running.

Default Shortcut Description
⇧⌘J Use element-based navigation (bring Scoot to foreground)
⇧⌘K Use grid-based navigation (bring Scoot to foreground)
⇧⌘L Use freestyle mode (bring Scoot to foreground)

All global keybindings are fully customizable. To modify the keybindings, click Scoot's menu bar icon, then “Preferences…”, and select the “Keybindings” tab.

Local Keybindings

Local keybindings are only active when Scoot is active (i.e., when Scoot is in the foreground).

Note that vi keybindings are not enabled by default, and must be explicitly toggled on (click Scoot's menu bar icon, then “Preferences…”, select the “Keybindings” tab, and then change the keybinding mode). Emacs keybindings (and most system keybindings) are disabled when vi keybindings are active.

General
Shortcut Alternate Description
⌘H Hide UI (bring Scoot to background)
⎋ (or ⌘.) C-g Cancel: if currently typing a label, clears all currently-typed characters; otherwise, brings Scoot to background

Note: ⎋ signifies the Escape key.

Cursor Movement
System Emacs vi Description
C-p k Move cursor up (partial step)
C-n j Move cursor down (partial step)
C-b h Move cursor left (partial step)
C-f l Move cursor right (partial step)
⌥↑ M-a C-k Move cursor up (full step)
⌥↓ M-e C-j Move cursor down (full step)
⌥← M-b C-h Move cursor left (full step)
⌥→ M-f C-l Move cursor right (full step)
⌘↑ M-< ⇧-k Move cursor to top edge of screen
⌘↓ M-> ⇧-j Move cursor to bottom edge of screen
⌘← C-a ⇧-h Move cursor to left edge of screen
⌘→ C-e ⇧-l Move cursor to right edge of screen
⌃L C-l ⇧-m Move cursor to center, and (on repeat) cycle around corners
Clicking
Shortcut Description
Click left mouse button (at current cursor location)
= Press and hold left mouse button (once activated, type to release)
\ Double-click left mouse button (at current cursor location)
[ Click middle mouse button (at current cursor location)
] Click right mouse button (at current cursor location)

Scoot will pass along any pressed modifier keys when simulating clicks. This means that Command-click, Option-click, Control-click, and Shift-click are all supported (or any combination thereof). For example, ⌘↵ will Command-click the left mouse button at the current cursor location, ⌥↵ will Option-click, ⌃↵ will Control-click, ⇧↵ will Shift-click, etc.

Scoot can't take control of the mouse cursor when a context menu is active (for example, after right clicking). However, system-provided keyboard shortcuts for selecting the item in a menu (such as ↑, ↓, ←, →, C-n, C-p, ↵) will work as expected.

For simplicity, Scoot only supports simulating holding/ dragging, and double clicking, with the left mouse button. (If you have a use case that requires more exotic click handling, please file an issue with details.)

Note: ↵ signifies the Return (a.k.a Enter) key. (Sidenote: technically, Return and Enter are two different keys.)

Scrolling
System Emacs vi Description
⇧↑ ⇧-p C-b Scroll up (at current cursor location)
⇧↓ ⇧-n C-f Scroll down (at current cursor location)
⇧← ⇧-b C-i Scroll left (at current cursor location)
⇧→ ⇧-f C-a Scroll right (at current cursor location)
Presentation
Shortcut Description
⌃= Toggle visibility of grid lines
⌃⇧= Toggle visibility of grid labels
⇧⌘= Increase size of grid cells
⇧⌘- Decrease size of grid cells
⌘= Increase contrast of user interface
⌘- Decrease contrast of user interface

Installation

Scoot is available on Homebrew:

brew install --cask scoot

Alternatively, you can manually download the app bundle:

  1. Download and extract the latest build of Scoot.
  2. Drag the extracted Scoot.app into your computer's Applications folder.
  3. Double-click on Scoot.app (from the Applications folder) to launch it.

Setup

On first run, you'll be presented with a prompt like the following:

Scoot.app would like to control this computer using accessibility features

Scoot will not work unless access is granted. (Note that Scoot does not collect any user or usage-related information, and does not make any network requests. The app runs entirely locally, and treats its privileged access with the utmost respect.)

To grant this permission, click “Open System Preferences”. Next, click the lock in the bottom left corner (“Click the lock to make changes”).

Locked accessibility settings

Finally, check “Scoot.app” to give Scoot the ability to move your cursor, and to click, drag, and scroll.

Scoot.app granted accessibility access

See the usage documentation for details on how to use Scoot.

If you're finding Scoot helpful, you may want to configure the app to launch automatically when you log in. To set this up, open System Preferences again, click “Users & Groups”, and then “Login Items”:

Locked login items settings

As before, you'll need to click the lock in the bottom left corner to unlock this preference pane. Once unlocked, click the “+” button, and select “Scoot.app” from the Applications folder. Checking the “Hide” checkbox is recommended.

Scoot configured to start automatically

If you encounter any problems, feel free to file an issue.

Demos

Element-based Navigation

This is what it's like to navigate around Wikipedia in Safari, using the element-based navigation mode:

element-based-nav-browsing-wikipedia.mp4

Drag and Drop

Here's what it's like to drag and drop with Scoot, using the grid-based navigation mode:

drag-and-drop.mp4

For reference, the following key sequence was used to grab the file and drop it in a new location:

  • ⇧⌘K to activate Scoot
  • kh to jump cursor to cell
  • = to press and hold the left mouse button
  • fd to jump cursor to cell
  • to release the left mouse button

Feature Backlog

See the issue tracker. Contributions welcome!

License

Scoot is released under the terms of the BSD 3-Clause License.

Copyright (c) 2021-2023, Michael Russo.