@settinghead/voxlert 0.3.6 → 0.3.8

package/README.md

@@ -57,7 +57,7 @@ You will also want:
 
 The setup wizard auto-detects running TTS backends. If none are running yet, setup still completes, but you will only get text notifications and fallback phrases until you start one and rerun setup.
 
-> **Can't run local TTS?** Both backends require a GPU or Apple Silicon. If that's a blocker, [request early access to Pipevox](https://settinghead.github.io/pipevox-signup) — a hosted option that needs no local TTS setup.
+> **Can't run local TTS?** Both backends require a GPU or Apple Silicon. Voxlert still works without TTS — you'll get text notifications and fallback phrases. Need help? [Post in Setup help & troubleshooting](https://github.com/settinghead/voxlert/discussions/6).
 
 ### 2. Install and run setup
 
@@ -241,6 +241,22 @@ flowchart TD
 5. The chosen phrase is synthesized by the configured TTS backend.
 6. Audio is optionally post-processed, cached, then played through a serialized queue.
 
+### What does it cost?
+
+The LLM step (turning events into in-character phrases) uses a small, cheap model — not Claude. Each notification costs a fraction of a cent via OpenRouter, or **zero** if you use a local LLM. TTS and audio run entirely on your machine at zero cost. You can also skip the LLM entirely and use only fallback phrases from the voice pack (no API key needed).
+
+### Fully local mode (no cloud at all)
+
+Voxlert supports local LLM servers for the phrase generation step. Run `voxlert setup` and choose **"Local LLM (Ollama / LM Studio / llama.cpp)"**. Any OpenAI-compatible local server works:
+
+| Server | Default URL |
+|--------|------------|
+| [Ollama](https://ollama.ai) | `http://localhost:11434/v1` |
+| [LM Studio](https://lmstudio.ai) | `http://localhost:1234/v1` |
+| [llama.cpp server](https://github.com/ggerganov/llama.cpp) | `http://localhost:8080/v1` |
+
+Combined with local TTS (Qwen3-TTS), this gives you a completely offline setup — no API keys, no cloud, no cost.
+
 ## Configuration
 
 Run `voxlert config path` to find `config.json`. You can edit it directly or use `voxlert setup` and `voxlert config set`.
@@ -366,9 +382,7 @@ See [Creating Voice Packs](docs/creating-voice-packs.md) for building your own c
 
 - **Protoss Advisor** voice pack inspired by [openclaw/protoss-voice](https://playbooks.com/skills/openclaw/skills/protoss-voice)
 
-## Considering a hosted version?
-
-If the local TTS setup is a blocker, [vote or comment in this Discussion](https://github.com/settinghead/voxlert/discussions/5). A hosted API (no local Python or model required) is on the roadmap if demand is there.
+## Need help?
 
 Having trouble with setup? Post in the [Setup help & troubleshooting Discussion](https://github.com/settinghead/voxlert/discussions/6).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@settinghead/voxlert",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "LLM-generated voice notifications for Claude Code, Cursor, OpenAI Codex, and OpenClaw, spoken by game characters like the StarCraft Adjutant, Kerrigan, C&C EVA, SHODAN, and more.",
   "repository": {
     "type": "git",

package/src/cli.js

@@ -23,6 +23,13 @@ function createHelpText() {
 
 async function maybeRunSetup(command) {
   if (command.skipSetupWizard || existsSync(STATE_DIR)) return false;
+  const args = process.argv.slice(2);
+  const nonInteractive = args.includes("--yes") || args.includes("-y");
+  if (nonInteractive) {
+    const { runSetup } = await import("./setup.js");
+    await runSetup({ nonInteractive: true });
+    return true;
+  }
   console.log("Welcome to Voxlert! First time here?\n");
   const select = (await import("@inquirer/select")).default;
   const action = await select({

package/src/commands/pack-helpers.js

@@ -48,8 +48,7 @@ export async function testPipeline(text, pack) {
     console.log("TTS failed — no audio was produced.");
     console.log("Make sure your TTS server is running (see: voxlert setup).");
     console.log("");
-    console.log("Can't run local TTS? Request hosted access:");
-    console.log("  https://settinghead.github.io/pipevox-signup");
+    console.log("Need help? https://github.com/settinghead/voxlert/discussions/6");
   } else {
     console.log("Done.");
   }

package/src/commands/setup.js

@@ -3,11 +3,13 @@ export const setupCommand = {
   aliases: [],
   help: [
     "  voxlert setup               Interactive setup wizard (LLM, voice, TTS, hooks)",
+    "  voxlert setup --yes         Accept all defaults non-interactively",
   ],
   skipSetupWizard: true,
   skipUpgradeCheck: false,
-  async run() {
+  async run({ args }) {
+    const nonInteractive = args.includes("--yes") || args.includes("-y");
     const { runSetup } = await import("../setup.js");
-    await runSetup();
+    await runSetup({ nonInteractive });
   },
 };

package/src/llm.js

@@ -91,7 +91,7 @@ function generatePhraseCloud(context, config, style, llmTemperature, examples) {
     if (!provider) return resolve({ phrase: null, fallbackReason: "unknown_provider", detail: backendId });
 
     const apiKey = getApiKey(config);
-    if (!apiKey) return resolve({ phrase: null, fallbackReason: "no_api_key" });
+    if (!apiKey && !provider.local) return resolve({ phrase: null, fallbackReason: "no_api_key" });
 
     const model = getModel(config);
     const messages = [

package/src/providers.js

@@ -11,6 +11,16 @@ export const LLM_PROVIDERS = {
     authHeader: (key) => ({ Authorization: `Bearer ${key}` }),
     format: "openai",
   },
+  local: {
+    name: "Local LLM (Ollama / LM Studio / llama.cpp)",
+    description: "fully offline, no API key needed",
+    baseUrl: "http://localhost:11434/v1",
+    defaultModel: "qwen3:8b",
+    signupUrl: null,
+    authHeader: () => ({}),
+    format: "openai",
+    local: true,
+  },
   openai: {
     name: "OpenAI",
     description: "GPT-4o-mini",

package/src/setup.js

@@ -102,6 +102,28 @@ function validateApiKey(providerId, apiKey) {
   });
 }
 
+/**
+ * Quick connectivity check for a local LLM server.
+ * Tries GET /v1/models — works for Ollama, LM Studio, llama.cpp, etc.
+ */
+function validateLocalLlm(baseUrl) {
+  return new Promise((resolve) => {
+    try {
+      const url = new URL("/v1/models", baseUrl);
+      const reqFn = url.protocol === "https:" ? https.request : http.request;
+      const req = reqFn(url, { method: "GET", timeout: 3000 }, (res) => {
+        res.resume();
+        resolve({ ok: res.statusCode >= 200 && res.statusCode < 500 });
+      });
+      req.on("error", (err) => resolve({ ok: false, error: err.message }));
+      req.on("timeout", () => { req.destroy(); resolve({ ok: false, error: "timeout" }); });
+      req.end();
+    } catch (err) {
+      resolve({ ok: false, error: err.message });
+    }
+  });
+}
+
 /**
  * Fetch a URL and return the response body as a Buffer.
  * Rejects on non-2xx or network error.
@@ -179,28 +201,36 @@ function ensurePacks() {
   }
 }
 
-export async function runSetup() {
+export async function runSetup({ nonInteractive = false } = {}) {
   // Ensure config exists
   ensureConfig();
   ensurePacks();
   mkdirSync(CACHE_DIR, { recursive: true });
 
-  const config = loadConfig();
+  const rawConfig = loadConfig();
 
-  // Save partial progress on Ctrl+C so completed steps are preserved
-  const savePartial = () => {
-    try {
-      saveConfig(config);
-      console.log("");
-      printWarning("Setup interrupted — progress saved. Run 'voxlert setup' to resume.");
-      console.log("");
-    } catch {
-      // ignore write errors during exit
-    }
-  };
-  process.on("SIGINT", () => { savePartial(); process.exit(130); });
+  // Auto-persist: any property write saves to disk immediately
+  const config = new Proxy(rawConfig, {
+    set(target, prop, value) {
+      target[prop] = value;
+      try { saveConfig(target); } catch { /* ignore */ }
+      return true;
+    },
+  });
+
+  process.on("SIGINT", () => {
+    console.log("");
+    printWarning("Setup interrupted — progress saved. Run 'voxlert setup' to resume.");
+    console.log("");
+    process.exit(130);
+  });
 
   try {
+
+  if (nonInteractive) {
+    return await runNonInteractiveSetup(config);
+  }
+
   const currentBackend = config.llm_backend || "openrouter";
   const currentProvider = getProvider(currentBackend);
   const currentModel = config.llm_model || currentProvider?.defaultModel || "default";
@@ -235,79 +265,119 @@ export async function runSetup() {
   const chosenProvider = await select({
     message: "Which LLM provider would you like to use?",
     choices: providerChoices,
-    default: currentBackend !== "local" ? currentBackend : "openrouter",
+    default: currentBackend || "openrouter",
   });
 
   let apiKey = null;
 
   if (chosenProvider !== "skip") {
     config.llm_backend = chosenProvider;
+
     const provider = getProvider(chosenProvider);
 
-    // --- Step 2: API Key ---
-    console.log("");
-    printStep(2, "API Key");
-    printStatus("Get a key at:", provider.signupUrl);
-    console.log("");
+    if (provider.local) {
+      // --- Step 2: Local LLM Server ---
+      console.log("");
+      printStep(2, "Local LLM Server");
+      printStatus("Supported", "Ollama, LM Studio, llama.cpp, vLLM, LocalAI");
+      printStatus("Default ports", "Ollama :11434 · LM Studio :1234 · llama.cpp :8080");
+      console.log("");
 
-    const existingKey = config.llm_api_key ?? config.openrouter_api_key ?? "";
-    const maskedExisting = existingKey
-      ? `${existingKey.slice(0, 4)}…${existingKey.slice(-4)}`
-      : "";
-
-    apiKey = (await input({
-      message: "Paste your API key:",
-      default: existingKey || undefined,
-      transformer: (val) => {
-        if (!val) return maskedExisting || "";
-        if (val === existingKey) return maskedExisting;
-        if (val.length <= 8) return "****";
-        return val.slice(0, 4) + "…" + val.slice(-4);
-      },
-    })).trim();
+      const existingUrl = config.local_api?.base_url || provider.baseUrl;
+      const localUrl = (await input({
+        message: "Server URL:",
+        default: existingUrl,
+      })).trim();
+
+      const existingModel = config.local_api?.model || provider.defaultModel;
+      const localModel = (await input({
+        message: "Model name (must be already pulled/loaded):",
+        default: existingModel,
+      })).trim();
+
+      config.local_api = {
+        ...config.local_api,
+        base_url: localUrl,
+        model: localModel,
+      };
+      config.llm_model = localModel;
+      config.llm_api_key = null;
+      config.openrouter_api_key = null;
 
-    if (apiKey) {
-      process.stdout.write("  Validating key... ");
-      const result = await validateApiKey(chosenProvider, apiKey);
-      if (result.ok) {
-        console.log("valid!\n");
-      } else {
-        console.log(`could not validate (${result.error || "unknown error"})`);
-        const proceed = await confirm({
-          message: "Use this key anyway?",
-          default: true,
-        });
-        if (!proceed) {
-          apiKey = null;
-          printWarning("Skipped. Set it later with: voxlert config set llm_api_key <key>");
-          console.log("");
-        } else {
-          console.log("");
-        }
+      // Quick connectivity check
+      process.stdout.write("  Checking server... ");
+      const result = await validateLocalLlm(localUrl);
+      console.log(result.ok ? "connected!" : `not reachable (${result.error})`);
+      if (!result.ok) {
+        printWarning("Server not detected. Voxlert will use fallback phrases until the server is running.");
       }
+      console.log("");
+    } else {
+      // --- Step 2: API Key ---
+      console.log("");
+      printStep(2, "API Key");
+      printStatus("Get a key at:", provider.signupUrl);
+      console.log("");
+
+      const existingKey = config.llm_api_key ?? config.openrouter_api_key ?? "";
+      const maskedExisting = existingKey
+        ? `${existingKey.slice(0, 4)}…${existingKey.slice(-4)}`
+        : "";
+
+      apiKey = (await input({
+        message: "Paste your API key:",
+        default: existingKey || undefined,
+        transformer: (val) => {
+          if (!val) return maskedExisting || "";
+          if (val === existingKey) return maskedExisting;
+          if (val.length <= 8) return "****";
+          return val.slice(0, 4) + "…" + val.slice(-4);
+        },
+      })).trim();
 
       if (apiKey) {
-        config.llm_api_key = apiKey;
-        // Clear legacy field if using the new unified field
-        if (chosenProvider === "openrouter") {
-          config.openrouter_api_key = apiKey;
+        process.stdout.write("  Validating key... ");
+        const result = await validateApiKey(chosenProvider, apiKey);
+        if (result.ok) {
+          console.log("valid!\n");
+        } else {
+          console.log(`could not validate (${result.error || "unknown error"})`);
+          const proceed = await confirm({
+            message: "Use this key anyway?",
+            default: true,
+          });
+          if (!proceed) {
+            apiKey = null;
+            printWarning("Skipped. Set it later with: voxlert config set llm_api_key <key>");
+            console.log("");
+          } else {
+            console.log("");
+          }
+        }
+
+        if (apiKey) {
+          config.llm_api_key = apiKey;
+          if (chosenProvider === "openrouter") {
+            config.openrouter_api_key = apiKey;
+          }
+        } else {
+          config.llm_api_key = null;
+          config.openrouter_api_key = null;
         }
       } else {
         config.llm_api_key = null;
         config.openrouter_api_key = null;
       }
-    } else {
-      config.llm_api_key = null;
-      config.openrouter_api_key = null;
-    }
 
-    // Set default model for chosen provider
-    if (!config.llm_model && !config.openrouter_model) {
-      config.llm_model = provider.defaultModel;
+      // Set default model for chosen provider
+      if (!config.llm_model && !config.openrouter_model) {
+        config.llm_model = provider.defaultModel;
+      }
     }
   } else {
     config.llm_api_key = null;
     config.openrouter_api_key = null;
+
     console.log("");
     printWarning("Using fallback phrases from the voice pack.");
     console.log("");
@@ -384,6 +454,7 @@ export async function runSetup() {
       default: active || "random",
     });
     config.active_pack = chosenPack;
+
   } else {
     printWarning("No voice packs found. Using default.");
     console.log("");
@@ -487,10 +558,106 @@ export async function runSetup() {
     printWarning("No platforms selected. Run 'voxlert setup' again to install hooks later.");
   }
 
-  // --- Save config ---
+  // --- Summary ---
+  printSetupSummary(config, "skip", []);
+
+  } catch (err) {
+    // Inquirer throws on Ctrl+C (ExitPromptError); progress already persisted
+    if (err && (err.name === "ExitPromptError" || err.message === "Prompt was canceled")) {
+  
+      console.log("");
+      printWarning("Setup interrupted — progress saved. Run 'voxlert setup' to resume.");
+      console.log("");
+      return;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Non-interactive setup: accept all defaults, skip prompts.
+ * Useful for CI, Docker, and automated testing.
+ */
+async function runNonInteractiveSetup(config) {
+  console.log("Running non-interactive setup (--yes)...\n");
+
+  // Step 1–2: LLM — skip (fallback phrases only)
+  printStep(1, "LLM Provider");
+  printStatus("LLM", "Skipped (fallback phrases only)");
+  config.llm_api_key = null;
+  config.openrouter_api_key = null;
+  console.log("");
+
+  // Step 3: Download default voice packs
+  printStep(3, "Download voice packs");
+  mkdirSync(PACKS_DIR, { recursive: true });
+
+  const existingPackIds = new Set();
+  try {
+    for (const entry of readdirSync(PACKS_DIR, { withFileTypes: true })) {
+      if (entry.isDirectory() && existsSync(join(PACKS_DIR, entry.name, "pack.json"))) {
+        existingPackIds.add(entry.name);
+      }
+    }
+  } catch {
+    // PACKS_DIR may not exist yet
+  }
+
+  const baseUrl = getPackRegistryBaseUrl();
+  for (const packId of DEFAULT_DOWNLOAD_PACK_IDS) {
+    if (existingPackIds.has(packId)) continue;
+    const pack = PACK_REGISTRY.find((p) => p.id === packId);
+    const label = pack ? pack.name : packId;
+    process.stdout.write(`  Downloading ${label}... `);
+    try {
+      await downloadPack(packId, baseUrl);
+      console.log("done.");
+    } catch (err) {
+      console.log(`failed (${err.message}).`);
+    }
+  }
+  console.log("");
+
+  // Step 4: Voice — random
+  printStep(4, "Voice Pack");
+  config.active_pack = "random";
+  printStatus("Voice", "random");
+  console.log("");
+
+  // Step 5: TTS — detect and pick best available, skip verification
+  printStep(5, "TTS Server");
+
+  process.stdout.write("  Checking Chatterbox... ");
+  const chatterboxUp = await probeTtsBackend(config, "chatterbox");
+  console.log(chatterboxUp ? "detected!" : "not running");
+
+  process.stdout.write("  Checking Qwen TTS... ");
+  const qwenUp = await probeTtsBackend(config, "qwen");
+  console.log(qwenUp ? "detected!" : "not running");
+
+  if (qwenUp) {
+    config.tts_backend = "qwen";
+  } else if (chatterboxUp) {
+    config.tts_backend = "chatterbox";
+  } else {
+    config.tts_backend = config.tts_backend || "qwen";
+  }
+  printStatus("TTS", config.tts_backend + (qwenUp || chatterboxUp ? "" : " (not running — text notifications only)"));
+  console.log("");
+
+  // Step 6: Hooks — skip
+  printStep(6, "Hooks");
+  printStatus("Hooks", "Skipped (run 'voxlert setup' to install hooks later)");
+  console.log("");
+
+  // Save config
   saveConfig(config);
 
-  // --- Summary ---
+  // Summary
+  printSetupSummary(config, "skip", []);
+}
+
+function printSetupSummary(config, chosenProvider, selectedPlatforms) {
   console.log("");
   console.log(highlight("=== Setup Complete ==="));
   console.log("");
@@ -516,13 +683,4 @@ export async function runSetup() {
   }
   printStatus("Reconfigure", "voxlert setup");
   console.log("");
-
-  } catch (err) {
-    // Inquirer throws on Ctrl+C (ExitPromptError); save partial progress
-    if (err && (err.name === "ExitPromptError" || err.message === "Prompt was canceled")) {
-      savePartial();
-      return;
-    }
-    throw err;
-  }
 }

package/src/tts-test.js

@@ -222,8 +222,7 @@ export async function chooseTtsBackend(config, { qwenUp, chatterboxUp }) {
     : "";
 
   if (!qwenUp && !chatterboxUp) {
-    printStatus("Note", "Local TTS needs a GPU or Apple Silicon. If that's a blocker:");
-    printStatus("Hosted option", "https://settinghead.github.io/pipevox-signup");
+    printStatus("Note", "Local TTS needs a GPU or Apple Silicon. Setup still works — you'll get text notifications until TTS is running.");
     console.log("");
   }
 
@@ -302,7 +301,7 @@ export async function verifyTtsSetup(config, backend) {
     }
 
     printWarning("Still not working? Local TTS requires specific hardware (Apple Silicon or NVIDIA GPU).");
-    printStatus("Hosted option", "https://settinghead.github.io/pipevox-signup — no local TTS needed");
+    printStatus("Setup help", "https://github.com/settinghead/voxlert/discussions/6");
     printStatus(`${label} docs`, docsUrl);
     console.log("");
   }