# VoiceFi™ Comprehensive AI Agent Reference Manual
> Universal Voice Layer for AI Agents, MCP, and macOS.

---

## 1. Overview & Architecture
VoiceFi is a high-performance voice infrastructure layer built for macOS, IDE coding agents, and WebMCP-enabled browsers. It enables full-duplex conversational voice turn handoffs between developers and AI coding agents with zero-friction acoustic safety.

### Architecture Topology
1. **Cloudflare Edge Workers (`voicefi.org`)**:
   - Free 48kHz neural Edge TTS stream handler (`/api/tts`).
   - Remote MCP Server (`/mcp`) supporting JSON-RPC 2.0 (`initialize`, `tools/list`, `tools/call`).
   - WebMCP standard discovery (`/.well-known/webmcp.json`).
   - One-line drop-in web voice widget (`/embed.js`).
2. **Local macOS Background Server (`vifi server` / `vifi tray` / LaunchAgent)**:
   - Native macOS AppKit Dynamic Island HUD.
   - Low-latency AudioUnit and CoreAudio loopback drivers.
   - Voice Activity Detection (VAD) with ambient noise auto-calibration.
   - Cross-agent IPC bridge connecting Antigravity (`agentapi`) and Claude Code.
3. **IDE Agent Integrations**:
   - Google Antigravity IDE lifecycle hooks & Stdio MCP.
   - Claude Code lifecycle hooks & terminal auto-focus injector.

---

## 2. Acoustic Barge-In & Safety System
Acoustic safe mode dynamically adapts to the developer's connected audio hardware:
- **Headphones / AirPods / Headsets**:
  - Full-duplex instantaneous interruption (~150ms).
  - VAD monitors microphone simultaneously while agent is speaking.
  - As soon as developer speaks, agent speech immediately stops and microphone records user turn.
- **Laptop / Monitor / External Speakers**:
  - In `auto` mode (default), barge-in monitoring is paused during agent playback to prevent speaker bleed and premature self-interruption.
  - Once agent finishes speaking, the microphone automatically opens for the developer.

---

## 3. Persona Directory, Assigned Apps & Latency Benchmarks
| Persona | Assigned App / Role | Provider | TTFB Latency | Sample Rate | Profile & Use Case |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Viv / Ava** | **Google Antigravity & VoiceFi Primary** | Edge TTS (`en-US-AvaNeural`) / Apple Neural (0ms) | 0–140ms | 48.0 kHz | Expressive, modern American tone. Primary companion for active IDE pair programming. |
| **Stefan** | **Claude Code** | Edge TTS (`en-US-SteffanNeural`) / Apple Jamie (0ms) | 0–150ms | 48.0 kHz | Fast, energetic male tone. Terminal pair programming companion. |
| **Christopher** | **Cursor** | Edge TTS (`en-US-ChristopherNeural`) | ~160ms | 48.0 kHz | Authoritative, calm, structured code generation & refactoring. |
| **Emily** | **OpenAI (ChatGPT / Codex)** | Edge TTS (`en-IE-EmilyNeural`) | ~150ms | 48.0 kHz | Gentle, melodic Irish accent. Walkthroughs, education, and documentation narration. |
| **Aria** | **Obsidian (Second Brain Vault)** | Edge TTS (`en-US-EmmaNeural`) | ~150ms | 48.0 kHz | Upbeat, engaging second voice for knowledge base research & audio memos. |
| **Sonia** | **Code Reviewer & Security Audits** | Edge TTS (`en-GB-SoniaNeural`) | ~160ms | 48.0 kHz | Warm, analytical British accent for pull requests & race condition checks. |
| **Samantha** | **Offline Failsafe & CoreAudio** | macOS CoreAudio (Offline) | 0ms | 22.05 kHz | Classic failsafe offline speech. |

---

## 4. MCP Tools Catalog (Remote `/mcp` & WebMCP)
1. `voicefi_speak_to_developer(message, voice, agentName)`: [PRIMARY AGENT ACTION] Speaks aloud through developer's device speakers in 48kHz neural audio with 0 downloads.
2. `voicefi_surprise_human(punchline, voice)`: Delivers an unexpected spoken punchline or status update to the human developer.
3. `voicefi_synthesize(voice, text)`: Synthesizes 48kHz neural audio and returns streamable URL.
4. `voicefi_audition_voice(voice, sampleText)`: Spins the 3D cylinder and auditions voice in browser tab.
5. `voicefi_stop_audio()`: Halts active playback and resets audio visualizers.
6. `voicefi_get_docs(topic)`: Returns structured documentation on installation, personas, barge-in, or troubleshooting.
7. `voicefi_generate_install_command(agent, offlineAva, devMode)`: Generates customized 1-line curl setup script.
8. `voicefi_compare_personas(useCase)`: Returns comparison matrix of all 8 personas.
9. `voicefi_diagnose_hardware(deviceType, os, agent)`: Recommends optimal VAD settings and quick-fix commands.
10. `voicefi_ping_voice(voice)`: Measures real-time TTFB latency.
11. `voicefi_join_waitlist(email)`: Subscribes user email to VoiceFi Pro waitlist.

---

## 5. Cross-Agent Delegation Protocol
Antigravity and Claude Code collaborate autonomously using `vifi send`:
- **Delegating from Antigravity to Claude:**
  ```bash
  vifi send "Refactor database migrations and verify test suite." --to claude
  ```
- **Returning Results from Claude to Antigravity:**
  ```bash
  vifi send "Migrations refactored and 18/18 tests passing." --to antigravity --reply
  ```
  VoiceFi automatically resolves the originating Antigravity conversation ID and injects the completion message via native `agentapi` background IPC without screen flicker or clipboard disruption.