joystick

Overview

Joystick is a lightweight background service that listens for specific key "chords" (a sequence of keys) and executes shell commands in response. It is designed to let you trigger scripts, launch applications, or control your system from anywhere, regardless of which application is in focus.

Installation

Install directly via Go:

go install github.com/phillip-england/joystick@latest

Or clone and build from source:

git clone https://github.com/phillip-england/joystick.git
cd joystick
go build -o joystick main.go

Configuration

Joystick uses a simple text-based configuration file. When you run it for the first time, it creates a default config at:

• macOS/Linux: ~/.config/joystick/keys.conf
• Windows: %APPDATA%\joystick\keys.conf

Config Syntax

The configuration file defines a Leader Key followed by mappings. Mappings consist of a trigger key and the shell command to execute.

# Define the leader key (must be wrapped in quotes if it's a special char)
LEADER: ';

# Trigger: Leader + g
g:
  echo "Hello from Joystick"

# Trigger: Leader + 1
1:
  open -a "Google Chrome"

# Trigger: Leader + t (Multi-line commands are supported)
t:
  cd ~/src/project;
  code .

Leader Key

The Leader Key acts as a safety mechanism. Joystick only listens for commands immediately after the leader key is pressed. The default is ; (semicolon), but you can change it to any key.

When a valid trigger sequence is detected, Joystick automatically sends "Backspace" keystrokes to erase the trigger characters from your current input field before executing the command.

CLI Commands