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 voice & IPC bus.

1-Minute Quickstart

Install the vifi binary and launch the local hands-free voice server:

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 VoiceFi background server & status bar
$ vifi start

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 (macOS)

Official Homebrew tap formula with automated updates and binary symlinks.

brew install atxatlarge-code/tap/vifi
Option C: Python / UV

Install directly into your Python environment with Metal CoreML support.

uv pip install git+https://github.com/atxatlarge-code/voicefi.git

Architecture & IPC Audio Bus

VoiceFi operates as an on-device ambient loopback server. 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:5141.

Local Loopback Topology (VFP-1) 100% On-Device • Zero Cloud Telemetry 
┌─────────────────────────────────────────────────────────────────────────┐
│                    Autonomous Agent Runtime                             │
│         (Google Antigravity · Claude Code · Cursor · VS Code)           │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ (JSON-RPC 2.0 / WebSocket & IPC)
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│               VoiceFi Ambient Server (localhost:5141)                   │
├────────────────────────────────────┬────────────────────────────────────┤
│  ⚡ 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]

Server Boot

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

--daemon, -d: Run in background decoupled from active terminal
--port <INT>: Audio bus port (Default: 5141)
--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 AI agent systems on your Mac and connects them to VoiceFi. Injects turn-completion stop-hooks into ~/.gemini/config/hooks.json (Antigravity) and ~/.claude/settings.json (Claude Code).

vifi pause / vifi resume

Kill Switch

Instantly pauses or resumes all VoiceFi agent speech hooks and microphone capture globally without editing configuration files.

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

VoiceFi connects natively to Claude Code via lifecycle Stop hooks in ~/.claude/settings.json. Claude Code speaks turn completions aloud using the Guy neural voice persona, and automatically captures your spoken reply: 

# 1. Automatically configure Claude Code hook
vifi setup --claude

# 2. Registered hook in ~/.claude/settings.json:
{
  "hooks": {
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "voicefi hook --agent claude",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

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.

Model Context Protocol (MCP) & WebMCP Layer W3C DRAFT + STDIO

VoiceFi provides native support for both Stdio JSON-RPC 2.0 MCP (for CLI agents like Antigravity, Claude Code, and Cursor) and WebMCP (navigator.modelContext) for in-browser AI assistants.

1. CLI Stdio MCP Server (Antigravity / Claude Code)
# Start the native stdio JSON-RPC MCP server
vifi mcp

# Exposed agent tools:
• voicefi_speak: Speak text aloud with live HUD animation
• voicefi_listen: Record user speech with VAD & return STT transcript
• voicefi_stop: Immediately halt active audio playback
• voicefi_status: Audio devices, active personas, & daemon state
• voicefi_set_voice: Configure voice persona for a specific subagent
• voicefi_ping_voice: Silent TTFB latency test
• voicefi_send: Inter-agent task dispatch envelope (Antigravity ↔ Claude)
• voicefi_sfx: Play comedic sound effects & punchlines
2. In-Browser WebMCP (navigator.modelContext)

On voicefi.org, AI agents can discover and invoke tools directly in the browser tab via the W3C WebML standard or the /.well-known/webmcp.json manifest: 

// Discover and invoke WebMCP tools in the page
const tools = navigator.modelContext.getTools();
// [
//   { name: "voicefi_audition_voice", description: "Audition neural voice in 3D carousel" },
//   { name: "voicefi_get_docs", description: "Query CLI reference and guides" },
//   { name: "voicefi_generate_install_command", description: "Generate custom 1-line installer" },
//   { name: "voicefi_ping_voice", description: "Measure TTFB latency for Edge TTS" },
//   { name: "voicefi_stop_audio", description: "Halt audio playback" }
// ]

await navigator.modelContext.invokeTool("voicefi_audition_voice", { 
  voice: "viv", 
  sampleText: "Testing WebMCP in-tab execution!" 
});
✓
Copied to clipboard!