mousey

Remaps extra mouse buttons to keyboard shortcuts on macOS. Runs as a LaunchAgent.

No fluff, only the essentials. The code is kept minimal so that you can audit what it does.

Install

Homebrew (recommended)

brew tap pokstad/mousechords https://github.com/pokstad/mousechords
brew install --HEAD pokstad/mousechords/mousechords
brew services start pokstad/mousechords/mousechords

Copy the starter config if this is a fresh install:

cp $(brew --prefix)/etc/mousey.json.example ~/.mousey.json

Then grant Accessibility permission to the installed binary in System Settings → Privacy & Security → Accessibility. The path is printed by brew info mousechords under Caveats.

brew services stop/restart manage the LaunchAgent. brew upgrade --fetch-HEAD mousechords pulls and rebuilds from the latest commit.

Manual

bash install.sh

Then grant Accessibility permission to /usr/local/bin/mousechords in System Settings → Privacy & Security → Accessibility.

Configure

Edit ~/.mousey.json:

{
  "mappings": [
    { "button": 3, "key": "]", "modifiers": ["cmd"] },
    { "button": 4, "key": "[", "modifiers": ["cmd"] }
  ]
}

key accepts a key name (a–z, 0–9, [, ], left, right, up, down, space, return, escape, tab, f1–f12, etc.) or a raw virtual keycode as a string.

modifiers accepts cmd, shift, alt, ctrl. Omit for no modifiers.

Chords

A chord fires when you hold one button and press another. This lets a single button act as a modifier, multiplying the number of shortcuts your mouse can perform.

{
  "mappings": [
    { "button": 3, "key": "]", "modifiers": ["cmd"] },
    { "button": 4, "key": "[", "modifiers": ["cmd"] }
  ],
  "chords": [
    { "hold": 6, "press": 0, "key": "left",  "modifiers": ["cmd", "shift"] },
    { "hold": 6, "press": 1, "key": "right", "modifiers": ["cmd", "shift"] }
  ]
}

In this example, holding button 6 and clicking left (button 0) or right (button 1) sends cmd+shift+left / cmd+shift+right — useful for moving a window to the left or right half of the screen with a window manager.

Each chord entry has:

• hold — the button to hold (acts as the modifier; swallowed, never triggers a click)
• press — the button to press while hold is held
• key / modifiers — the keyboard shortcut to emit

A button used as hold cannot also appear as button in mappings. The same hold button can back any number of press bindings.

Restart the agent after editing:

# Homebrew install
brew services restart pokstad/mousechords/mousechords

# Manual install
launchctl kickstart -k gui/$UID/com.pokstad.mousechords

Troubleshooting

View logs to diagnose issues:

tail -f /tmp/mousechords.out.log /tmp/mousechords.err.log

Finding button numbers

Monitor mode identifies which mouse button you are pressing to help you write your configuration:

mousechords monitor

Prints the button number for each click.

NOTE: requires input monitoring permissions for the Terminal application (or whichever term you use) in System Settings → Privacy & Security → Input Monitoring.