@micsushi/agent-hotline 1.0.1 → 1.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 Agent Hotline is a local Windows tray app that reads useful parts of Codex, Claude Code, and Antigravity replies aloud.
 
-You keep using your coding tool like normal. Agent Hotline listens for finished responses through local hooks, skips code-heavy bits, and reads the useful prose through the desktop WebView. The full reply stays in the original chat.
+You keep using your coding tool like normal. Agent Hotline listens for finished responses through local hooks, skips code-heavy bits, and reads the useful prose through the browser or desktop UI. The full reply stays in the original chat.
 
 ## What It Does
 
@@ -15,40 +15,57 @@ You keep using your coding tool like normal. Agent Hotline listens for finished
 
 ## Status
 
-Good enough for local development use.
+Usable from npm or the Windows desktop installer.
 
 Still missing:
 
-- A normal packaged installer.
-- A bundled backend sidecar for production installs.
 - Voice input owned by Agent Hotline.
 
 ## Requirements
 
 - Windows 10 or 11.
-- Node.js 22 or newer.
-- For terminal install only: no repo clone is needed.
+- Node.js 22 or newer for the npm/npx commands.
+- No repo clone is needed for normal install.
 - For desktop app development: Rust plus the usual Tauri Windows prerequisites.
 
 ## Install
 
+### Recommended: desktop app plus hook setup
+
+1. Download and run the latest Windows installer:
+
+```text
+https://github.com/Micsushi/agent-hotline/releases/latest
+```
+
+2. Install the hooks and spoken instructions:
+
+```powershell
+npx --yes @micsushi/agent-hotline install --harness all --skill all
+```
+
+3. Restart Codex, Claude Code, or Antigravity so it reloads its hook files.
+
+After that, open Agent Hotline from the Start Menu. The desktop app starts its own bundled backend and opens the panel. No separate `ah run` command is needed for the desktop installer.
+
 ### Terminal install from npm
 
-Use this on a normal machine that should not clone this repo:
+Use this when you want the browser control panel instead of the native tray app:
 
 ```powershell
 npx --yes @micsushi/agent-hotline install --harness all --skill all
+npx --yes @micsushi/agent-hotline run
 ```
 
-That one command downloads the Agent Hotline npm package and installs both parts:
+The install command downloads the Agent Hotline npm package and installs both parts:
 
 - the hook/tool command used by Codex, Claude Code, and Antigravity
 - the spoken-output skill or managed instructions
 
-Start the local backend:
+The run command starts the backend and opens the browser control panel:
 
-```powershell
-npx --yes @micsushi/agent-hotline run
+```text
+http://127.0.0.1:4777
 ```
 
 For one repo only:
@@ -65,12 +82,20 @@ agent-hotline install --harness all --skill all
 agent-hotline run
 ```
 
+If `ah` or `agent-hotline` is not found after a global install, run:
+
+```powershell
+npx --yes @micsushi/agent-hotline doctor
+npx --yes @micsushi/agent-hotline doctor --fix-path
+```
+
 Useful separate commands:
 
 ```powershell
 npx --yes @micsushi/agent-hotline install-hooks --harness all
 npx --yes @micsushi/agent-hotline install-skill --target all
 npx --yes @micsushi/agent-hotline hook
+npx --yes @micsushi/agent-hotline run --no-open
 ```
 
 ### Local checkout install
@@ -90,9 +115,9 @@ npm run install:tts
 
 ## What Gets Installed
 
-The npm package includes the CLI/backend hook tool and the spoken skill/instructions. Users do not download those separately.
+The npm package includes the CLI/backend hook tool, the browser control panel, and the spoken skill/instructions. Users do not download those separately.
 
-The polished desktop installer is not finished yet. Until then, the desktop control panel is run from a local checkout.
+The GitHub release includes the Windows desktop installer for the native tray/WebView app and a bundled backend. The installer does not yet write Codex, Claude Code, or Antigravity hook files, so run the npm setup command once after installing the desktop app.
 
 ## Run Locally
 
@@ -108,6 +133,18 @@ From `npx`, start the backend:
 npx --yes @micsushi/agent-hotline run
 ```
 
+This also opens the browser control panel:
+
+```text
+http://127.0.0.1:4777
+```
+
+To start only the backend:
+
+```powershell
+npx --yes @micsushi/agent-hotline run --no-open
+```
+
 From a local checkout, run it in the foreground while developing:
 
 ```powershell
@@ -142,6 +179,47 @@ From a local checkout, test the local hook:
 
 The sentence should show up in the Agent Hotline queue. If the backend is not running, the hook exits quietly.
 
+## Troubleshooting
+
+### The desktop app says Backend unavailable
+
+Install the latest GitHub release. The current desktop app starts its bundled backend automatically. If you are using the npm/browser version instead, run:
+
+```powershell
+npx --yes @micsushi/agent-hotline run
+```
+
+### I ran ah run but no tray icon appeared
+
+`ah run` starts the npm/browser version. It opens `http://127.0.0.1:4777` and does not start the native tray app. For the tray app, install and launch the GitHub `.exe`.
+
+### ah is not recognized
+
+Use `npx` directly, or install globally:
+
+```powershell
+npm install -g @micsushi/agent-hotline
+npx --yes @micsushi/agent-hotline doctor
+```
+
+If npm's global command folder is missing from PATH on Windows:
+
+```powershell
+npx --yes @micsushi/agent-hotline doctor --fix-path
+```
+
+Restart the terminal after changing PATH.
+
+### Agent replies are not spoken
+
+Make sure the hook and spoken instructions are installed, then restart the coding tool:
+
+```powershell
+npx --yes @micsushi/agent-hotline install --harness all --skill all
+```
+
+Then say `hotline on` or `read aloud on` in Codex, Claude Code, or Antigravity.
+
 ## Checks
 
 ```powershell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micsushi/agent-hotline",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Local read-aloud hooks and tray app for AI coding agents.",
   "bin": {
     "ah": "packages/backend/bin/agent-hotline.js",
@@ -36,6 +36,8 @@
     "install-hotline": "node packages/backend/bin/agent-hotline.js install",
     "stage-web": "node scripts/stage-web.mjs",
     "prepack": "node scripts/stage-web.mjs",
+    "build:backend-sea": "node scripts/build-backend-sea.mjs",
+    "sync-desktop-version": "node scripts/sync-desktop-version.mjs",
     "test": "npm --prefix packages/backend test && npm --workspace @agent-hotline/desktop run test",
     "lint": "eslint . && npm run rust:clippy",
     "lint:fix": "eslint . --fix",
@@ -51,8 +53,10 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "esbuild": "^0.28.1",
     "eslint": "^10.5.0",
     "globals": "^17.6.0",
+    "postject": "^1.0.0-alpha.6",
     "prettier": "^3.8.4"
   },
   "repository": {

package/packages/backend/bin/agent-hotline.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
 const { main: hookMain } = require("../src/hook-command");
+const { createDoctorReport, fixWindowsUserPath, formatDoctorReport } = require("../src/doctor");
 const { installHooks, installSkills, npxHookCommand, parseArgs } = require("../src/installer");
-const { launchBackend } = require("../src/run-command");
+const { launchBackend, openUrl } = require("../src/run-command");
 
 function printHelp() {
   console.log(`Agent Hotline
@@ -10,6 +11,8 @@ function printHelp() {
 Usage:
   agent-hotline run
   agent-hotline hook
+  agent-hotline doctor
+  agent-hotline doctor --fix-path
   agent-hotline install --harness codex --skill codex
   agent-hotline install-hooks --harness all
   agent-hotline install-skill --target all
@@ -24,6 +27,8 @@ Options:
   --home <path>
   --hook-command <command>
   --port <port>       Backend port for "run" (default: 4777)
+  --no-open           Start only the backend; do not open the browser panel
+  --fix-path          With "doctor", add npm global bin to the Windows user PATH
   --use-npx-hook    Write hooks that call "npx --yes @micsushi/agent-hotline hook"
 `);
 }
@@ -65,12 +70,42 @@ async function main(argv = process.argv.slice(2), options = {}) {
   if (command === "run" || command === "start") {
     const args = parseArgs([subcommand, ...rest].filter(Boolean));
     const launcher = options.launchBackend || launchBackend;
+    const opener = options.openUrl || openUrl;
     const result = launcher({ port: args.port });
     console.log(`Agent Hotline backend started in the background on ${result.url}.`);
     if (result.pid) {
       console.log(`Process id: ${result.pid}`);
     }
-    console.log("You can close this terminal; the backend will keep running.");
+    if (!args["no-open"]) {
+      opener(result.url);
+      console.log(`Opening the Agent Hotline browser panel: ${result.url}`);
+    } else {
+      console.log(`Open the Agent Hotline browser panel: ${result.url}`);
+    }
+    console.log("You can close this terminal; Agent Hotline will keep running.");
+    return 0;
+  }
+
+  if (command === "doctor") {
+    const args = parseArgs([subcommand, ...rest].filter(Boolean));
+    const report = createDoctorReport();
+    console.log(formatDoctorReport(report));
+    if (args["fix-path"]) {
+      if (report.platform !== "win32") {
+        console.log("--fix-path is only supported on Windows.");
+      } else if (!report.binDir) {
+        console.log("Could not find npm global bin directory.");
+      } else if (report.onPath) {
+        console.log("npm global bin is already on PATH.");
+      } else {
+        const result = fixWindowsUserPath(report.binDir);
+        console.log(
+          result.ok
+            ? "Added npm global bin to your user PATH. Restart your terminal."
+            : `Could not update PATH: ${result.error || "unknown error"}`
+        );
+      }
+    }
     return 0;
   }
 

package/packages/backend/package.json

@@ -13,7 +13,7 @@
   "scripts": {
     "start": "node src/server.js",
     "test": "node --test test/*.test.js test/*.test.mjs",
-    "check": "node --check src/server.js && node --check src/settings-store.js && node --check src/speech-queue-store.js && node --check src/audio-cache-store.js && node --check src/installer.js && node --check src/hook-input-parser.js && node --check src/hook-command.js && node --check src/run-command.js && node --check src/speakable-filter.js && node --check src/mcp-server.mjs && node --check bin/agent-hotline.js && node --check bin/agent-hotline-hook.js && node --check bin/agent-hotline-mcp.js && node --check test/settings-store.test.js && node --check test/speech-queue-store.test.js && node --check test/audio-cache-store.test.js && node --check test/audio-endpoints.test.js && node --check test/installer.test.js && node --check test/run-command.test.js && node --check test/speakable-filter.test.js && node --check test/hook-input-parser.test.js && node --check test/hook-command.test.js && node --check test/server-endpoints.test.js && node --check test/mcp-server.test.mjs"
+    "check": "node --check src/server.js && node --check src/settings-store.js && node --check src/speech-queue-store.js && node --check src/audio-cache-store.js && node --check src/doctor.js && node --check src/installer.js && node --check src/hook-input-parser.js && node --check src/hook-command.js && node --check src/run-command.js && node --check src/speakable-filter.js && node --check src/mcp-server.mjs && node --check bin/agent-hotline.js && node --check bin/agent-hotline-hook.js && node --check bin/agent-hotline-mcp.js && node --check test/settings-store.test.js && node --check test/speech-queue-store.test.js && node --check test/audio-cache-store.test.js && node --check test/audio-endpoints.test.js && node --check test/doctor.test.js && node --check test/installer.test.js && node --check test/run-command.test.js && node --check test/speakable-filter.test.js && node --check test/hook-input-parser.test.js && node --check test/hook-command.test.js && node --check test/server-endpoints.test.js && node --check test/mcp-server.test.mjs"
   },
   "engines": {
     "node": ">=18"

package/packages/backend/src/doctor.js

@@ -0,0 +1,129 @@
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function globalBinFromPrefix(prefix, platform = process.platform) {
+  const trimmed = String(prefix || "").trim();
+  if (!trimmed) return "";
+  return platform === "win32" ? trimmed : path.join(trimmed, "bin");
+}
+
+function npmGlobalPrefix(options = {}) {
+  const spawnSyncImpl = options.spawnSync || spawnSync;
+  const platform = options.platform || process.platform;
+  const result = spawnSyncImpl("npm", ["config", "get", "prefix"], {
+    encoding: "utf8",
+    windowsHide: true
+  });
+  if (result.error || result.status !== 0) {
+    if (platform === "win32" && process.env.APPDATA) {
+      return path.join(process.env.APPDATA, "npm");
+    }
+    return "";
+  }
+  return String(result.stdout || "").trim();
+}
+
+function pathEntries(value = process.env.PATH || "") {
+  return String(value)
+    .split(path.delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function pathContains(dir, value = process.env.PATH || "", platform = process.platform) {
+  const normalize =
+    platform === "win32" ? (entry) => entry.toLowerCase().replace(/[\\/]+$/, "") : (entry) => entry;
+  const target = normalize(dir);
+  return pathEntries(value).some((entry) => normalize(entry) === target);
+}
+
+function windowsPathFixCommand(binDir) {
+  const escaped = String(binDir).replace(/'/g, "''");
+  return [
+    "$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')",
+    `$bin = '${escaped}'`,
+    "if ($null -eq $userPath) { $userPath = '' }",
+    "if (($userPath -split ';') -notcontains $bin) {",
+    "  $nextPath = if ([string]::IsNullOrWhiteSpace($userPath)) { $bin } else { $userPath.TrimEnd(';') + ';' + $bin }",
+    "  [Environment]::SetEnvironmentVariable('Path', $nextPath, 'User')",
+    "}",
+    "Write-Host 'Restart your terminal after updating PATH.'"
+  ].join("; ");
+}
+
+function fixWindowsUserPath(binDir, options = {}) {
+  const spawnSyncImpl = options.spawnSync || spawnSync;
+  const result = spawnSyncImpl(
+    "powershell.exe",
+    ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", windowsPathFixCommand(binDir)],
+    {
+      encoding: "utf8",
+      windowsHide: true
+    }
+  );
+  return {
+    ok: !result.error && result.status === 0,
+    error: result.error ? result.error.message : String(result.stderr || "").trim()
+  };
+}
+
+function createDoctorReport(options = {}) {
+  const platform = options.platform || process.platform;
+  const prefix = options.prefix || npmGlobalPrefix(options);
+  const binDir = globalBinFromPrefix(prefix, platform);
+  const onPath = binDir
+    ? pathContains(binDir, options.pathValue || process.env.PATH || "", platform)
+    : false;
+  const hasGlobalInstall = !!options.hasGlobalInstall;
+
+  return {
+    platform,
+    node: process.version,
+    prefix,
+    binDir,
+    onPath,
+    hasGlobalInstall,
+    pathFixCommand: platform === "win32" && binDir ? windowsPathFixCommand(binDir) : ""
+  };
+}
+
+function formatDoctorReport(report) {
+  const lines = [
+    "Agent Hotline doctor",
+    `Node: ${report.node}`,
+    `npm global bin: ${report.binDir || "not found"}`,
+    `npm global bin on PATH: ${report.onPath ? "yes" : "no"}`,
+    ""
+  ];
+
+  if (!report.onPath && report.platform === "win32" && report.pathFixCommand) {
+    lines.push("To add npm global commands like ah to PATH:");
+    lines.push(
+      `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "${report.pathFixCommand.replace(/"/g, '\\"')}"`
+    );
+    lines.push("");
+  }
+
+  lines.push("Recommended first run:");
+  lines.push("  npx --yes @micsushi/agent-hotline install --harness all --skill all");
+  lines.push("  npx --yes @micsushi/agent-hotline run");
+
+  if (report.platform === "win32") {
+    lines.push("");
+    lines.push("Windows desktop installer:");
+    lines.push("  https://github.com/Micsushi/agent-hotline/releases/latest");
+  }
+
+  return lines.join(os.EOL);
+}
+
+module.exports = {
+  createDoctorReport,
+  fixWindowsUserPath,
+  formatDoctorReport,
+  globalBinFromPrefix,
+  npmGlobalPrefix,
+  pathContains,
+  windowsPathFixCommand
+};

package/packages/backend/src/run-command.js

@@ -34,7 +34,38 @@ function launchBackend(options = {}) {
   };
 }
 
+function openUrl(url, options = {}) {
+  const spawnImpl = options.spawn || spawn;
+  const platform = options.platform || process.platform;
+  let command;
+  let args;
+
+  if (platform === "win32") {
+    command = "cmd";
+    args = ["/c", "start", "", url];
+  } else if (platform === "darwin") {
+    command = "open";
+    args = [url];
+  } else {
+    command = "xdg-open";
+    args = [url];
+  }
+
+  const child = spawnImpl(command, args, {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true
+  });
+
+  if (typeof child.unref === "function") {
+    child.unref();
+  }
+
+  return { command, args };
+}
+
 module.exports = {
   backendServerPath,
-  launchBackend
+  launchBackend,
+  openUrl
 };

package/packages/backend/src/server.js

@@ -8,14 +8,13 @@ const {
   TTS_ENGINES,
   createSettingsStore
 } = require("./settings-store");
-const { createSpeechQueueStore } = require("./speech-queue-store");
+const { createSpeechQueueStore, defaultDataDir } = require("./speech-queue-store");
 const { createSpoolStore } = require("./spool-store");
 const { createAudioCacheStore } = require("./audio-cache-store");
 
 const PORT = Number(process.env.AGENT_HOTLINE_PORT || process.env.VOICE_QUESTION_LOOP_PORT || 4777);
 const HOST = "127.0.0.1";
-const ROOT = path.resolve(__dirname, "..");
-const DATA_DIR = path.join(ROOT, "data");
+const DATA_DIR = process.env.AGENT_HOTLINE_DATA_DIR || defaultDataDir();
 const QUESTIONS_FILE = process.env.QUESTION_FILE || path.join(DATA_DIR, "questions.json");
 const REQUEST_LIMIT_BYTES = 1_000_000;
 const AUDIO_BODY_LIMIT_BYTES = 96 * 1024 * 1024;
@@ -646,22 +645,23 @@ function page() {
 }
 
 function createServer(options = {}) {
+  const dataDir = options.dataDir || DATA_DIR;
   const settingsStore =
     options.settingsStore ||
     createSettingsStore({
-      dataDir: options.dataDir,
+      dataDir,
       settingsPath: options.settingsPath
     });
   const queueStore =
     options.queueStore ||
     createSpeechQueueStore({
-      dataDir: options.dataDir,
+      dataDir,
       filePath: options.queuePath
     });
   const questionStore =
     options.questionStore ||
     createQuestionStore({
-      dataDir: options.questionDataDir || options.dataDir,
+      dataDir: options.questionDataDir || dataDir,
       questionsFile: options.questionsFile,
       answersFile: options.answersFile,
       ensureFiles: options.ensureQuestionFiles
@@ -670,7 +670,7 @@ function createServer(options = {}) {
   const audioCacheStore =
     options.audioCacheStore ||
     createAudioCacheStore({
-      dataDir: options.dataDir,
+      dataDir,
       cacheDir: options.audioCacheDir,
       maxBytes: options.audioMaxBytes,
       getMaxBytes: options.audioMaxBytes
@@ -679,8 +679,7 @@ function createServer(options = {}) {
     });
 
   const spoolStore =
-    options.spoolStore ||
-    createSpoolStore({ dataDir: options.dataDir, filePath: options.spoolPath });
+    options.spoolStore || createSpoolStore({ dataDir, filePath: options.spoolPath });
   try {
     spoolStore.drain((item) => queueStore.enqueue(item));
   } catch {}
@@ -1029,6 +1028,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  DATA_DIR,
   HOST,
   PORT,
   createServer,

package/packages/backend/src/settings-store.js

@@ -8,6 +8,7 @@ const READ_BEHAVIORS = new Set(["manual", "auto"]);
 const TTS_ENGINES = new Set(["webview", "kokoro", "kokoro-ts"]);
 const NOTIFICATION_OPENS = new Set(["full", "mini"]);
 const AUDIO_CACHE_LIMIT_MAX_MB = 100000;
+const DEFAULT_RATE = 0.9;
 
 const DEFAULT_SETTINGS = Object.freeze({
   readBehavior: "manual",
@@ -16,7 +17,7 @@ const DEFAULT_SETTINGS = Object.freeze({
   voice: "",
   audioOutputDeviceId: "",
   kokoroVoice: "af_heart",
-  rate: 0.92,
+  rate: DEFAULT_RATE,
   volume: 1,
   skipRules: Object.freeze({
     codeBlocks: true,
@@ -32,7 +33,9 @@ const DEFAULT_SETTINGS = Object.freeze({
   notifyOnNewReply: false,
   notificationOpens: "full",
   highlightSpokenText: false,
-  audioCacheLimitMb: 1024
+  audioCacheLimitMb: 1024,
+  startupSplash: true,
+  startupJingle: true
 });
 
 function getDefaultDataDir(env = process.env, platform = process.platform) {
@@ -79,6 +82,11 @@ function numberInRangeOrDefault(value, fallback, min, max) {
   return number >= min && number <= max ? number : fallback;
 }
 
+function normalizeRate(value, fallback) {
+  const rate = numberInRangeOrDefault(value, fallback, 0.1, 10);
+  return rate === 0.92 ? DEFAULT_RATE : rate;
+}
+
 function normalizeSettings(input) {
   const source = isPlainObject(input) ? input : {};
   const defaults = DEFAULT_SETTINGS;
@@ -93,7 +101,7 @@ function normalizeSettings(input) {
     voice: stringOrDefault(source.voice, defaults.voice),
     audioOutputDeviceId: stringOrDefault(source.audioOutputDeviceId, defaults.audioOutputDeviceId),
     kokoroVoice: stringOrDefault(source.kokoroVoice, defaults.kokoroVoice),
-    rate: numberInRangeOrDefault(source.rate, defaults.rate, 0.1, 10),
+    rate: normalizeRate(source.rate, defaults.rate),
     volume: numberInRangeOrDefault(source.volume, defaults.volume, 0, 1),
     skipRules: {
       codeBlocks: booleanOrDefault(sourceSkipRules.codeBlocks, defaults.skipRules.codeBlocks),
@@ -119,7 +127,9 @@ function normalizeSettings(input) {
       defaults.audioCacheLimitMb,
       10,
       AUDIO_CACHE_LIMIT_MAX_MB
-    )
+    ),
+    startupSplash: booleanOrDefault(source.startupSplash, defaults.startupSplash),
+    startupJingle: booleanOrDefault(source.startupJingle, defaults.startupJingle)
   };
 }