AutoPad

AutoPad is a lightweight native macOS menu-bar app for triggering actions from short Option-held tap rhythms and drawn pointer gestures.

Current app behavior

• Menu-bar resident, background-first macOS app.
• Global trigger capture through a Quartz session event tap.
• Two supported trigger types:
  • Tap Beat: Option + tap/click rhythms
  • Drawn Gesture: Option + press-drag-release pointer paths
• App-aware trigger scoping:
  • Anywhere
  • This app only
• Action types:
  • paste text
  • open apps or URLs
  • trigger keyboard shortcuts
  • run shell scripts
  • run elevated scripts through macOS authentication
  • simple macros

What is implemented now

• Native AppKit + SwiftUI app with:
  • menu-bar menu
  • main library window
  • floating capture window
• Global beat capture with timing tolerance and prefix-aware matching.
• Global drawn-gesture capture using the pointer path from press to release.
• Click suppression while a trigger is being captured so the frontmost app does not receive those input events.
• Focused-app context tracking through NSWorkspace.
• Saved-trigger library with:
  • search
  • edit
  • delete
  • duplicate-name visibility
  • beat inspector
  • gesture preview
• Capture flow improvements:
  • real app picker for launch targets
  • shortcut recorder
  • script editor with shell selection, working directory, and admin mode
• Stable local signing setup in script/build_and_run.sh so TCC identity stays consistent across rebuilds.

Permissions

AutoPad currently relies on two macOS privacy permissions:

• Input Monitoring Required for global trigger capture through the event tap.
• Accessibility Required for posting synthetic keyboard events used by paste-text and keyboard-shortcut actions.

After granting either permission, AutoPad should be relaunched once so the running process picks up the new state cleanly.

Architecture

Input capture

• GestureEngine Owns the Quartz event tap and the live matcher.
• EventTapBridge Intercepts:
  • left mouse down
  • left mouse drag
  • left mouse up
  • modifier flag changes
• Beat matching:
  • timing-tolerant
  • waits when a shorter beat is also the prefix of a longer saved beat
• Gesture matching:
  • normalizes path shape
  • trims startup/end noise
  • smooths points
  • compares overall shape and direction with human-friendly tolerance

Context layer

• AppContextMonitor Tracks the frontmost app and last external app for action targeting.

Execution layer

• ActionRunner Dispatches saved actions.
• Paste-text and shortcut actions target the last non-AutoPad app when the action is launched from AutoPad itself.
• Script actions support:
  • zsh
  • bash
  • sh
  • optional working directory
  • optional administrator privileges via osascript

Persistence

• Trigger library is stored as JSON in Application Support.
• Current data model supports beats, gestures, actions, app scoping, and enable/disable state.

Important constraints

• Raw background multitouch trackpad data is not available through the public macOS APIs this app is using.
• So the supported “gesture” model is pointer-path based, not raw finger-shape or pressure-sensitive multitouch capture.
• Force/pressure classification is currently not reliable enough to expose as a real matching dimension.
• Very similar gestures can still collide if their overall path shape is too close; this is a tolerance problem, not a capture-permission problem.

Next useful improvements

1. Add visible live match diagnostics such as captured, waiting, matched, and no match.
2. Add per-gesture sensitivity control such as Precise, Normal, and Loose.
3. Add import/export for trigger libraries.
4. Add richer app-specific action packs on top of the stable beat/gesture engine.