@micsushi/agent-hotline 0.5.1

package/README.md

@@ -0,0 +1,167 @@
+# Agent Hotline
+
+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.
+
+## What It Does
+
+- Reads finished coding-agent replies aloud.
+- Skips code blocks, diffs, logs, JSON, tables, and big dumps.
+- Lets you save replies or auto-play them when idle.
+- Gives you read, pause, resume, stop, replay, mute, and unmute controls.
+- Stores settings under `%APPDATA%\Agent Hotline\`.
+- Does not need model API keys or paid speech APIs for read-aloud.
+
+## Status
+
+Good enough for local development use.
+
+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.
+- For desktop app development: Rust plus the usual Tauri Windows prerequisites.
+
+## Install
+
+### Terminal install from npm
+
+Use this on a normal machine that should not clone this repo:
+
+```powershell
+npx --yes @micsushi/agent-hotline install --harness all --skill all
+```
+
+That one 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:
+
+```powershell
+npx --yes @micsushi/agent-hotline run
+```
+
+For one repo only:
+
+```powershell
+npx --yes @micsushi/agent-hotline install --harness all --skill all --scope repo --repo C:\path\to\repo
+```
+
+Optional: install once globally so you can use shorter commands:
+
+```powershell
+npm install -g @micsushi/agent-hotline
+agent-hotline install --harness all --skill all
+agent-hotline run
+```
+
+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
+```
+
+### Local checkout install
+
+Use this only when developing Agent Hotline from this repo:
+
+```powershell
+npm install
+npm run install-hotline -- --harness all --skill all
+```
+
+`npm install` also grabs the local TTS assets used by the desktop app. To repair those assets:
+
+```powershell
+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 polished desktop installer is not finished yet. Until then, the desktop control panel is run from a local checkout.
+
+## Run Locally
+
+From a global install, start the backend:
+
+```powershell
+ah run
+```
+
+From `npx`, start the backend:
+
+```powershell
+npx --yes @micsushi/agent-hotline run
+```
+
+From a local checkout, run it in the foreground while developing:
+
+```powershell
+npm run dev:backend
+```
+
+Start the desktop app:
+
+```powershell
+npm run dev:desktop
+```
+
+Backend URL:
+
+```text
+http://127.0.0.1:4777
+```
+
+## Smoke Test
+
+With the backend running, test the npm-installed hook:
+
+```powershell
+'{"source":"codex","response":{"text":"Spoken:`nAgent Hotline is ready to read this aloud.`n`nDisplayed:`nSmoke test complete."}}' | npx --yes @micsushi/agent-hotline hook
+```
+
+From a local checkout, test the local hook:
+
+```powershell
+'{"source":"codex","response":{"text":"Spoken:`nAgent Hotline is ready to read this aloud.`n`nDisplayed:`nSmoke test complete."}}' | node packages/backend/bin/agent-hotline.js hook
+```
+
+The sentence should show up in the Agent Hotline queue. If the backend is not running, the hook exits quietly.
+
+## Checks
+
+```powershell
+npm test
+npm run lint
+npm run format:check
+npm run check
+```
+
+## Docs
+
+- [Docs index](docs/README.md)
+- [Codex setup](docs/integrations/codex.md)
+- [Claude Code setup](docs/integrations/claude-code.md)
+- [Antigravity setup](docs/integrations/antigravity.md)
+
+## Repo Layout
+
+```text
+docs/                 Human setup notes
+packages/backend/     Local API, queue, settings, hook command
+packages/desktop/     Tauri tray app and control panel
+```

package/docs/README.md

@@ -0,0 +1,30 @@
+# Agent Hotline Docs
+
+Short setup notes for people using or hacking on Agent Hotline.
+
+## Setup
+
+- [Codex](integrations/codex.md)
+- [Claude Code](integrations/claude-code.md)
+- [Antigravity](integrations/antigravity.md)
+- [Spoken output](integrations/spoken-output.md)
+
+## Common Commands
+
+```powershell
+npm run install:tts
+npm run install-hotline -- --harness all --skill all
+npm run dev:backend
+npm run dev:desktop
+```
+
+From npm:
+
+```powershell
+npx --yes @micsushi/agent-hotline install --harness all --skill all
+npx --yes @micsushi/agent-hotline hook
+```
+
+## Notes
+
+Read-aloud playback is local. Agent Hotline talks to its local backend and uses browser/WebView text-to-speech.

package/docs/integrations/antigravity.md

@@ -0,0 +1,62 @@
+# Antigravity Setup
+
+Agent Hotline can read Antigravity replies aloud through its global hook setup. It only talks to the local Agent Hotline backend.
+
+## Install
+
+Start Agent Hotline first:
+
+```powershell
+npm install
+npm run dev:backend
+npm run dev:desktop
+```
+
+Install the Antigravity hook and spoken skill:
+
+```powershell
+npm run install-hotline -- --harness antigravity --skill antigravity
+```
+
+For a different backend URL, set `AGENT_HOTLINE_URL` before starting Antigravity.
+
+## Use It
+
+In Antigravity, say:
+
+```text
+hotline on
+```
+
+To stop adding read-aloud sections:
+
+```text
+hotline off
+```
+
+## Test
+
+```powershell
+@{
+  source = "antigravity"
+  hook_event_name = "Stop"
+  assistant_response = @{
+    text = "Spoken:`nAgent Hotline is ready to read Antigravity aloud.`n`nDisplayed:`nSmoke test complete."
+  }
+} | ConvertTo-Json -Depth 8 | node packages/backend/bin/agent-hotline.js hook
+```
+
+If Agent Hotline is running, the sentence lands in the queue.
+
+## Turn It Off
+
+- Remove the `Stop` hook from `%USERPROFILE%\.gemini\config\hooks.json`.
+- Or say `hotline off` in the session.
+- Or turn off Antigravity playback in Agent Hotline settings.
+
+## Troubleshooting
+
+- No audio: make sure the backend and desktop app are running.
+- Nothing queued: say `hotline on` and try again.
+- Different port: set `AGENT_HOTLINE_URL`.
+- Hook diagnostics: set `AGENT_HOTLINE_HOOK_DEBUG=1`.

package/docs/integrations/claude-code.md

@@ -0,0 +1,48 @@
+# Claude Code Setup
+
+Agent Hotline can read Claude Code replies aloud through a `Stop` hook. It only talks to the local Agent Hotline backend.
+
+## Install
+
+Start Agent Hotline first:
+
+```powershell
+npm install
+npm run dev:backend
+npm run dev:desktop
+```
+
+Then install the Claude Code hook and spoken-output instructions:
+
+```powershell
+npx --yes @micsushi/agent-hotline install --harness claude-code --skill claude-code --scope global
+```
+
+From a local checkout:
+
+```powershell
+npm run install-hotline -- --harness claude-code --skill claude-code --scope global
+```
+
+For a different backend URL, set `AGENT_HOTLINE_URL` before starting Claude Code.
+
+## Test
+
+```powershell
+'{"source":"claude","assistant_response":{"text":"Spoken:`nAgent Hotline is ready to read Claude Code aloud.`n`nDisplayed:`nSmoke test complete."}}' | node packages/backend/bin/agent-hotline.js hook
+```
+
+If Agent Hotline is running, the sentence lands in the queue. If not, the hook exits quietly.
+
+## Turn It Off
+
+- Repo setup: remove the hook from `.claude/settings.local.json`.
+- Global setup: remove it from `%USERPROFILE%\.claude\settings.json`.
+- Temporary: turn off Claude playback in Agent Hotline settings.
+
+## Troubleshooting
+
+- No audio: make sure the backend and desktop app are running.
+- Nothing queued: the reply may have been filtered out, or Claude playback may be off.
+- Different port: set `AGENT_HOTLINE_URL`.
+- Hook diagnostics: set `AGENT_HOTLINE_HOOK_DEBUG=1` before starting Claude Code.

package/docs/integrations/codex.md

@@ -0,0 +1,48 @@
+# Codex Setup
+
+Agent Hotline can read Codex replies aloud through a Codex `Stop` hook. It only talks to the local Agent Hotline backend.
+
+## Install
+
+Start Agent Hotline first:
+
+```powershell
+npm install
+npm run dev:backend
+npm run dev:desktop
+```
+
+Then install the Codex hook and spoken-output instructions:
+
+```powershell
+npx --yes @micsushi/agent-hotline install --harness codex --skill codex --scope global
+```
+
+From a local checkout:
+
+```powershell
+npm run install-hotline -- --harness codex --skill codex --scope global
+```
+
+For a different backend URL, set `AGENT_HOTLINE_URL` before starting Codex.
+
+## Test
+
+```powershell
+'{"source":"codex","response":{"text":"Spoken:`nAgent Hotline is ready to read Codex aloud.`n`nDisplayed:`nSmoke test complete."}}' | node packages/backend/bin/agent-hotline.js hook
+```
+
+If Agent Hotline is running, the sentence lands in the queue. If not, the hook exits quietly.
+
+## Turn It Off
+
+- Repo setup: remove the hook from `<repo>\.codex\hooks.json`.
+- Global setup: remove it from `%USERPROFILE%\.codex\hooks.json`.
+- Temporary: turn off Codex playback in Agent Hotline settings.
+
+## Troubleshooting
+
+- No audio: make sure the backend and desktop app are running.
+- Nothing queued: the reply may have been filtered out, or Codex playback may be off.
+- Different port: set `AGENT_HOTLINE_URL`.
+- Hook diagnostics: set `AGENT_HOTLINE_HOOK_DEBUG=1` before starting Codex.

package/docs/integrations/spoken-output.md

@@ -0,0 +1,36 @@
+# Spoken Output
+
+Agent Hotline works best when a reply has a short `Spoken:` section. It reads that part and ignores the rest.
+
+Install the formatting instructions:
+
+```powershell
+npm run install-skill -- --target all
+```
+
+From npm:
+
+```powershell
+agent-hotline install-skill --target all
+```
+
+## Contract
+
+```text
+Spoken:
+A short, conversational summary meant to be heard.
+
+==========
+
+Displayed:
+The full normal answer with code, paths, commands, and details.
+```
+
+Keep `Spoken:` short and plain. Put everything technical in `Displayed:`.
+
+## Verify
+
+1. Start Agent Hotline.
+2. Install the hook and spoken-output instructions.
+3. Ask for a normal reply.
+4. Confirm Agent Hotline reads only the `Spoken:` text.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@micsushi/agent-hotline",
+  "version": "0.5.1",
+  "description": "Local read-aloud hooks and tray app for AI coding agents.",
+  "bin": {
+    "ah": "packages/backend/bin/agent-hotline.js",
+    "agent-hotline": "packages/backend/bin/agent-hotline.js",
+    "agent-hotline-hook": "packages/backend/bin/agent-hotline-hook.js"
+  },
+  "files": [
+    "README.md",
+    "docs/",
+    "packages/backend/bin/",
+    "packages/backend/src/",
+    "packages/backend/skills/",
+    "packages/backend/package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "start": "npm --prefix packages/backend start",
+    "dev:backend": "npm --prefix packages/backend start",
+    "dev:desktop": "npm --workspace @agent-hotline/desktop run dev",
+    "install:tts": "npm --workspace @agent-hotline/desktop run install:tts",
+    "install-hook": "node scripts/install-hook.js",
+    "install-skill": "node scripts/install-skill.js",
+    "install-hotline": "node packages/backend/bin/agent-hotline.js install",
+    "test": "npm --prefix packages/backend test && npm --workspace @agent-hotline/desktop run test",
+    "lint": "eslint . && npm run rust:clippy",
+    "lint:fix": "eslint . --fix",
+    "fix": "prettier . --write && npm run lint:fix && npm run rust:fmt",
+    "format": "prettier . --write && npm run rust:fmt",
+    "format:check": "prettier . --check && npm run rust:fmt:check",
+    "verify:eol": "node scripts/verify-ci-eol.js",
+    "rust:fmt": "cargo fmt --manifest-path packages/desktop/src-tauri/Cargo.toml",
+    "rust:fmt:check": "cargo fmt --manifest-path packages/desktop/src-tauri/Cargo.toml --check",
+    "rust:clippy": "cargo clippy --manifest-path packages/desktop/src-tauri/Cargo.toml --all-targets -- -D warnings",
+    "check": "npm test && npm run format:check && npm run lint && npm --prefix packages/backend run check && npm --workspace @agent-hotline/desktop run check",
+    "ci": "npm ci && npm run check"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.5.0",
+    "globals": "^17.6.0",
+    "prettier": "^3.8.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Micsushi/agent-hotline.git"
+  },
+  "homepage": "https://github.com/Micsushi/agent-hotline#readme",
+  "bugs": {
+    "url": "https://github.com/Micsushi/agent-hotline/issues"
+  }
+}

package/packages/backend/README.md

@@ -0,0 +1,40 @@
+# Agent Hotline Backend
+
+Local HTTP backend for Agent Hotline.
+
+This package owns hook parsing, text filtering, the speech queue, settings, local API routes, and the `agent-hotline hook` command.
+
+## Run
+
+Background mode:
+
+```powershell
+ah run
+```
+
+Dev mode:
+
+```powershell
+npm run dev:backend
+```
+
+Default URL:
+
+```text
+http://127.0.0.1:4777
+```
+
+Use `AGENT_HOTLINE_PORT` to change the port.
+
+Runtime data lives in:
+
+```text
+%APPDATA%\Agent Hotline\
+```
+
+## Checks
+
+```powershell
+npm --prefix packages/backend test
+npm --prefix packages/backend run check
+```

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

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+const { main } = require("../src/hook-command");
+
+main()
+  .then((exitCode) => {
+    process.exitCode = exitCode;
+  })
+  .catch(() => {
+    process.exitCode = 0;
+  });

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

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+const { main: hookMain } = require("../src/hook-command");
+const { installHooks, installSkills, npxHookCommand, parseArgs } = require("../src/installer");
+const { launchBackend } = require("../src/run-command");
+
+function printHelp() {
+  console.log(`Agent Hotline
+
+Usage:
+  agent-hotline run
+  agent-hotline hook
+  agent-hotline install --harness codex --skill codex
+  agent-hotline install-hooks --harness all
+  agent-hotline install-skill --target all
+  agent-hotline install --harness all --skill all
+
+Options:
+  --harness antigravity|claude-code|codex|all
+  --target antigravity|claude-code|codex|all
+  --skill antigravity|claude-code|codex|all
+  --scope global|repo
+  --repo <path>
+  --home <path>
+  --hook-command <command>
+  --port <port>       Backend port for "run" (default: 4777)
+  --use-npx-hook    Write hooks that call "npx --yes @micsushi/agent-hotline hook"
+`);
+}
+
+function printResults(title, results) {
+  console.log(title);
+  for (const result of results) {
+    console.log(
+      `  ${result.target || result.harness} (${result.scope}): ${result.path || result.configPath}`
+    );
+  }
+}
+
+function isNpmExec() {
+  return (
+    process.env.npm_command === "exec" ||
+    /\bnpm exec\b/.test(process.env.npm_config_user_agent || "")
+  );
+}
+
+function hookCommandFromArgs(args) {
+  if (args["hook-command"]) return args["hook-command"];
+  if (args["use-npx-hook"] || isNpmExec()) return npxHookCommand();
+  return undefined;
+}
+
+async function main(argv = process.argv.slice(2), options = {}) {
+  const [command, subcommand, ...rest] = argv;
+
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return 0;
+  }
+
+  if (command === "hook") {
+    return hookMain();
+  }
+
+  if (command === "run" || command === "start") {
+    const args = parseArgs([subcommand, ...rest].filter(Boolean));
+    const launcher = options.launchBackend || launchBackend;
+    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.");
+    return 0;
+  }
+
+  if (command === "install-hooks") {
+    const args = parseArgs([subcommand, ...rest].filter(Boolean));
+    const results = installHooks({
+      harness: args.harness || "all",
+      scope: args.scope || "global",
+      repo: args.repo,
+      home: args.home,
+      hookCommand: hookCommandFromArgs(args)
+    });
+    printResults("Installed Agent Hotline hooks:", results);
+    return 0;
+  }
+
+  if (command === "install-skill") {
+    const args = parseArgs([subcommand, ...rest].filter(Boolean));
+    const results = installSkills({
+      target: args.target || args.harness || "all",
+      scope: args.scope || "global",
+      repo: args.repo,
+      home: args.home
+    });
+    printResults("Installed Agent Hotline spoken skill/instructions:", results);
+    return 0;
+  }
+
+  if (command === "install") {
+    const args = parseArgs([subcommand, ...rest].filter(Boolean));
+    const hookResults = installHooks({
+      harness: args.harness || "all",
+      scope: args.scope || "global",
+      repo: args.repo,
+      home: args.home,
+      hookCommand: hookCommandFromArgs(args)
+    });
+    const skillResults = installSkills({
+      target: args.skill || args.target || args.harness || "all",
+      scope: args.scope || "global",
+      repo: args.repo,
+      home: args.home
+    });
+    printResults("Installed Agent Hotline hooks:", hookResults);
+    printResults("Installed Agent Hotline spoken skill/instructions:", skillResults);
+    return 0;
+  }
+
+  console.error(`Unknown command "${command}".`);
+  printHelp();
+  return 1;
+}
+
+if (require.main === module) {
+  main()
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((error) => {
+      console.error(error.message);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = { main };

package/packages/backend/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@agent-hotline/backend",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Local web backend for Agent Hotline.",
+  "type": "commonjs",
+  "bin": {
+    "ah": "bin/agent-hotline.js",
+    "agent-hotline": "bin/agent-hotline.js",
+    "agent-hotline-hook": "bin/agent-hotline-hook.js"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node --test test/*.test.js",
+    "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 bin/agent-hotline.js && node --check bin/agent-hotline-hook.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"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}