Documentation & Quick Start
Follow this guide to install OpenAgent, grant macOS permissions, calibrate WhatsApp Desktop, and connect Instinct.
Prerequisites
macOS 14 (Sonoma) or macOS 15 (Sequoia) on Apple Silicon (M1-M4) or Intel.
Fast Python manager `uv` and JavaScript runtime `bun` (auto-installed if missing).
Required to provision command-line dependencies (`sox`, `ffmpeg`, `ripgrep`).
Official macOS client installed and logged in with your active Instinct chat.
Installation in 4 Steps
git clone https://github.com/GitCoder052023/OpenAgent.git cd OpenAgent
Provisions virtual environment with `uv`, installs Bun dependencies, downloads Vosk and Whisper speech models.
./install.py
Inspects your open WhatsApp client, detects Accessibility tree paths, and saves verified selectors into `.env`.
./calibrate.py --save
Starts the agent with continuous offline wake-word listener enabled:
./boot.py --voice --send-mode audio
macOS Privacy & Permissions
Open System Settings → Privacy & Security and verify permissions for your Terminal / IDE:
- Accessibility: WhatsApp UI tree inspection and native computer clicks.
- Input Monitoring: Global push-to-talk hotkey (`F8`) detection.
- Microphone: Audio recording via SoX CoreAudio driver.
- Screen Recording: Window screenshot capture (`mac_see`).
- Automation: System Events and osascript control.
Environment Variables (`.env`)
| Variable | Default | Description |
|---|---|---|
| BRIDGE_WHATSAPP_NUMBER | +16508702892 | Verified Instinct assistant phone number |
| BRIDGE_SAFE_MODE | true | Strictly fail-closed verification against chat header |
| BRIDGE_HOTKEY | f8 | Push-to-talk hotkey fallback |
| BRIDGE_SEND_MODE | audio | `audio` (AAC voice note) or `text` (Whisper STT) |
| BRIDGE_VOICE_SILENCE_SECONDS | 2.0 | Silence duration before auto-submitting speech |
| LOCOAGENT_ENABLED | true | Enable Threads and Reddit social automation |
| FIRECRAWL_API_URL | http://localhost:3002 | Self-hosted Firecrawl Docker daemon endpoint |