~/download
[sudo]
The cross-platform companion app for your sudo macro pad. Approve, reject, and control AI agents with a physical button press.
macOS · Windows · Linux
> download
> install from source
$ git clone https://github.com/ibrue/sudo-app
$ cd sudo-app
$ ./install.sh
> button modes
simple mode
Assign preset system shortcuts to each button.
- ● screenshot, copy, paste, undo
- ● save, lock screen, media controls
- ● custom keyboard shortcuts
complex mode
AI agent button-finding with customizable search terms.
- ● accessibility tree detection
- ● OCR vision fallback
- ● custom button labels per app
> default button map
| button | hotkey | action |
|---|---|---|
| 1 | Ctrl+Shift+F13 | Approve / Yes |
| 2 | Ctrl+Shift+F14 | Reject / No |
| 3 | Ctrl+Shift+F15 | Continue |
| 4 | Ctrl+Shift+F16 | Stop |
all hotkeys are fully configurable in the app settings
> detection stack
| feature | macOS | Windows | Linux |
|---|---|---|---|
| system tray | MenuBarExtra | NotifyIcon | AppIndicator3 |
| hotkeys | CGEvent tap | RegisterHotKey | pynput |
| button finding | AXUIElement | UI Automation | AT-SPI2 |
| OCR fallback | Apple Vision | Windows.Media.Ocr | Tesseract |
| execution | AXPress | InvokePattern | AT-SPI / xdotool |
> firmware (QMK / VIA / Vial)
The sudo macro pad runs QMK firmware on an RP2040 chip. Three keymap options are available:
| keymap | features | reconfigure |
|---|---|---|
| default | Ctrl+Shift+F13–F16 | reflash required |
| VIA | live remapping via usevia.app | no reflash needed |
| Vial | auto-detection, no draft definition | no reflash needed |
> supported apps
native apps
Claude for Desktop
ChatGPT
web apps
claude.ai · chatgpt.com · grok.com
Safari (macOS) · Chrome · Firefox · Brave · Edge · Opera · Chromium
> requirements
macOS
- macOS 13 Ventura+
- Accessibility permission
- Screen Recording (OCR)
Windows
- Windows 10+
- .NET 8 Runtime
- Run as Administrator (optional)
Linux
- X11 or Wayland
- Python 3.8+, GTK3
- Tesseract OCR (optional)
[sudo] is open source hardware + softwareGitHub →