Cursor Conductor

A simple first-attempt at a cross-platform desktop (electron) app to control mouse cursor position, scroll and clicks via keyboard shortcuts. Inspired by EsportToys/TPMouse.

Table of Contents

• Cursor Conductor
  • Table of Contents
  • Why?
  • Features
  • Installation
  • Usage
  • Commands
  • Dependencies
  • Related
  • Roadmap
  • License
  • FAQ

Why?

Using a mouse is great, but sometimes it's nice to be able to control the cursor with the keyboard, too. 🤷‍♂️ This little app enables just that. It's inspired by EsportToys/TPMouse, which is a nifty tool that does the same. Unfortunately, it seems to be Windows-only (written in AutoIt-- a scripting language for automating the Windows GUI), and I wanted to be able to use it on other platforms, so I decided to try and build something similar from scratch using JavaScript. This is the first iteration of that attempt. It's definitely still a work in progress, but works well enough for me so far. Hopefully, it'll be useful to someone else, too. 🙂

Features

• Easily customizable and extensible.
• Cross-platform (Windows, Linux and macOS).

Installation

The app can be installed in two ways:

1. Directly from GitHub: Download the app from GitHub and run the installer/executable (e.g., .exe for Windows, .dmg for macOS, .AppImage for Linux).
2. Cloning the repo locally and installing dependencies with a node package manager (e.g., npm, yarn, pnpm, bun): git clone https://github.com/arazzz/cursor-conductor.git && cd cursor-conductor && npm install

To install dependencies (e.g., using npm), run:

npm install

You can also build the app for your current platform with bun build, which will create a dist folder in the project root with the built app:

npm run build

Usage

To start the app in dev mode (uses nodemon to restart on file changes), run:

npm run dev

To start the app normally, run:

npm run start

Once the app is running, you can use the following default shortcuts to control the cursor:

• Alt+`: Toggle cursor control on/off.
• I: Move cursor up.
• K: Move cursor down.
• J: Move cursor left.
• L: Move cursor right.
• F: Left click.
• E: Right click.
• R: Middle click.
• S: Toggle brake mode (slows down the cursor movement).
• Space: Toggle scrolling mode (scrolls up/down when moving the cursor up/down or left/right).

You can easily change the default shortcuts (e.g., to vim [h/j/k/l] bindings) by editing the src/config/config.default.js file, or by selecting "Open Config" from the app menu in the system tray (opens a config file stored in your home directory and allows you to edit it in your default text editor; changes to this file will be reflected in the app without requiring a restart). You can also specify different configuration profiles (modes) in the config file and switch between them (when the app is active [when Alt+` has been pressed]) by pressing Ctrl+Alt+1, Ctrl+Alt+2, Ctrl+Alt+3, etc. where the number indicates the mode number (see the config file for more info). Different configurations can be useful for different use cases (e.g., different mouse sensitivity settings for different apps, one for general use, another for gaming, etc.). Currently, the app contains two default modes; mode 2 uses acceleration/deceleration to determine cursor movement, while mode 1 does not (see the mouse actions file for more info).

Commands

NPM scripts in the package.json file:

• dev: Start the app in dev mode (uses nodemon to restart on file changes).
• start: Start the app.
• build: Build the app for the current platform (see electron-builder for more info).

Dependencies

• electron: A cross-platform desktop application framework with global keyboard shortcuts.
• electron-builder: A library for building and packaging electron apps.
• uiohook-napi: To capture mouse and keyboard events.
• @jitsi/robotjs: To control the mouse cursor position and simulate mouse clicks.

Related

• EsportToys/TPMouse - A virtual trackball via vim-like homerow controls (Windows).
• rvaiya/warpd - A modal keyboard driven interface for mouse manipulation (Linux, macOS and experimental support for Windows).
• petoncle/mousemaster - A keyboard driven interface for mouse manipulation (Windows).
• wirekang/mouseable - Control the mouse via the keyboard (Windows).
• neatdecisions/neatmouse - Keyboard-based mouse emulator (Windows).
• philc/vimium - A browser extension that provides keyboard-based navigation and control of the web in the spirit of the Vim editor (Chromium).
• tridactyl/tridactyl - A browser extension that provides a Vim-like interface (Firefox).
• homerow - Keyboard shortcuts for every button (macOS).
• shortcat - Manipulate masterfully, minus the mouse (macOS).

Roadmap

• Grid mode (e.g., as in warpd and TPMouse.
• Search & click (e.g., as in homerow).

License

MIT License (see LICENSE for more info)

FAQ

• Why is the app not working?

  • This little toy project is still in development and has not been tested well. If you find any bugs, please report them in the issue tracker. If you have any suggestions on how to improve and/or extend the app, please feel free to open a pull request. Thank you for your understanding and support. 🙂

• Why does this use Electron?

  • Probably no good reason, 😶 but keyboard shortcuts registered via Electron's globalShortcut module are suppressed by default (i.e., key events are kept from being passed down to / processed by other apps down the line), which is a requirement for this sort of tool to work properly... Plus, Electron's simplicity and cross-platform compatibility offer too easy of a starting point to pass up. 😅 It's just a start, though. I'm sure there are better ways to do this-- hopefully, I'll find out about them soon. 🤞