ElPerro

ElPerro is a two-app system: a native macOS menu bar app that runs a WebSocket server, and a Flutter iOS/iPadOS app that connects to it over WiFi (or remotely via Cloudflare Tunnel) to execute actions on your Mac in under 100 ms.

Platforms

• macOS — Native menu bar app, Swift/SwiftUI + AppKit. Universal binary (arm64 + x86_64). Code-signed and notarized. Auto-updates via Sparkle with EdDSA signing.
• iOS/iPadOS — Flutter app. QR code pairing to establish the WebSocket connection.
• Web UI — HTML/CSS/JS served directly from the WebSocket server; open in any browser on the same network.

Action Types

8 action types per button: AppleScript, Shell commands, macOS Shortcuts, keyboard shortcuts, Chrome tab navigation (AppleScript-driven), VS Code commands, multi-action sequences (up to 10 chained actions), and keystroke simulation via CGEventTap.

AI Integration

Claude API generates button actions from natural language: describe what you want ("open my standup Notion page"), and Claude returns a JSON action with name, SF Symbol icon, hex color, and the most efficient execution method (keyboard shortcut preferred over AppleScript for speed). Includes an embedded database of 30+ app shortcut tables.

Engineering Highlights

• Swift-NIO actor-based WebSocket server — Non-blocking async I/O with EventLoopGroup handles multiple concurrent clients (phone + browser simultaneously). All communication is real-time with <100 ms latency.
• Cloudflare Tunnel remote access — Zero-trust remote control without port forwarding. The Mac app manages the cloudflared binary, generates time-expiring Base64 tokens for authenticated WebSocket connections, and tears down the tunnel on exit.
• Keyboard event recording — CGEventTap captures keyboard/mouse sequences and converts them to replayable action macros without accessibility permission prompts beyond initial setup.
• Supabase cloud sync — Profile grids sync across devices with Row Level Security. PostgreSQL trigger auto-creates a default profile on user signup.
• Embedded UI from WebSocket server — No CDN, no external dependency. The macOS app serves the entire web UI (drag-and-drop grid editor, profile manager) as static HTML/JS directly from the NIO server.

Deployment

DMG installer distributed directly. macOS code-signed + notarized via Apple notarytool. Sparkle EdDSA-signed appcast for over-the-air updates. Vercel for the marketing website. Supabase for cloud data.