CLI SPECIFICATION v0.1.0

VoiceFi Developer & CLI Hub

The canonical guide for installing, configuring, and operating VoiceFi on macOS, and connecting autonomous AI agent loops to the on-device ambient voice bus.

1-Minute Quickstart

Install the vifi binary and launch the local ambient voice daemon:

Terminal — Universal Install & Boot 
# 1. Install VoiceFi universal binary
curl -fsSL https://vifi.sh | sh

# 2. Auto-wire hooks into Antigravity & Cursor
vifi setup

# 3. Boot ambient daemon & status bar
vifi start --daemon

Installation Methods

Option A: Curl Script

Instant installation into ~/.local/bin/vifi with automatic PATH detection.

curl -fsSL https://vifi.sh | sh
Option B: Homebrew

Install via macOS official package formula with automated updates.

brew install vifi
Option C: Python / UV

Install directly into your Python environment with Metal CoreML support.

uv pip install -e .

Architecture & IPC Audio Bus

VoiceFi operates as an on-device ambient loopback daemon. It bridges physical CoreAudio microphones, Apple Silicon neural Whisper inference, and multi-provider text-to-speech pipelines directly to autonomous agent runtimes via high-speed Unix Domain Sockets and WebSockets at localhost:8765.

Local Loopback Topology (RFC-001) 100% On-Device • Zero Cloud Telemetry 
┌─────────────────────────────────────────────────────────────────────────┐
│                    Autonomous Agent Runtime                             │
│         (Google Antigravity · Claude Code · Cursor · VS Code)           │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ (JSON-RPC 2.0 / WebSocket & IPC)
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│               VoiceFi Ambient Daemon (localhost:8765)                   │
├────────────────────────────────────┬────────────────────────────────────┤
│  ⚡ Turn-Completion Stop-Hooks     │  🎙️ Energy Voice Activity (VAD)     │
│  🧠 Neural Faster-Whisper (Metal)  │  🔊 Multi-Provider TTS (Edge/Say)  │
│  🖥️ macOS Status Bar Tray & Hotkey │  📝 Voice Memo Buffer Synthesizer  │
└────────────────────────────────────┴────────────────────────────────────┘

Core CLI Commands

vifi start [OPTIONS]

Daemon Boot

Starts the background VoiceFi audio bus listener, WebSocket server on localhost:8765, and the native macOS Menu Bar tray controller.

--daemon, -d: Run in background decoupled from active terminal
--port <INT>: Audio bus port (Default: 8765)
--tray / --no-tray: Enable/disable macOS status bar tray icon (Default: true)
--verbose, -v: Enable detailed IPC debug logs

vifi setup [OPTIONS]

Agent Hook Integration

Discovers installed IDEs and agent configurations on your Mac and connects them to VoiceFi. Injects turn-completion stop-hooks into ~/.gemini/config/hooks.json and Claude Code settings.

vifi listen [OPTIONS]

One-Shot Dictation

Triggers instant high-speed Whisper dictation. Listens for speech, transcribes locally in 120ms, and types the result directly into the active frontmost macOS application.

vifi voice <SUBCOMMAND>

Persona Management

Manage acoustic personas, audition voices, configure speech rate, and map agent roles.

vifi voice list Print all available neural voice models
vifi voice set <role> <persona> Assign persona to role (e.g. planner Christopher)
vifi voice audition Interactive terminal acoustic audition prompt

vifi memo <SUBCOMMAND>

Voice Memo Buffer

Capture 2–5 minute pacing thoughts and synthesize them into structured implementation plans, Mermaid architecture diagrams, and PR verification checklists.

vifi memo record Start capturing microphone audio buffer
vifi memo synth <file.wav> Deconstruct voice memo into PR checklist artifact
vifi memo list List captured memos in ~/.voicefi/memos/

vifi status & vifi tray

System Diagnostics & Status Bar

Check daemon process health, active IPC sockets, latency diagnostics, and launch the native macOS Menu Bar tray companion.

vifi status Display daemon uptime, audio device IDs, and active port
vifi tray Launch lightweight macOS menu bar status indicator & quick-toggle
vifi info Print detailed system audio hardware & ML model parameters

vifi config

Configuration Schema

Configuration is persisted in ~/.voicefi/config.yaml. Modify models, TTS providers, voice personas, and energy VAD thresholds: 

version: 1
tts:
  provider: "edge_tts" # "edge_tts" | "mac_say" | "elevenlabs"
  voice: "en-US-ChristopherNeural"
  rate: 200

stt:
  provider: "whisper_local" # "whisper_local" | "groq" | "apple_speech"
  model_size: "base.en"     # "tiny.en" | "base.en" | "small.en"

vad:
  mode: "hybrid"            # "hybrid" | "ptt" | "auto"
  silence_duration: 1.2     # Silence duration (seconds) to close mic
  energy_threshold: 0.003   # Mic sensitivity threshold

Agent & IDE Integration

Google Antigravity Hook Configuration

To trigger acoustic turn announcements automatically when Antigravity finishes a task, verify your ~/.gemini/config/hooks.json contains: 

{
  "post_turn_hooks": [
    {
      "name": "voicefi_ambient_notify",
      "command": "vifi hook turn-completed --summary \"$TURN_SUMMARY\""
    }
  ]
}

Claude Code Integration

Connect VoiceFi to Claude Code CLI by running vifi setup or adding a custom notification hook: 

# Pipe Claude Code notifications into VoiceFi
claude --on-complete "vifi speak 'Claude task complete!'"

Cursor & VS Code Integration

VoiceFi operates globally across macOS. Press Control + T inside any Cursor or VS Code split-pane, terminal, or AI prompt bar to dictate immediately with 100% on-device Whisper neural accuracy.

✓
Copied to clipboard!