The companion 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 · all free
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
4 · black
yolo (allow all)
ctrl+shift+F16
3 · red
reject / no
ctrl+shift+F14
2 · yellow
make it better
ctrl+shift+F15
1 · green
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:
| 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