@settinghead/voxlert 0.3.7 → 0.3.9

package/README.md

@@ -62,8 +62,7 @@ The setup wizard auto-detects running TTS backends. If none are running yet, set
 ### 2. Install and run setup
 
 ```bash
-npm install -g @settinghead/voxlert
-voxlert setup
+npx voxlert --onboard
 ```
 
 The setup wizard configures:
@@ -241,6 +240,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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@settinghead/voxlert",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "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

@@ -53,6 +53,14 @@ async function maybeRunSetup(command) {
 
 (async () => {
   const args = process.argv.slice(2);
+
+  // --onboard flag: run setup wizard directly (supports `npx voxlert --onboard`)
+  if (args.includes("--onboard")) {
+    const { runSetup } = await import("./setup.js");
+    await runSetup();
+    return;
+  }
+
   const requested = args[0] || "help";
   const command = resolveCommand(requested);
 

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.
@@ -243,7 +265,7 @@ export async function runSetup({ nonInteractive = false } = {}) {
   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;
@@ -253,69 +275,104 @@ export async function runSetup({ nonInteractive = false } = {}) {
 
     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;
-        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;