voicecc 1.0.10 → 1.1.0

package/README.md

@@ -1,41 +1,58 @@
 # Voice CC
 
-A Claude Code plugin for hands-free voice interaction with local speech-to-text, text-to-speech, and voice activity detection.
+A Claude Code plugin for hands-free voice interaction with ElevenLabs speech-to-text, text-to-speech, and voice activity detection.
+
+## Project Structure
+
+```
+server/             Backend: voice pipeline + orchestration services
+  voice/            Real-time audio: STT, TTS, VAD, session management
+  services/         Orchestration: tunnel, Twilio, browser calls, agents
+  index.ts          Entry point (boots dashboard + auto-starts integrations)
+dashboard/          Web UI (Vite + React) + API routes (Hono)
+lander/             Static landing page
+init/               Default prompt templates for new agents
+bin/                CLI entry point (voicecc command)
+```
 
 ## Installation
 
 ### Prerequisites
 
-- macOS with Apple Silicon (M1/M2/M3/M4)
+- macOS or Linux
 - Node.js 18+
-- Python 3.10+
-- Homebrew
+- An ElevenLabs API key
 
 ### Install
 
 ```bash
-# 1. Install system dependencies
-xcode-select --install
-brew install espeak-ng cloudflared
-
-# 2. Install Voice CC
+# 1. Install Voice CC
 npm install -g voicecc
 
-# 3. Start the dashboard
+# 2. Start the dashboard
 voicecc
 ```
 
-The postinstall script handles sox, the Whisper model, Python venv, and TTS dependencies automatically.
+## Development
 
-## How It Works
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Start the backend server
+npm start
 
-The voice loop runs locally with zero external API calls except to Claude:
+# 3. In a separate terminal, start the dashboard with hot reload
+npm run dev:dashboard
+```
+
+## How It Works
 
-1. **Mic capture**: VPIO (macOS Voice Processing IO) records 16kHz mono PCM with echo cancellation
+1. **Mic capture**: Browser captures 16kHz mono PCM via WebRTC
 2. **Voice activity detection**: Silero VAD v5 detects speech segments
-3. **Speech-to-text**: sherpa-onnx (Whisper ONNX model) transcribes audio locally
+3. **Speech-to-text**: ElevenLabs Scribe API transcribes audio
 4. **Endpointing**: VAD silence-based turn detection
 5. **Claude inference**: Transcript sent to Claude Code Agent SDK session with streaming response
 6. **Narration**: Claude's response stripped of markdown and split into sentences
-7. **Text-to-speech**: Kokoro-82M via mlx-audio on Apple Silicon GPU (~8x realtime)
-8. **Speaker playback**: Audio output through VPIO at 24kHz with echo cancellation
+7. **Text-to-speech**: ElevenLabs streaming TTS API generates audio
+8. **Speaker playback**: Audio output through browser at 24kHz

package/bin/voicecc.js

@@ -3,29 +3,136 @@
 /**
  * CLI entry point for the voicecc command.
  *
- * Checks if first-run setup is needed (compile mic-vpio, Python venv, etc.)
- * and runs it with visible output. Then spawns `tsx run.ts` for the dashboard.
+ * - On first run (no .env), launches an interactive setup wizard
+ * - Copies CLAUDE.md template on first run
+ * - Spawns the dashboard server
  */
 
 import { spawn } from "node:child_process";
+import { copyFileSync, existsSync } from "node:fs";
+import { writeFile, readFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { randomBytes } from "node:crypto";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = join(__dirname, "..");
 const TSX_BIN = join(PKG_ROOT, "node_modules", ".bin", "tsx");
+const ENV_PATH = join(PKG_ROOT, ".env");
 
-// Run setup if needed (first run or incomplete install)
 process.chdir(PKG_ROOT);
-const { needsSetup, runSetup } = await import("../scripts/postinstall.js");
 
-if (needsSetup()) {
-  console.log("[voicecc] Running first-time setup...\n");
-  runSetup();
+// ============================================================================
+// SETUP WIZARD
+// ============================================================================
+
+/**
+ * Prompt the user for a single line of input.
+ *
+ * @param rl - readline interface
+ * @param question - the prompt text
+ * @returns the user's trimmed answer
+ */
+function ask(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(answer.trim()));
+  });
+}
+
+/**
+ * Generate a cryptographically random password (24 URL-safe characters).
+ *
+ * @returns generated password string
+ */
+function generatePassword() {
+  return randomBytes(18).toString("base64url");
+}
+
+/**
+ * Run the first-run setup wizard.
+ * Prompts for ElevenLabs API key and dashboard password configuration.
+ * Writes results to .env.
+ */
+async function runSetupWizard() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log("");
+  console.log("========================================");
+  console.log("       Welcome to VoiceCC Setup!        ");
+  console.log("========================================");
+  console.log("");
+
+  // ElevenLabs API key
+  console.log("VoiceCC uses ElevenLabs for speech recognition and text-to-speech.");
+  console.log("You can get a free API key at: https://elevenlabs.io");
+  console.log("");
+  const apiKey = await ask(rl, "Paste your ElevenLabs API key (or press Enter to skip): ");
+  if (!apiKey) {
+    console.log("Skipped. You can add it later from the dashboard.");
+  }
+
+  // Dashboard password
+  console.log("");
+  console.log("Would you like to protect your dashboard with a password?");
+  console.log("Anyone with access to the dashboard can control your voice agents.");
+  console.log("");
+  console.log("  1) Yes, generate a password for me (recommended)");
+  console.log("  2) No, leave it open (not recommended)");
+  console.log("");
+  const passwordChoice = await ask(rl, "Choose [1/2]: ");
+
+  let password = "";
+  if (passwordChoice === "2") {
+    console.log("");
+    console.log("WARNING: Your dashboard will be open to anyone who can reach it.");
+  } else {
+    password = generatePassword();
+    console.log("");
+    console.log("========================================");
+    console.log("  Your dashboard login (save this!)     ");
+    console.log("========================================");
+    console.log("");
+    console.log(`  Username: admin`);
+    console.log(`  Password: ${password}`);
+    console.log("");
+    console.log("  \x1b[31mThis will NOT be shown again.\x1b[0m");
+    console.log("  Your browser will ask for these when");
+    console.log("  you open the dashboard.");
+    console.log("========================================");
+    console.log("");
+    await ask(rl, "Have you saved the password? Press Enter to continue. ");
+  }
+
+  rl.close();
+
+  // Build .env content
+  const lines = [];
+  if (apiKey) lines.push(`ELEVENLABS_API_KEY=${apiKey}`);
+  if (password) lines.push(`DASHBOARD_PASSWORD=${password}`);
+  await writeFile(ENV_PATH, lines.join("\n") + "\n", "utf-8");
+
+  console.log("All done! Starting VoiceCC...");
+  console.log("");
+}
+
+// ============================================================================
+// MAIN ENTRYPOINT
+// ============================================================================
+
+// Copy CLAUDE.md template if available
+const claudeMdSrc = join("init", "CLAUDE.md");
+if (existsSync(claudeMdSrc)) {
+  copyFileSync(claudeMdSrc, "CLAUDE.md");
+}
+
+// Run setup wizard on first run (no .env file)
+if (!existsSync(ENV_PATH)) {
+  await runSetupWizard();
 }
 
 // Start the dashboard
-const child = spawn(TSX_BIN, ["run.ts"], {
+const child = spawn(TSX_BIN, ["server/index.ts"], {
   cwd: PKG_ROOT,
   stdio: "inherit",
 });