~/app
[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
> get the app
> install from source
$ git clone https://github.com/ibrue/sudo-app
$ cd sudo-app
$ ./install.sh
> button modes
ai search mode
automatically find and press buttons in AI apps using a 3-strategy pipeline.
- ● accessibility tree detection
- ● vision OCR fallback
- ● keyboard fallback
- ● custom button labels per app
shortcuts & macros
assign keyboard shortcuts, media keys, or macro sequences to each button.
- ● keyboard shortcuts & media keys
- ● macro sequences with delays
- ● per-app profiles with auto-switching
- ● auto-approve rules engine
> default button map
yolo (allow all)
ctrl+shift+F16
reject / no
ctrl+shift+F14
make it better
ctrl+shift+F15
approve / yes
ctrl+shift+F13
all buttons are fully configurable with quick presets in the app
> quick presets
| preset | description |
|---|---|
| ai agent | approve / reject / make it better / yolo for AI permission prompts |
| plan mode | plan-oriented actions for AI coding agents |
| claude code | optimized for claude code terminal workflows |
| system shortcuts | screenshot, copy, paste, undo, save, lock screen |
| media controls | play/pause, next, previous, volume |
| web browsing | tab navigation, back, forward, refresh |
| discord soundboard | trigger soundboard clips |
> developer tools
local API
HTTP API on port 7483 for scripting and automation.
- ● simulate button presses
- ● read/write button config
- ● webhook notifications
- ● action history
MCP server
gate AI tool use behind physical button approval.
- ● POST /mcp/request-approval
- ● blocks until button press
- ● works with any MCP client
plugin system
extend functionality with json plugin files.
- ● drop .json files in plugins dir
- ● custom actions & search terms
- ● automation rules
> 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
editors & terminals
Cursor · VS Code · Windsurf
VSCodium · VS Code Insiders
Terminal · iTerm2 · Warp
Ghostty · Kitty · Alacritty
web apps
claude.ai · chatgpt.com · grok.com
Safari · Chrome · Firefox · Brave · Edge · Arc · Opera
> 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)