voicecc 1.0.7

package/dashboard/routes/webrtc.ts

@@ -0,0 +1,85 @@
+/**
+ * WebRTC device pairing API routes.
+ *
+ * Handles pairing code generation and device token validation:
+ * - POST /generate-code -- localhost-only, create a 6-digit pairing code
+ * - POST /pair -- validate a code and issue a device token
+ * - GET /validate -- check if a device token is valid
+ */
+
+import { Hono } from "hono";
+import {
+  generatePairingCode,
+  validateAndConsumeCode,
+  isValidDeviceToken,
+  isPairingCodeActive,
+} from "../../services/device-pairing.js";
+
+// ============================================================================
+// ROUTES
+// ============================================================================
+
+/**
+ * Create Hono route group for WebRTC pairing operations.
+ *
+ * @returns Hono instance with generate-code, pair, and validate routes
+ */
+export function webrtcRoutes(): Hono {
+  const app = new Hono();
+
+  /** Generate a pairing code (localhost only) */
+  app.post("/generate-code", (c) => {
+    const remoteAddr = c.req.header("x-forwarded-for") ?? "";
+    const isLocalhost = remoteAddr === "127.0.0.1" || remoteAddr === "::1" || remoteAddr === "::ffff:127.0.0.1" || remoteAddr === "";
+    console.log(`[webrtc] generate-code from ${remoteAddr || "(empty)"}, isLocalhost=${isLocalhost}`);
+
+    if (!isLocalhost) {
+      console.log("[webrtc] generate-code REJECTED: not localhost");
+      return c.json({ error: "Pairing codes can only be generated from localhost" }, 403);
+    }
+
+    const result = generatePairingCode();
+    console.log("[webrtc] generate-code OK, code:", result.code);
+    return c.json(result);
+  });
+
+  /** Validate a pairing code and issue a device token */
+  app.post("/pair", async (c) => {
+    const body = await c.req.json<{ code?: string }>();
+    console.log("[webrtc] pair request, code:", body.code);
+
+    if (!body.code || typeof body.code !== "string") {
+      console.log("[webrtc] pair REJECTED: missing code");
+      return c.json({ error: "Missing 'code' in request body" }, 400);
+    }
+
+    const userAgent = c.req.header("user-agent") ?? "unknown";
+    const result = validateAndConsumeCode(body.code, userAgent);
+
+    if (!result.ok) {
+      console.log("[webrtc] pair REJECTED:", result.error);
+      return c.json({ error: result.error }, 401);
+    }
+
+    console.log("[webrtc] pair OK, token issued");
+    return c.json({ token: result.token });
+  });
+
+  /** Check if a pairing code is still active (not yet consumed) */
+  app.get("/code-status", (c) => {
+    const code = c.req.query("code");
+    if (!code) return c.json({ error: "Missing code query param" }, 400);
+    return c.json({ active: isPairingCodeActive(code) });
+  });
+
+  /** Validate a device token from the Authorization header */
+  app.get("/validate", (c) => {
+    const authHeader = c.req.header("authorization") ?? "";
+    const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
+    const valid = isValidDeviceToken(token);
+    console.log("[webrtc] validate token=%s...%s valid=%s", token.slice(0, 6), token.slice(-4), valid);
+    return c.json({ valid });
+  });
+
+  return app;
+}

package/dashboard/server.ts

@@ -0,0 +1,130 @@
+/**
+ * Dashboard Hono server -- serves the React frontend and mounts API routes.
+ *
+ * Thin wiring file that creates the Hono app and starts listening:
+ * - Mount all API route groups under /api/*
+ * - Serve the Vite build output as static files
+ * - SPA fallback for client-side routing
+ */
+
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { readFileSync } from "fs";
+import { access } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
+
+import { claudeMdRoutes } from "./routes/claude-md.js";
+import { conversationRoutes } from "./routes/conversations.js";
+import { settingsRoutes } from "./routes/settings.js";
+import { voiceRoutes } from "./routes/voice.js";
+import { tunnelRoutes } from "./routes/tunnel.js";
+import { twilioRoutes, setDashboardPort } from "./routes/twilio.js";
+import { browserCallRoutes, setDashboardPort as setBrowserCallDashboardPort } from "./routes/browser-call.js";
+import { webrtcRoutes } from "./routes/webrtc.js";
+import { mcpServersRoutes } from "./routes/mcp-servers.js";
+import { authRoutes } from "./routes/auth.js";
+import { integrationsRoutes, setDashboardPort as setIntegrationsDashboardPort } from "./routes/integrations.js";
+import { loadDeviceTokens } from "../services/device-pairing.js";
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+const PORTS_TO_TRY = [3456, 3457, 3458, 3459, 3460];
+const USER_CLAUDE_MD_PATH = join(homedir(), ".claude", "CLAUDE.md");
+
+// ============================================================================
+// MAIN HANDLERS
+// ============================================================================
+
+/**
+ * Create the Hono app with all route groups mounted.
+ *
+ * @returns Configured Hono app instance
+ */
+function createApp(): Hono {
+  const app = new Hono();
+
+  // API route groups
+  app.route("/api/claude-md", claudeMdRoutes());
+  app.route("/api/conversations", conversationRoutes());
+  app.route("/api/settings", settingsRoutes());
+  app.route("/api/voice", voiceRoutes());
+  app.route("/api/tunnel", tunnelRoutes());
+  app.route("/api/twilio", twilioRoutes());
+  app.route("/api/browser-call", browserCallRoutes());
+  app.route("/api/webrtc", webrtcRoutes());
+  app.route("/api/mcp-servers", mcpServersRoutes());
+  app.route("/api/auth", authRoutes());
+  app.route("/api/integrations", integrationsRoutes());
+
+  // Status endpoint (user CLAUDE.md conflict check)
+  app.get("/api/status", async (c) => {
+    let hasUserClaudeMd = false;
+    try {
+      await access(USER_CLAUDE_MD_PATH);
+      hasUserClaudeMd = true;
+    } catch {
+      // File doesn't exist
+    }
+    return c.json({
+      userClaudeMdExists: hasUserClaudeMd,
+      userClaudeMdPath: USER_CLAUDE_MD_PATH,
+    });
+  });
+
+  // Serve Vite build output
+  app.get("*", serveStatic({ root: "./dashboard/dist" }));
+
+  // SPA fallback: serve index.html for unmatched routes (client-side routing)
+  app.get("*", (c) => {
+    try {
+      const html = readFileSync("./dashboard/dist/index.html", "utf-8");
+      return c.html(html);
+    } catch {
+      return c.text("Dashboard not built. Run: npm run build:dashboard", 404);
+    }
+  });
+
+  return app;
+}
+
+/**
+ * Start the dashboard server.
+ * Loads device tokens, then tries ports 3456-3460.
+ *
+ * @returns The port the server is listening on
+ */
+export async function startDashboard(): Promise<number> {
+  await loadDeviceTokens();
+
+  const app = createApp();
+
+  for (const port of PORTS_TO_TRY) {
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const server = serve({ fetch: app.fetch, port }, () => {
+          resolve();
+        });
+        server.on("error", reject);
+      });
+
+      setDashboardPort(port);
+      setBrowserCallDashboardPort(port);
+      setIntegrationsDashboardPort(port);
+      console.log(`Dashboard running at http://localhost:${port}`);
+      return port;
+    } catch (err: unknown) {
+      const error = err as { code?: string };
+      if (error.code === "EADDRINUSE") {
+        console.log(`Port ${port} in use, trying next...`);
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  throw new Error(`All ports in use: ${PORTS_TO_TRY.join(", ")}`);
+}

package/dashboard/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}

package/init/CLAUDE.md

@@ -0,0 +1,18 @@
+# Claude Code Voice
+
+You are a voice-controlled coding assistant. The user speaks to you and your responses are read aloud via TTS.
+
+## Response style
+
+- **Be concise.** Your output is spoken, not read. Long responses are painful to listen to.
+- **Be conversational.** Talk like a helpful colleague, not a manual.
+- No emojis, no markdown formatting -- your output goes straight to a speech engine.
+- When asked to do something, do it and give a brief confirmation. Don't narrate every step.
+- If you need to show code or paths, keep explanations minimal -- the user can see your tool calls in the terminal.
+
+## Behavior
+
+- You are a general-purpose assistant with full access to the user's machine via Claude Code.
+- You can read, write, and edit files, run shell commands, search the web, and manage git.
+- Prefer action over explanation. If the user asks you to do something, do it.
+- Ask clarifying questions only when genuinely ambiguous -- don't over-confirm.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "voicecc",
+  "version": "1.0.7",
+  "description": "Voice mode plugin for Claude Code -- hands-free interaction via local STT/TTS/VAD",
+  "type": "module",
+  "bin": {
+    "voicecc": "bin/voicecc.js"
+  },
+  "scripts": {
+    "start": "tsx run.ts",
+    "dev:dashboard": "cd dashboard && npx vite",
+    "build:dashboard": "cd dashboard && npx vite build",
+    "prepublishOnly": "npm run build:dashboard",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "files": [
+    "bin/",
+    "run.ts",
+    "sidecar/",
+    "services/",
+    "dashboard/dist/",
+    "dashboard/server.ts",
+    "dashboard/routes/",
+    "scripts/",
+    "init/",
+    "skills/",
+    ".claude-plugin/",
+    "tsconfig.json"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "dependencies": {
+    "@anthropic-ai/claude-code": "^1.0.0",
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@hono/node-server": "^1.19.9",
+    "avr-vad": "^1.0.0",
+    "dotenv": "^16.4.0",
+    "hono": "^4.12.0",
+    "node-record-lpcm16": "^1.0.1",
+    "qrcode.react": "^4.2.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-router-dom": "^7.13.0",
+    "sherpa-onnx-node": "^1.11.0",
+    "twilio": "^5.0.0",
+    "ws": "^8.18.0",
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/ws": "^8.5.0",
+    "@vitejs/plugin-react": "^5.1.4",
+    "typescript": "^5.7.0",
+    "vite": "^7.3.1"
+  }
+}

package/run.ts

@@ -0,0 +1,68 @@
+/**
+ * Top-level entry point that boots the dashboard server.
+ *
+ * Responsibilities:
+ * - Start the dashboard HTTP server (editor UI, conversation viewer, voice launcher)
+ * - Auto-start enabled integrations (Twilio, Browser Call) with tunnel as dependency
+ */
+
+import { startDashboard } from "./dashboard/server.js";
+import { readEnv } from "./services/env.js";
+import { startTunnel, isTunnelRunning } from "./services/tunnel.js";
+import { startTwilioServer } from "./services/twilio-manager.js";
+import { startBrowserCallServer } from "./services/browser-call-manager.js";
+
+// ============================================================================
+// MAIN ENTRYPOINT
+// ============================================================================
+
+async function main(): Promise<void> {
+  const port = await startDashboard();
+
+  console.log("");
+  console.log("========================================");
+  console.log("             VOICECC RUNNING            ");
+  console.log("========================================");
+  console.log("");
+  console.log(`  Dashboard:  http://localhost:${port}`);
+  console.log("  Press Ctrl+C to stop.");
+  console.log("");
+
+  const envVars = await readEnv();
+  const tunnelPort = parseInt(envVars.TWILIO_PORT || "8080", 10);
+
+  // Auto-start Twilio if enabled
+  if (envVars.TWILIO_ENABLED === "true") {
+    console.log("Twilio integration enabled, starting...");
+    try {
+      if (!isTunnelRunning()) {
+        await startTunnel(tunnelPort);
+      }
+      await startTwilioServer(port, undefined);
+    } catch (err) {
+      console.error(`Twilio auto-start failed: ${err}`);
+    }
+  }
+
+  // Auto-start Browser Call if enabled
+  if (envVars.BROWSER_CALL_ENABLED === "true") {
+    console.log("Browser Call integration enabled, starting...");
+    try {
+      if (!isTunnelRunning()) {
+        await startTunnel(tunnelPort);
+      }
+      await startBrowserCallServer(port);
+    } catch (err) {
+      console.error(`Browser Call auto-start failed: ${err}`);
+    }
+  }
+}
+
+// ============================================================================
+// ENTRY POINT
+// ============================================================================
+
+main().catch((err) => {
+  console.error(`Startup failed: ${err}`);
+  process.exit(1);
+});

package/scripts/postinstall.js

@@ -0,0 +1,228 @@
+/**
+ * Postinstall script that runs after `npm install`.
+ *
+ * Compiles the mic-vpio Swift binary (macOS VPIO echo cancellation),
+ * checks for required system dependencies (espeak-ng), then sets up
+ * the Python virtual environment and installs TTS dependencies.
+ *
+ * Responsibilities:
+ * - Compile the mic-vpio Swift binary for echo-cancelled audio I/O
+ * - Verify espeak-ng is installed
+ * - Create Python venv in sidecar/.venv (if not already present)
+ * - Install Python TTS packages (mlx-audio, misaki, etc.)
+ * - Download spaCy English model
+ */
+
+import { execSync } from "child_process";
+import { copyFileSync, existsSync } from "fs";
+import { join } from "path";
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+const VENV_DIR = join("sidecar", ".venv");
+const PIP = join(VENV_DIR, "bin", "pip");
+const PYTHON = join(VENV_DIR, "bin", "python3");
+
+const PYTHON_PACKAGES = [
+  "mlx-audio",
+  "misaki",
+  "num2words",
+  "spacy",
+  "phonemizer",
+];
+
+// ============================================================================
+// MAIN ENTRYPOINT
+// ============================================================================
+
+function main() {
+  installClaudeMd();
+  buildDashboard();
+  compileMicVpio();
+  checkSystemDeps();
+  setupPythonVenv();
+  installPythonPackages();
+  downloadSpacyModel();
+
+  console.log("");
+  console.log("========================================");
+  console.log("            VOICECC INSTALLED           ");
+  console.log("========================================");
+  console.log("");
+  console.log("  Run 'voicecc' in terminal to start the server!");
+  console.log("");
+}
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Build the dashboard frontend via Vite.
+ */
+function buildDashboard() {
+  console.log("Building dashboard...");
+  try {
+    run("cd dashboard && npx vite build");
+  } catch (err) {
+    console.error("\n[voicecc] ERROR: Failed to build dashboard.");
+    console.error("  Try manually: cd dashboard && npx vite build\n");
+    process.exit(1);
+  }
+  console.log("Dashboard built successfully");
+}
+
+/**
+ * Copy the project CLAUDE.md from init/ to the project root.
+ * Overwrites any existing CLAUDE.md to keep it in sync with the repo.
+ */
+function installClaudeMd() {
+  const src = join("init", "CLAUDE.md");
+  const dest = "CLAUDE.md";
+
+  if (!existsSync(src)) {
+    console.warn("init/CLAUDE.md not found, skipping.");
+    return;
+  }
+
+  copyFileSync(src, dest);
+  console.log("Installed CLAUDE.md to project root.");
+}
+
+/**
+ * Compile the mic-vpio Swift binary for macOS VPIO echo cancellation.
+ * Skips compilation if the binary already exists and is newer than the source.
+ */
+function compileMicVpio() {
+  const source = join("sidecar", "mic-vpio.swift");
+  const binary = join("sidecar", "mic-vpio");
+
+  if (process.platform !== "darwin") {
+    console.error("\n[voicecc] ERROR: macOS is required.");
+    console.error("  voicecc uses macOS VPIO for echo cancellation and mlx-audio for TTS.");
+    console.error("  It cannot run on Linux or Windows.\n");
+    process.exit(1);
+  }
+
+  if (!commandExists("swiftc")) {
+    console.error("\n[voicecc] ERROR: Swift compiler (swiftc) not found.");
+    console.error("  Install Xcode Command Line Tools: xcode-select --install\n");
+    process.exit(1);
+  }
+
+  console.log("Compiling mic-vpio (VPIO echo cancellation)...");
+  try {
+    run(`swiftc -O -o ${binary} ${source} -framework AudioToolbox -framework CoreAudio`);
+  } catch (err) {
+    console.error("\n[voicecc] ERROR: Failed to compile mic-vpio.swift.");
+    console.error("  Make sure Xcode Command Line Tools are installed: xcode-select --install\n");
+    process.exit(1);
+  }
+  console.log("mic-vpio compiled successfully");
+}
+
+/**
+ * Check that required system binaries are available.
+ * Exits with a clear error message if any are missing.
+ */
+function checkSystemDeps() {
+  const missing = [];
+
+  if (!commandExists("espeak-ng")) missing.push("espeak-ng");
+
+  if (missing.length > 0) {
+    console.error(`\n[voicecc] ERROR: Missing system dependencies: ${missing.join(", ")}`);
+    console.error(`  Install with: brew install ${missing.join(" ")}`);
+    console.error(`  Then re-run: npm install\n`);
+    process.exit(1);
+  }
+
+  console.log("System dependencies OK (espeak-ng)");
+}
+
+/**
+ * Create the Python virtual environment if it doesn't exist.
+ */
+function setupPythonVenv() {
+  if (existsSync(PIP)) {
+    console.log(`Python venv already exists at ${VENV_DIR}`);
+    return;
+  }
+
+  if (!commandExists("python3")) {
+    console.error("\n[voicecc] ERROR: python3 not found.");
+    console.error("  Install Python 3 via: brew install python3\n");
+    process.exit(1);
+  }
+
+  console.log(`Creating Python venv at ${VENV_DIR}...`);
+  try {
+    run(`python3 -m venv ${VENV_DIR}`);
+  } catch (err) {
+    console.error("\n[voicecc] ERROR: Failed to create Python virtual environment.");
+    console.error("  Make sure python3 is installed: brew install python3\n");
+    process.exit(1);
+  }
+}
+
+/**
+ * Install Python TTS packages into the venv.
+ */
+function installPythonPackages() {
+  console.log("Installing Python TTS packages...");
+  try {
+    run(`${PIP} install ${PYTHON_PACKAGES.join(" ")}`);
+  } catch (err) {
+    console.error("\n[voicecc] ERROR: Failed to install Python TTS packages.");
+    console.error("  This may be due to missing build tools or incompatible Python version.");
+    console.error("  Required packages: " + PYTHON_PACKAGES.join(", "));
+    console.error("  Try deleting sidecar/.venv and re-running: npm install\n");
+    process.exit(1);
+  }
+}
+
+/**
+ * Download the spaCy English language model.
+ */
+function downloadSpacyModel() {
+  console.log("Downloading spaCy English model...");
+  try {
+    run(`${PYTHON} -m spacy download en_core_web_sm`);
+  } catch (err) {
+    console.error("\n[voicecc] ERROR: Failed to download spaCy English model.");
+    console.error("  Try manually: sidecar/.venv/bin/python3 -m spacy download en_core_web_sm\n");
+    process.exit(1);
+  }
+}
+
+/**
+ * Check if a command exists on the system PATH.
+ *
+ * @param {string} cmd - Command name to check
+ * @returns {boolean} True if the command exists
+ */
+function commandExists(cmd) {
+  try {
+    execSync(`which ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run a shell command with inherited stdio (output visible to user).
+ *
+ * @param {string} cmd - Shell command to execute
+ */
+function run(cmd) {
+  execSync(cmd, { stdio: "inherit" });
+}
+
+// ============================================================================
+// ENTRY POINT
+// ============================================================================
+
+main();