@lucas_zaia/agent-voice 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Zaia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# agent-voice
+
+**Make your coding agent talk to you.** When Claude Code or Codex finishes a
+long task — or gets stuck waiting for your permission — a speaker says so out
+loud:
+
+> *"Claude Code terminou na sessão Home assistant repo, depois de cerca de 4
+> minutos. Você tinha pedido: criar o docker compose."*
+
+> *"Codex precisa de você na sessão azul, do projeto api, para usar o Bash."*
+
+Works on macOS, Windows and Linux. Speaks through an Echo (via Home Assistant),
+your computer's own voice, or any command you like.
+
+## Install
+
+Requires Node.js 20 or newer.
+
+```bash
+npm install -g @lucas_zaia/agent-voice
+agent-voice setup
+```
+
+`setup` finds your agents, adds its hooks to them (showing you exactly what it
+adds, and backing up the file first), asks how you want it to speak, and says a
+test sentence so you know it works.
+
+**Windows PowerShell** blocks npm's `.ps1` launchers by default ("execução de
+scripts foi desabilitada" / "running scripts is disabled"). Either allow them
+for your user once — `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` —
+or call `npm.cmd` and `agent-voice.cmd` instead. The agent hooks are not
+affected: they run `agent-voice.cmd`.
+
+Running from a checkout instead? Either `npm link` in the checkout (so
+`agent-voice` is on your PATH), or tell the hooks how to call it before
+connecting:
+
+```bash
+AV_HOOK_COMMAND="node /path/to/agent-voice/bin/agent-voice.js" agent-voice connect claude-code
+```
+
+`AV_HOOK_COMMAND` is the command written into the agent's hooks (default
+`agent-voice`); it is read when you run `setup` or `connect`.
+
+## Why
+
+You ask an agent for something that takes a while and stop watching. Then
+either the work finishes and sits there, or — worse — it stopped thirty seconds
+in at a permission prompt. A popup appears in the window you stopped looking
+at. A voice does not. agent-voice follows two rules:
+
+- **Say something specific**: which session, and what you had asked for.
+- **Stay quiet most of the time**: short turns are never announced.
+
+## When it speaks
+
+| Situation | What happens |
+|---|---|
+| A turn finishes in under 30s | Silent |
+| A turn finishes in over 30s | **Speaks**, with how long it took and what you asked |
+| Background work finishes (a subagent, a task) | **Speaks**, at most once every 120s per session |
+| Background work with nothing to report | Silent |
+| The agent needs your permission or input | **Always speaks** |
+
+Every decision, including every silence, goes to the log with its reason —
+`agent-voice status` shows the latest lines.
+
+## Commands
+
+```
+agent-voice setup                         guided setup
+agent-voice connect <claude-code|codex>   add hooks to an agent (--yes to skip the question)
+agent-voice disconnect <claude-code|codex>
+agent-voice output add <alexa|local|command> [name]
+agent-voice output list | remove | enable | disable | test [name]
+agent-voice wrap [--name <label>] -- <command...>
+agent-voice status
+agent-voice config get [key] | set <key> <value>
+agent-voice test
+```
+
+## Speakers
+
+| Type | How | Needs |
+|---|---|---|
+| `alexa` | Home Assistant's `notify.send_message` on an Echo entity | Home Assistant URL, a long-lived token, and the Alexa Media Player integration |
+| `local` | `say` (macOS), SAPI (Windows), `spd-say`/`espeak-ng` (Linux) | Nothing on macOS/Windows; `espeak-ng` or speech-dispatcher on Linux |
+| `command` | Runs any command; `{text}` in it is replaced by the sentence, otherwise the sentence goes to stdin | The command |
+
+You can have several, e.g. `alexa-sala` and `alexa-escritorio`; every enabled
+output speaks, each given up to 15 seconds.
+
+A `command` never goes through a shell: arguments are passed as typed, and a
+leading `~`, `$HOME` or `%USERPROFILE%` means your home directory. On Windows a
+`.cmd`/`.bat` speaker is run through `cmd.exe` with every argument quoted and
+escaped, so the sentence can never run anything; a batch file sees it with
+`^` escapes, which disappear when it passes `%*` or `%1` on to another program.
+
+## Agents
+
+- **Claude Code** — hooks in `~/.claude/settings.json`.
+- **Codex CLI** — hooks in `~/.codex/hooks.json`. Codex runs a hook only after
+  you trust it: open Codex and run `/hooks` once after connecting.
+- **Anything else** — `agent-voice wrap -- aider ...` announces when the
+  command finishes (no "needs you" announcements in this mode).
+
+Adding an agent: see [`docs/adapters.md`](docs/adapters.md).
+
+## Tuning
+
+Tune against your own log. If most of your turns sit below the threshold it
+will feel broken — it will simply never speak.
+
+```bash
+agent-voice config set minSeconds 20
+agent-voice config set cooldownSeconds 300
+```
+
+| Key | Default | Env override |
+|---|---|---|
+| `minSeconds` | 30 | `AV_MIN_SECONDS` |
+| `cooldownSeconds` | 120 | `AV_COOLDOWN_SECONDS` |
+| `maxSpeechChars` | 90 | `AV_MAX_SPEECH_CHARS` |
+
+## Where things live
+
+| | Config | State and `events.log` |
+|---|---|---|
+| Linux | `~/.config/agent-voice` | `~/.local/state/agent-voice` |
+| macOS | `~/Library/Application Support/agent-voice` | `…/agent-voice/state` |
+| Windows | `%APPDATA%\agent-voice` | `%LOCALAPPDATA%\agent-voice` |
+
+## Troubleshooting
+
+Run `agent-voice status` first — the reason is almost always in the log lines it prints.
+
+- `silent (turn 21s < 30s)` → working as configured; lower `minSeconds`.
+- `FAILED via <output> (…)` → the speaker failed; the parenthesis says why. Try `agent-voice output test <name>`.
+- `no such output: <name>` → enabled but not configured; `agent-voice output add`.
+- An agent shows `legacy` → it still has the old bash hooks; run `agent-voice connect <agent>`.
+- Nothing in the log at all → the hooks are not firing. In Claude Code, open `/hooks` once to reload; in Codex, trust them in `/hooks`.
+
+## Upgrading from the bash version
+
+1. `npm install -g @lucas_zaia/agent-voice`
+2. `agent-voice setup` — for the same Echo as before, pick `command` and enter
+   `~/softwares/home-assistant/falar.sh -a {text}`, or pick `alexa` to talk to
+   Home Assistant directly.
+3. `agent-voice connect claude-code` replaces the old `…/bin/notify` hooks.
+
+Existing state in `~/.local/state/agent-voice` is reused as-is.
+
+## Notes
+
+- **It cannot break your agent.** The hook entry point exits 0 no matter what;
+  failures go to the log and nowhere else.
+- **Language.** Code and docs are English; the spoken sentences are Brazilian
+  Portuguese and live in one file, `src/core/phrases.js`.
+- **Concurrency.** State is keyed per agent and per session, so parallel
+  sessions never mix up their turns, durations or cooldowns.
+
+## License
+
+MIT.

package/bin/agent-voice.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from '../src/cli/main.js';
+import { guardNotifyProcess } from '../src/cli/notify.js';
+
+const argv = process.argv.slice(2);
+if (argv[0] === 'notify') guardNotifyProcess(argv.slice(1));
+// `agent-voice status | head`: the reader went away, so there is nobody left to talk to.
+else process.stdout.on('error', (e) => { if (e.code === 'EPIPE') process.exit(0); throw e; });
+process.exitCode = await main(argv);

package/docs/adapters.md

@@ -0,0 +1,56 @@
+# Writing an adapter
+
+An adapter teaches agent-voice about one agent. It is a module in
+`src/adapters/<agent>.js`, registered in `src/adapters/index.js`. It **stores
+nothing and decides nothing** — no thresholds, no cooldown, no sentences. The
+core owns all of that, so every agent gets the same behaviour and the same fixes.
+
+## The module
+
+| Export | What it is |
+|---|---|
+| `name` | The agent id, e.g. `"codex"`. Used in hook commands, state paths and the log |
+| `hooks` | `[{ event, sub, async?, timeout }]` — which agent events call `agent-voice notify <name> <sub>`. Give hooks that can speak `timeout: 60`: each output gets up to 15s, one after another, and the FAILED line must reach the log before the agent kills the hook |
+| `notes` | Strings printed after `connect` (e.g. "trust the hooks in /hooks") |
+| `configFile(env, home)` | Path of the agent's JSON config that holds hooks |
+| `detect(env, home)` | Whether the agent is installed here |
+| `hookReply(sub)` | What to print on stdout for the agent (usually `''`) |
+| `translate(sub, payload, home)` | The agent's hook payload → one canonical event, or `null` |
+
+`connect`/`disconnect` work for any agent whose config uses the
+`{"hooks": {Event: [{hooks: [{type, command}]}]}}` shape; see
+`src/adapters/hooks-json.js`.
+
+## The canonical event
+
+```json
+{ "type": "task_done",
+  "agent": "your-agent",
+  "session_id": "stable-identity",
+  "session_name": "Human readable, optional",
+  "project": "last path segment, optional",
+  "text": "what was asked, or the message, optional" }
+```
+
+| `type` | When |
+|---|---|
+| `turn_start` | The user submitted a request. Carry the request in `text` |
+| `task_done` | The agent finished responding (`text` is ignored — the core uses the stored request) |
+| `background_done` | Background work finished (a subagent, a queued task) |
+| `needs_input` | The agent is blocked on a permission or a question |
+
+`type`, `agent` and `session_id` are required; an event missing any of them is
+dropped and logged as `ignored: incomplete event`. `session_id` must be stable
+for the whole session. Never compute a duration — the core does.
+
+## Agents with no hooks
+
+Use `agent-voice wrap -- <command>`: it marks the start, runs the command, and
+marks the end.
+
+## Checklist
+
+- [ ] `translate` returns `null` for unknown subcommands and never throws on garbage
+- [ ] `agentName` in `src/core/phrases.js` has a spoken name for the agent
+- [ ] A test file `tests/adapter-<agent>.test.js` mirroring `tests/adapter-codex.test.js`
+- [ ] The adapter is listed in `src/adapters/index.js`

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@lucas_zaia/agent-voice",
+  "version": "1.0.0",
+  "description": "Make your coding agent talk to you: a smart speaker says when a long task finishes or when the agent needs you.",
+  "type": "module",
+  "bin": { "agent-voice": "bin/agent-voice.js" },
+  "files": ["bin", "src", "docs/adapters.md", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "scripts": { "test": "node --test" },
+  "repository": { "type": "git", "url": "git+https://github.com/LucasZaia/agent-voice.git" },
+  "keywords": ["claude-code", "codex", "alexa", "home-assistant", "tts", "notifications"],
+  "license": "MIT",
+  "publishConfig": { "access": "public" }
+}

package/src/adapters/claude-code.js

@@ -0,0 +1,103 @@
+// Translates Claude Code hook payloads into canonical events. Pure: it reads
+// the payload, returns one event, and keeps no state. Everything it knows about
+// Claude Code — hook names, field names, where the session title hides — is here.
+import { openSync, readSync, fstatSync, closeSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { str, projectOf } from './common.js';
+
+export const name = 'claude-code';
+
+export const hooks = [
+  { event: 'UserPromptSubmit', sub: 'start', timeout: 5 },
+  { event: 'Stop', sub: 'stop', async: true, timeout: 60 },
+  { event: 'SubagentStop', sub: 'task', async: true, timeout: 60 },
+  { event: 'TaskCompleted', sub: 'task', async: true, timeout: 60 },
+  { event: 'Notification', sub: 'notification', async: true, timeout: 60 },
+];
+
+export const notes = [];
+
+export function configFile(env = process.env, home = homedir()) {
+  return join(env.CLAUDE_CONFIG_DIR || join(home, '.claude'), 'settings.json');
+}
+
+export const detect = (env = process.env, home = homedir()) => existsSync(dirname(configFile(env, home)));
+
+export const hookReply = () => '';
+
+// Claude Code writes an AI-generated title into the transcript as
+// {"type":"ai-title","aiTitle":"..."} and rewrites it as the topic shifts.
+// The newest one wins, so the file is read backwards in chunks: transcripts
+// grow to many megabytes and the title is usually near the end.
+function titleOf(line) {
+  if (!line.includes('"type":"ai-title"')) return null;
+  try {
+    return str(JSON.parse(line).aiTitle).replace(/[_-]+/g, ' ');
+  } catch {
+    return '';
+  }
+}
+
+export function sessionName(transcriptPath, chunkSize = 64 * 1024) {
+  if (!transcriptPath) return '';
+  let fd;
+  try {
+    fd = openSync(transcriptPath, 'r');
+    let pos = fstatSync(fd).size;
+    // Pieces of the line being assembled, oldest first: everything after the
+    // newest newline not yet consumed. Joined once per line, so one huge line
+    // (a large tool result) is not copied again for every chunk.
+    let parts = [];
+    while (pos > 0) {
+      const size = Math.min(chunkSize, pos);
+      pos -= size;
+      const chunk = Buffer.alloc(size);
+      readSync(fd, chunk, 0, size, pos);
+      // Splitting on the newline byte keeps multi-byte UTF-8 characters whole.
+      let end = size;
+      for (let nl = chunk.lastIndexOf(10, end - 1); nl !== -1; nl = end > 0 ? chunk.lastIndexOf(10, end - 1) : -1) {
+        const title = titleOf(Buffer.concat([chunk.subarray(nl + 1, end), ...parts]).toString('utf8'));
+        if (title !== null) return title;
+        parts = [];
+        end = nl;
+      }
+      parts.unshift(chunk.subarray(0, end));
+    }
+    return titleOf(Buffer.concat(parts).toString('utf8')) ?? '';
+  } catch {
+    return '';
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+// SubagentStop / TaskCompleted rarely fill agent_type, so try each field in
+// turn; the core decides what to do when all are empty.
+const taskText = (p) => str(p.agent_type) || str(p.subagent_type) || str(p.description) || str(p.task_description);
+
+// Claude Code submits some turns itself — a background task finishing arrives as
+// a <task-notification> "prompt". Those blocks are not what the user asked for.
+const SYSTEM_BLOCKS = /<(task-notification|system-reminder)>[\s\S]*?<\/\1>/g;
+const requestText = (p) => str(p.prompt).replace(SYSTEM_BLOCKS, '').trim();
+
+const MAPPING = {
+  start: ['turn_start', requestText],
+  stop: ['task_done', () => ''],
+  task: ['background_done', taskText],
+  notification: ['needs_input', (p) => str(p.message)],
+};
+
+export function translate(sub, payload, home = homedir()) {
+  if (!Object.hasOwn(MAPPING, sub)) return null;
+  const p = payload && typeof payload === 'object' ? payload : {};
+  const [type, text] = MAPPING[sub];
+  return {
+    type,
+    agent: name,
+    session_id: str(p.session_id),
+    session_name: sessionName(str(p.transcript_path)),
+    project: projectOf(p.cwd, home),
+    text: text(p),
+  };
+}

package/src/adapters/codex.js

@@ -0,0 +1,43 @@
+// Translates Codex CLI hook payloads into canonical events. Codex hooks share
+// Claude Code's shape; the differences are the event names, no ai-title in the
+// transcript (Codex calls its format unstable), and Stop wanting JSON back.
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { str, projectOf } from './common.js';
+
+export const name = 'codex';
+
+export const hooks = [
+  { event: 'UserPromptSubmit', sub: 'start', timeout: 5 },
+  { event: 'Stop', sub: 'stop', async: true, timeout: 60 },
+  { event: 'PermissionRequest', sub: 'permission', async: true, timeout: 60 },
+];
+
+export const notes = ['Codex skips hooks it has not trusted yet: open Codex and run /hooks to review and trust them.'];
+
+export function configFile(env = process.env, home = homedir()) {
+  return join(env.CODEX_HOME || join(home, '.codex'), 'hooks.json');
+}
+
+export const detect = (env = process.env, home = homedir()) => existsSync(dirname(configFile(env, home)));
+
+// Codex treats non-JSON stdout from a Stop hook as invalid.
+export const hookReply = (sub) => (sub === 'stop' ? '{}' : '');
+
+// Worded like Claude Code's notice so the core's translation applies:
+// "..., para usar o Bash."
+const permissionText = (p) => (str(p.tool_name) ? `needs your permission to use ${str(p.tool_name)}` : 'needs your permission');
+
+const MAPPING = {
+  start: ['turn_start', (p) => str(p.prompt)],
+  stop: ['task_done', () => ''],
+  permission: ['needs_input', permissionText],
+};
+
+export function translate(sub, payload, home = homedir()) {
+  if (!Object.hasOwn(MAPPING, sub)) return null;
+  const p = payload && typeof payload === 'object' ? payload : {};
+  const [type, text] = MAPPING[sub];
+  return { type, agent: name, session_id: str(p.session_id), session_name: '', project: projectOf(p.cwd, home), text: text(p) };
+}

package/src/adapters/common.js

@@ -0,0 +1,14 @@
+import { homedir } from 'node:os';
+
+export const str = (v) => (typeof v === 'string' ? v : '');
+
+// The last segment of cwd. The home directory is not a project — announcing
+// "do projeto lucas-zaia" would be nonsense.
+// Windows paths compare case-insensitively and with either separator.
+export function projectOf(cwd, home = homedir(), platform = process.platform) {
+  const dir = str(cwd).replace(/[\\/]+$/, '');
+  const norm = (p) => (platform === 'win32' ? p.replace(/[\\/]+/g, '\\').replace(/\\$/, '').toLowerCase() : p.replace(/\/+$/, ''));
+  if (!dir || norm(dir) === norm(String(home))) return '';
+  const parts = dir.split(/[\\/]/);
+  return parts[parts.length - 1];
+}

package/src/adapters/hooks-json.js

@@ -0,0 +1,158 @@
+// Merges agent-voice's hooks into an agent's JSON config (Claude Code's
+// settings.json, Codex's hooks.json — same shape). Rules: never touch foreign
+// hooks, never duplicate ours, back up before writing, and on anything
+// unexpected abort without writing a byte.
+import {
+  readFileSync, writeFileSync, copyFileSync, mkdirSync, existsSync, renameSync, rmSync, statSync, chmodSync, realpathSync,
+  constants,
+} from 'node:fs';
+import { dirname } from 'node:path';
+
+export const hookCommand = (env = process.env) => env.AV_HOOK_COMMAND || 'agent-voice';
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+export const isLegacy = (command) => typeof command === 'string' && /bin[\\/]notify"?\s/.test(command);
+
+export function isOurs(command, agent) {
+  if (typeof command !== 'string') return false;
+  if (!new RegExp(`\\bnotify"?\\s+${escapeRe(agent)}(\\s|$)`).test(command)) return false;
+  return /agent-voice/.test(command) || isLegacy(command);
+}
+
+function eventsOf(settings, file = 'settings') {
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    throw new Error(`${file}: expected a JSON object — nothing was written`);
+  }
+  if (settings.hooks === undefined) return {};
+  const { hooks } = settings;
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) {
+    throw new Error(`${file}: "hooks" is not an object — nothing was written`);
+  }
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) throw new Error(`${file}: hooks.${event} is not a list — nothing was written`);
+  }
+  return hooks;
+}
+
+export function removeHooks(settings, agent, file) {
+  const hooks = eventsOf(settings, file);
+  const next = {};
+  let removed = 0;
+  for (const [event, groups] of Object.entries(hooks)) {
+    const kept = [];
+    for (const group of groups) {
+      if (!group || !Array.isArray(group.hooks)) { kept.push(group); continue; }
+      const ours = group.hooks.filter((x) => isOurs(x?.command, agent));
+      if (ours.length === 0) { kept.push(group); continue; }
+      removed += ours.length;
+      const rest = group.hooks.filter((x) => !isOurs(x?.command, agent));
+      if (rest.length) kept.push({ ...group, hooks: rest });
+    }
+    if (kept.length || groups.length === 0) next[event] = kept;
+  }
+  if (removed === 0) return { settings, removed };
+  const out = { ...settings };
+  if (Object.keys(next).length) out.hooks = next;
+  else delete out.hooks;
+  return { settings: out, removed };
+}
+
+export function mergeHooks(settings, agent, defs, command, file) {
+  const { settings: base } = removeHooks(settings, agent, file);
+  const hooks = { ...(base.hooks ?? {}) };
+  for (const d of defs) {
+    const entry = { type: 'command', command: `${command} notify ${agent} ${d.sub}`, ...(d.async ? { async: true } : {}), timeout: d.timeout };
+    hooks[d.event] = [...(hooks[d.event] ?? []), { hooks: [entry] }];
+  }
+  return { ...base, hooks };
+}
+
+export function hookStatus(settings, agent, defs, file) {
+  const hooks = eventsOf(settings, file);
+  const ours = Object.values(hooks).flat()
+    .flatMap((g) => (g && Array.isArray(g.hooks) ? g.hooks : []))
+    .filter((x) => isOurs(x?.command, agent));
+  if (ours.some((x) => isLegacy(x.command))) return 'legacy';
+  const has = (d) => ((hooks[d.event] ?? [])
+    .some((g) => g && Array.isArray(g.hooks) && g.hooks.some((x) => isOurs(x?.command, agent) && x.command.trimEnd().endsWith(` ${agent} ${d.sub}`))));
+  const n = defs.filter(has).length;
+  if (n === defs.length) return 'connected';
+  return n === 0 ? 'not connected' : 'partially connected';
+}
+
+function readSettings(file) {
+  if (!existsSync(file)) return { settings: {}, existed: false };
+  // Windows editors like to start UTF-8 files with a BOM; JSON.parse does not.
+  const raw = readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+  if (raw.trim() === '') return { settings: {}, existed: true };
+  let settings;
+  try {
+    settings = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`${file}: invalid JSON (${e.message}) — nothing was written`);
+  }
+  eventsOf(settings, file);
+  return { settings, existed: true };
+}
+
+const pad2 = (n) => String(n).padStart(2, '0');
+const stamp = (d) => `${d.getFullYear()}${pad2(d.getMonth() + 1)}${pad2(d.getDate())}-${pad2(d.getHours())}${pad2(d.getMinutes())}${pad2(d.getSeconds())}`;
+
+// Never overwrites an earlier backup: connect and disconnect in the same
+// second must both keep theirs.
+function backupOf(file, now) {
+  const base = `${file}.bak-${stamp(now)}`;
+  for (let i = 1; ; i++) {
+    const backup = i === 1 ? base : `${base}-${i}`;
+    try {
+      copyFileSync(file, backup, constants.COPYFILE_EXCL);
+      return backup;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+    }
+  }
+}
+
+// Written to a temp file and renamed over the original, so a crash or a full
+// disk never leaves the agent with half a settings file. A symlinked file
+// (dotfile repos) is written at its target and stays a symlink.
+function replaceFile(file, text) {
+  const target = existsSync(file) ? realpathSync(file) : file;
+  const tmp = `${target}.tmp-${process.pid}`;
+  try {
+    writeFileSync(tmp, text);
+    try { chmodSync(tmp, statSync(target).mode & 0o7777); } catch { /* new file, or no modes here */ }
+    renameSync(tmp, target);
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    throw e;
+  }
+}
+
+function writeSettings(file, existed, before, next, now) {
+  if (JSON.stringify(before) === JSON.stringify(next)) return { changed: false, backup: null };
+  mkdirSync(dirname(file), { recursive: true });
+  const backup = existed ? backupOf(file, now) : null;
+  replaceFile(file, `${JSON.stringify(next, null, 2)}\n`);
+  return { changed: true, backup };
+}
+
+export function connectFile(file, agent, defs, { command, now = new Date() } = {}) {
+  const { settings, existed } = readSettings(file);
+  return writeSettings(file, existed, settings, mergeHooks(settings, agent, defs, command, file), now);
+}
+
+export function disconnectFile(file, agent, { now = new Date() } = {}) {
+  if (!existsSync(file)) return { changed: false, backup: null };
+  const { settings, existed } = readSettings(file);
+  return writeSettings(file, existed, settings, removeHooks(settings, agent, file).settings, now);
+}
+
+export function fileStatus(file, agent, defs) {
+  try {
+    return hookStatus(readSettings(file).settings, agent, defs, file);
+  } catch (e) {
+    return `unreadable (${e.message})`;
+  }
+}

package/src/adapters/index.js

@@ -0,0 +1,4 @@
+import * as claudeCode from './claude-code.js';
+import * as codex from './codex.js';
+
+export const ADAPTERS = { 'claude-code': claudeCode, codex };

package/src/cli/config.js

@@ -0,0 +1,33 @@
+import { loadConfig, saveConfig, NUMERIC_KEYS } from '../config.js';
+
+const USAGE = `usage: agent-voice config get [key] | set <key> <value>   (keys: ${Object.keys(NUMERIC_KEYS).join(', ')})`;
+
+export function runConfig(args, { env, out }) {
+  const [sub, key, value] = args;
+  if (sub === 'get') {
+    const cfg = loadConfig(env);
+    if (!key) {
+      for (const k of Object.keys(NUMERIC_KEYS)) out(`${k}=${cfg[k]}`);
+      out(`outputs=${cfg.outputs.join(' ')}`);
+      return 0;
+    }
+    if (key === 'outputs') out(cfg.outputs.join(' '));
+    else if (Object.hasOwn(NUMERIC_KEYS, key)) out(String(cfg[key]));
+    else throw new Error(`unknown key "${key}". ${USAGE}`);
+    return 0;
+  }
+  if (sub === 'set') {
+    if (!Object.hasOwn(NUMERIC_KEYS, key ?? '')) {
+      throw new Error(`unknown key "${key}" (settable: ${Object.keys(NUMERIC_KEYS).join(', ')}; outputs are managed with "agent-voice output enable|disable")`);
+    }
+    if (!/^[0-9]+$/.test(value ?? '')) {
+      throw new Error(`${key} must be a whole number of ${key === 'maxSpeechChars' ? 'characters' : 'seconds'}`);
+    }
+    saveConfig({ [key]: Number(value) }, env);
+    out(`${key}=${value}`);
+    const envName = NUMERIC_KEYS[key];
+    if (env[envName] !== undefined) out(`Note: ${envName}=${env[envName]} overrides it in this environment.`);
+    return 0;
+  }
+  throw new Error(USAGE);
+}

package/src/cli/connect.js

@@ -0,0 +1,42 @@
+import { ADAPTERS } from '../adapters/index.js';
+import { connectFile, disconnectFile, hookCommand } from '../adapters/hooks-json.js';
+import { findOnPath } from '../platform.js';
+
+export function adapterFor(name) {
+  if (!Object.hasOwn(ADAPTERS, name ?? '')) {
+    throw new Error(`unknown agent "${name}" (available: ${Object.keys(ADAPTERS).join(', ')})`);
+  }
+  return ADAPTERS[name];
+}
+
+export async function connectAgent(adapter, { env, out, prompt, yes = false }) {
+  const file = adapter.configFile(env);
+  const command = hookCommand(env);
+  out(`${adapter.name}: these hooks will be added to ${file}`);
+  for (const d of adapter.hooks) out(`  ${d.event.padEnd(18)} → ${command} notify ${adapter.name} ${d.sub}`);
+  if (!yes && !(await prompt.confirm('Apply?', true))) {
+    out('Nothing changed.');
+    return false;
+  }
+  const { changed, backup } = connectFile(file, adapter.name, adapter.hooks, { command });
+  out(changed ? `Connected ${adapter.name}.${backup ? ` Backup: ${backup}` : ''}` : `${adapter.name} was already connected; nothing changed.`);
+  if (command === 'agent-voice' && !findOnPath('agent-voice', env)) {
+    out('Warning: "agent-voice" is not on your PATH, so these hooks will not run. Install with "npm i -g @lucas_zaia/agent-voice".');
+  }
+  for (const note of adapter.notes) out(`Note: ${note}`);
+  return true;
+}
+
+export async function runConnect(args, { env, out, prompt }) {
+  const adapter = adapterFor(args.find((a) => !a.startsWith('--')));
+  await connectAgent(adapter, { env, out, prompt, yes: args.includes('--yes') });
+  return 0;
+}
+
+export async function runDisconnect(args, { env, out }) {
+  const adapter = adapterFor(args[0]);
+  const file = adapter.configFile(env);
+  const { changed, backup } = disconnectFile(file, adapter.name);
+  out(changed ? `Removed agent-voice's hooks from ${file}. Backup: ${backup}` : `${adapter.name} had no agent-voice hooks; nothing changed.`);
+  return 0;
+}