HapticMouse 📳

Website · Download for Mac

HapticMouse gives any external mouse a haptic scroll wheel. Plug in a $20 USB mouse and feel a crisp Taptic-Engine detent on every scroll notch and click — borrowed live from your MacBook's trackpad. (Plus tactile typing feedback, if you want it!)

---

---

✨ Features

• ⌨️ Mechanical Keyboard Emulation (Key Weights): Types feel like physical keycaps. Specific keycodes are mapped to custom taptic vibrations:
  • Spacebar & Return: Heavy, deep physical click responses (actuationID: 2, 1.0 base intensity).
  • Delete/Backspace: Crisp, solid mechanical click feel (actuationID: 2, 0.8 base intensity).
  • Letters & Numbers: Light, crisp micro-pulse ticks (actuationID: 1, 0.9 base intensity) that simulate quiet brown switches.
• 🎛️ Modular Feature Toggles: Enable or disable haptic categories independently from the menu-bar dropdown checklist:
  • Tactile Keyboard Typing: Adds mechanical typing ticks to your internal keyboard presses.
  • Tactile Mouse Scrolling: Converts scroll wheel clicks from any USB/Bluetooth mouse into physical scroll notches.
  • Tactile Mouse Clicks: Transmits mouse click actions to the trackpad's taptic motor.
• 🎚️ Custom Vibration Strength Slider: Drag the slider (from 0.1 to 2.0 intensity) to adjust your haptic feedback strength in real time. It vibrates dynamically as you slide to let you preview your setting!
• 🔋 Battery-Saving Throttlers: Built-in rate limiters prevent continuous motor activation and reduce power draw by up to 60%:
  • Keyboard keypresses are throttled to a maximum of once every 120ms (limits feedback to ~8 keyclicks per second for smooth typing rhythm).
  • Scroll wheel ticks are throttled to once every 100ms to prevent rapid motor vibration during fast sweeps.
• 🔒 100% Privacy Protection:
  • Zero Keylogging: Events are intercepted in-memory, used to actuate the motor, and discarded instantly.
  • No Disk Write: No logs, configs, caches, or files are ever created or written to disk.
• 🖥️ Standalone Background Agent: Runs completely silently in your menu bar. No terminal windows, no Dock icon clutter, and zero console warning outputs.

---

🚀 Quick Start & Installation

Option 1: Double-Click App Installation

1. Download HapticMouse.zip and unzip it (Apple Silicon, macOS 11 or later), or compile it as in Option 2.
2. Move it to your standard Applications folder:

   mv HapticMouse.app /Applications/

3. Double-click /Applications/HapticMouse.app in Finder to launch it.
4. When prompted, follow the prompt to open System Settings and switch ON the Accessibility permission for HapticMouse. (If it doesn't prompt you, navigate to System Settings > Privacy & Security > Accessibility and toggle it manually).

First launch: the app is not notarised by Apple, so macOS blocks it once. Open System Settings → Privacy & Security, scroll down and click Open Anyway, or run xattr -dr com.apple.quarantine /Applications/HapticMouse.app.

Option 2: Build From Source

Compile the Swift code directly using macOS's built-in compiler:

# Clone the repository
git clone https://github.com/ZANYANBU/haptic-mouse.git
cd haptic-mouse

# Compile the Swift source
swiftc -O -target arm64-apple-macos11.0 HapticMouse.swift -o HapticMouseBin

# Create the macOS App Bundle structure
mkdir -p HapticMouse.app/Contents/MacOS
mv HapticMouseBin HapticMouse.app/Contents/MacOS/HapticMouse
cp Info.plist HapticMouse.app/Contents/Info.plist

# Ad-hoc sign the app bundle
codesign --force --deep --sign - HapticMouse.app

---

⚙️ Configuration & Diagnostics

Running at Login

To make HapticMouse run automatically whenever your Mac boots up:

1. Open System Settings > General > Login Items.
2. Click the + (Plus) button under the "Open at Login" list.
3. Select HapticMouse.app from /Applications.

Alternatively, from a clone of this repository, run the installer. It registers a LaunchAgent that starts HapticMouse at login and relaunches it if it quits. Use one method or the other, not both:

./install.sh            # ./install.sh --dry-run previews the LaunchAgent without installing it

The installer looks for HapticMouse.app in /Applications, then ~/Applications. To remove the LaunchAgent:

launchctl unload ~/Library/LaunchAgents/com.user.hapticmouse.plist
rm ~/Library/LaunchAgents/com.user.hapticmouse.plist

Testing Haptic Motor Directly

Verify your trackpad's haptic motor is functional directly, independent of Accessibility permission states:

swiftc -O TestHaptic.swift -o test-haptic
./test-haptic

---

📄 License

Distributed under the MIT License. See LICENSE for more details.