@drakulavich/kesha-voice-kit 1.18.1 → 1.18.3

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/logo.png" alt="Kesha Voice Kit" width="200">
+  <img src="docs/assets/logo.png" alt="Kesha Voice Kit" width="200">
 </p>
 
 <h1 align="center">Kesha Voice Kit</h1>
@@ -11,12 +11,12 @@
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
 </p>
 
-<p align="center"><b>Open-source voice toolkit.</b> Optimized for Apple Silicon (CoreML), with ONNX fallback on supported Linux/Windows builds.<br>A collection of small, fast, open-source audio models — packaged as CLI tools and an <a href="https://github.com/openclaw/openclaw">OpenClaw</a> skill for LLM agents.</p>
+<p align="center"><b>Give your local tools and LLM agents a voice.</b><br>Fast speech-to-text, text-to-speech, voice-activity detection, and language detection in one local-first CLI: Apple Silicon CoreML first, ONNX fallback on supported Linux/Windows builds.</p>
 
-- **Speech-to-text** — 25 languages, ~15x faster than Whisper on Apple Silicon, ~2.5x on CPU
-- **Text-to-speech** — Kokoro (EN) + Vosk-TTS (RU) + macOS system voices, SSML preview
-- **Rust engine** — single 20MB binary, no ffmpeg, no Python, no native Node addons
-- **OpenClaw-ready** — plug into your LLM agent as a voice processing skill
+- **Transcribe locally** — 25 languages, up to ~19x faster than Whisper on Apple Silicon, ~2.5x on CPU
+- **Speak back** — Kokoro (EN), Vosk-TTS (RU), macOS system voices, and SSML preview
+- **Plug into agents** — ship voice workflows as CLI commands or an <a href="https://github.com/openclaw/openclaw">OpenClaw</a> skill
+- **Small Rust engine** — single ~20MB binary, no ffmpeg, no Python, no native Node addons
 
 See [Product positioning](docs/product-positioning.md) for supported workflows, non-goals, maturity labels, and the platform matrix.
 
@@ -51,6 +51,32 @@ kesha audio.ogg     # transcript to stdout
 
 Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-mirror.md).
 
+## Shell Completions and Manpage
+
+The npm package includes bash, zsh, and fish completions plus `kesha(1)`.
+The CLI can print the packaged files, so install paths do not depend on the
+Bun global package layout:
+
+```bash
+# bash
+mkdir -p ~/.local/share/bash-completion/completions
+kesha completions bash > ~/.local/share/bash-completion/completions/kesha
+
+# zsh
+mkdir -p ~/.zsh/completions
+kesha completions zsh > ~/.zsh/completions/_kesha
+# add to ~/.zshrc once: fpath=(~/.zsh/completions $fpath); autoload -Uz compinit; compinit
+
+# fish
+mkdir -p ~/.config/fish/completions
+kesha completions fish > ~/.config/fish/completions/kesha.fish
+
+# manpage
+mkdir -p ~/.local/share/man/man1
+kesha manpage > ~/.local/share/man/man1/kesha.1
+mandb ~/.local/share/man 2>/dev/null || true
+```
+
 ## Homebrew Install
 
 Homebrew installs the Bun-based CLI wrapper. Engine and model downloads remain
@@ -77,6 +103,39 @@ kesha support-bundle --output kesha-support.tar.gz
 
 `support-bundle` creates a redacted `.tar.gz` archive for GitHub issues. It includes runtime, engine, cache, optional-component, Stats status, and known Kesha environment settings. It does not include audio, transcripts, model files, or the Stats database.
 
+## Local Stats privacy and lifecycle
+
+Kesha Stats is disabled by default. When you opt in with `kesha stats enable`,
+Kesha writes a local SQLite database only on your machine:
+
+```bash
+kesha stats status
+kesha stats week
+kesha stats errors
+kesha stats export --format json   # or csv
+kesha stats retention 30           # default: 90 days
+kesha stats retention off          # keep until reset
+kesha stats reset                  # delete recorded stats rows
+kesha stats vacuum                 # compact the SQLite file
+```
+
+The database stores content-free operational records only: command name
+(`transcribe` or `say`), timestamps, success/failure status, app version, item
+count, anonymous stage timings, input/output artifact kind, file extension,
+size, optional duration/sample-rate/channel counts, and sanitized error
+class/code/message.
+
+Stats never stores audio bytes, transcripts, input text, generated speech text,
+file names, full file paths, raw stdout/stderr, environment variables, model
+files, API tokens, or cloud identifiers. `support-bundle` reports Stats status
+only; it never includes the Stats SQLite database.
+
+By default, Stats prunes rows older than 90 days before writing or exporting
+data. Use `kesha stats retention <days>` to change the TTL or `kesha stats
+retention off` to disable TTL pruning. `kesha stats reset` deletes recorded
+runs, artifacts, timings, and errors while preserving settings such as enabled
+state and retention.
+
 ## Nix Install
 
 Alternative reproducible-build path on `aarch64-darwin` / `x86_64-linux`:
@@ -150,9 +209,9 @@ $ kesha freedom.ogg tahiti.ogg
 Таити, Таити! Не были мы ни в какой Таити! Нас и тут неплохо кормят.
 ```
 
-Stdout: transcript. Stderr: errors. Pipe-friendly. Also available as `parakeet` command (backward-compatible alias).
+Stdout: transcript. Stderr: errors. Pipe-friendly.
 
-For long / silence-heavy audio, use `--vad` (auto-on past 120 s). Details: [docs/vad.md](docs/vad.md).
+For long / silence-heavy audio, install VAD (`kesha install --vad`) and run without `--no-vad`. Kesha auto-uses VAD past 120 s when installed; without VAD, very long audio falls back to fixed ASR chunks. Details: [docs/vad.md](docs/vad.md).
 
 **Speaker diarization** (darwin-arm64, post-v1.12.0):
 
@@ -208,11 +267,11 @@ macOS system voices, SSML, voice listing, and the full voice catalogue: [docs/tt
 
 ## Performance
 
-> **~15x faster than Whisper** on Apple Silicon (M3 Pro), **~2.5x faster** on CPU
+> **Up to ~19x faster than Whisper** on Apple Silicon (M2), **~2.5x faster** on CPU
 
 Compared against Whisper `large-v3-turbo` — all engines auto-detect language.
 
-![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](assets/benchmark.svg)
+![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](docs/assets/benchmark.svg)
 
 See [BENCHMARK.md](BENCHMARK.md) for the full per-file breakdown (Russian + English).
 
@@ -238,6 +297,7 @@ Audio decoding via [symphonia](https://github.com/pdeljanov/Symphonia) — WAV,
 ## Integrations
 
 - **OpenClaw** — give your LLM agent ears. Install & config: [docs/openclaw.md](docs/openclaw.md).
+- **Hermes Agent** — local STT/TTS through Hermes command providers. Setup: [docs/hermes.md](docs/hermes.md).
 - **Raycast** (macOS) — transcribe selected audio & speak clipboard from the launcher. Source + install: [`raycast/`](raycast/).
 
 ## Programmatic API

package/completions/kesha.bash

@@ -0,0 +1,38 @@
+# bash completion for kesha.
+# Source this file or copy it into your bash-completion directory.
+
+_kesha_completion() {
+  local cur command opts commands
+  COMPREPLY=()
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  command="${COMP_WORDS[1]}"
+  commands="completions doctor install manpage record say stats status support-bundle"
+
+  if [[ "$COMP_CWORD" -eq 1 ]]; then
+    if [[ "$cur" == -* ]]; then
+      COMPREPLY=( $(compgen -W "--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad" -- "$cur") )
+    else
+      COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+    fi
+    return 0
+  fi
+
+  case "$command" in
+    completions) opts="--help -h" ;;
+    doctor) opts="--help -h --json --redact" ;;
+    install) opts="--help -h --coreml --onnx --no-cache --plan --tts --vad --diarize" ;;
+    manpage) opts="--help -h" ;;
+    record) opts="--help -h --out --max-seconds --debug" ;;
+    say) opts="--help -h --voice --lang --out --rate --list-voices --ssml --format --bitrate --sample-rate --no-expand-abbrev --verbose --debug" ;;
+    stats) opts="--help -h --format" ;;
+    status) opts="--help -h --disk" ;;
+    support-bundle) opts="--help -h --output" ;;
+    *) opts="--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad" ;;
+  esac
+
+  if [[ "$cur" == -* ]]; then
+    COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
+  fi
+}
+
+complete -F _kesha_completion kesha

package/completions/kesha.fish

@@ -0,0 +1,71 @@
+# fish completion for kesha.
+complete -c kesha -f
+complete -c kesha -n '__fish_use_subcommand' -a 'completions' -d 'Print shell completion script for bash, zsh, or fish'
+complete -c kesha -n '__fish_use_subcommand' -a 'doctor' -d 'Collect support diagnostics without changing local state'
+complete -c kesha -n '__fish_use_subcommand' -a 'install' -d 'Download inference engine and models'
+complete -c kesha -n '__fish_use_subcommand' -a 'manpage' -d 'Print the kesha(1) manpage'
+complete -c kesha -n '__fish_use_subcommand' -a 'record' -d 'Record microphone audio to a WAV file'
+complete -c kesha -n '__fish_use_subcommand' -a 'say' -d 'Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
+complete -c kesha -n '__fish_use_subcommand' -a 'stats' -d 'Manage local anonymous Kesha Stats'
+complete -c kesha -n '__fish_use_subcommand' -a 'status' -d 'Show backend installation status'
+complete -c kesha -n '__fish_use_subcommand' -a 'support-bundle' -d 'Create a redacted diagnostics archive for support'
+complete -c kesha -n '__fish_use_subcommand' -l help -d 'Show help'
+complete -c kesha -n '__fish_use_subcommand' -s h -d 'Show help'
+complete -c kesha -n '__fish_use_subcommand' -l version -d 'Show version'
+complete -c kesha -n '__fish_use_subcommand' -s v -d 'Show version'
+complete -c kesha -n '__fish_use_subcommand' -l json -d 'Output results as JSON'
+complete -c kesha -n '__fish_use_subcommand' -l toon -d 'Output results as TOON (compact, LLM-friendly encoding of the same data as --json)'
+complete -c kesha -n '__fish_use_subcommand' -l timestamps -d 'Include timestamped transcript segments in JSON/TOON output'
+complete -c kesha -n '__fish_use_subcommand' -l speakers -d 'Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).'
+complete -c kesha -n '__fish_use_subcommand' -l include-errors -d 'With --json, output { results, errors } so scripts can read per-file failures without parsing stderr'
+complete -c kesha -n '__fish_use_subcommand' -l verbose -d 'Show language detection details'
+complete -c kesha -n '__fish_use_subcommand' -l format -r -d 'Output format: transcript | json | toon (long-form alias for --json / --toon)'
+complete -c kesha -n '__fish_use_subcommand' -l lang -r -d 'Expected language code (ISO 639-1), warn if mismatch'
+complete -c kesha -n '__fish_use_subcommand' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
+complete -c kesha -n '__fish_use_subcommand' -l vad -d 'Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.'
+complete -c kesha -n '__fish_use_subcommand' -l no-vad -d 'Force full-file ASR for short/medium files; long audio fails early'
+complete -c kesha -n '__fish_seen_subcommand_from completions' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from completions' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from doctor' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from doctor' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from doctor' -l json -d 'Output diagnostics as JSON'
+complete -c kesha -n '__fish_seen_subcommand_from doctor' -l redact -d 'Redact secrets and user-home paths from diagnostic output'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from install' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l coreml -d 'Force CoreML backend (macOS arm64)'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l onnx -d 'Force ONNX backend'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l no-cache -d 'Re-download even if cached'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l plan -d 'Show download, disk, and warm-up plan without changing local state'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l tts -d 'Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l vad -d 'Also install Silero VAD (~2.3MB) for long-audio preprocessing'
+complete -c kesha -n '__fish_seen_subcommand_from install' -l diarize -d 'Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)'
+complete -c kesha -n '__fish_seen_subcommand_from manpage' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from manpage' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from record' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l out -r -d 'Write recorded WAV audio to this path'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l max-seconds -r -d 'Maximum recording duration in seconds'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from say' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l voice -r -d 'Voice id, e.g. en-am_michael'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l lang -r -d 'BCP 47 language code (default en-us)'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l out -r -d 'Write audio to file instead of stdout'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l rate -r -d 'Speaking rate 0.5–2.0'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l list-voices -d 'List installed voices and exit'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l ssml -d 'Parse input as SSML (supports <speak>, <break>; strips unknown tags)'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l bitrate -r -d 'Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l sample-rate -r -d 'Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l no-expand-abbrev -d 'Disable Russian acronym auto-expansion (ВОЗ → \'вэ о зэ\') for ru-vosk-* voices. <say-as interpret-as=\'characters\'> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l verbose -d 'Log TTS synthesis time to stderr'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
+complete -c kesha -n '__fish_seen_subcommand_from stats' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from stats' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from stats' -l format -r -d 'Export format: json | csv'
+complete -c kesha -n '__fish_seen_subcommand_from status' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from status' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from status' -l disk -d 'Include recursive cache disk usage'
+complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -l help -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -s h -d 'Show help'
+complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -l output -r -d 'Write archive to this .tar.gz path'

package/completions/kesha.zsh

@@ -0,0 +1,125 @@
+#compdef kesha
+# zsh completion for kesha.
+
+_kesha() {
+  local -a commands
+  commands=(
+    'completions:Print shell completion script for bash, zsh, or fish'
+    'doctor:Collect support diagnostics without changing local state'
+    'install:Download inference engine and models'
+    'manpage:Print the kesha(1) manpage'
+    'record:Record microphone audio to a WAV file'
+    'say:Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
+    'stats:Manage local anonymous Kesha Stats'
+    'status:Show backend installation status'
+    'support-bundle:Create a redacted diagnostics archive for support'
+  )
+
+  if (( CURRENT == 2 )); then
+    if [[ "$words[CURRENT]" == -* ]]; then
+      _arguments '--help[Show help]' \
+      '-h[Show help]' \
+      '--version[Show version]' \
+      '-v[Show version]' \
+      '--json[Output results as JSON]' \
+      '--toon[Output results as TOON (compact, LLM-friendly encoding of the same data as --json)]' \
+      '--timestamps[Include timestamped transcript segments in JSON/TOON output]' \
+      '--speakers[Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).]' \
+      '--include-errors[With --json, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
+      '--verbose[Show language detection details]' \
+      '--format=[Output format: transcript | json | toon (long-form alias for --json / --toon)]:format:' \
+      '--lang=[Expected language code (ISO 639-1), warn if mismatch]:lang:' \
+      '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]' \
+      '--vad[Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.]' \
+      '--no-vad[Force full-file ASR for short/medium files; long audio fails early]'
+    else
+      _describe -t commands 'kesha command' commands
+    fi
+    return
+  fi
+
+  case "$words[2]" in
+    completions)
+      _arguments '--help[Show help]' \
+        '-h[Show help]'
+      ;;
+    doctor)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--json[Output diagnostics as JSON]' \
+        '--redact[Redact secrets and user-home paths from diagnostic output]'
+      ;;
+    install)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--coreml[Force CoreML backend (macOS arm64)]' \
+        '--onnx[Force ONNX backend]' \
+        '--no-cache[Re-download even if cached]' \
+        '--plan[Show download, disk, and warm-up plan without changing local state]' \
+        '--tts[Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)]' \
+        '--vad[Also install Silero VAD (~2.3MB) for long-audio preprocessing]' \
+        '--diarize[Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)]'
+      ;;
+    manpage)
+      _arguments '--help[Show help]' \
+        '-h[Show help]'
+      ;;
+    record)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--out=[Write recorded WAV audio to this path]:out:' \
+        '--max-seconds=[Maximum recording duration in seconds]:max seconds:' \
+        '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]'
+      ;;
+    say)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--voice=[Voice id, e.g. en-am_michael]:voice:' \
+        '--lang=[BCP 47 language code (default en-us)]:lang:' \
+        '--out=[Write audio to file instead of stdout]:out:' \
+        '--rate=[Speaking rate 0.5–2.0]:rate:' \
+        '--list-voices[List installed voices and exit]' \
+        '--ssml[Parse input as SSML (supports <speak>, <break>; strips unknown tags)]' \
+        '--format=[Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.]:format:' \
+        '--bitrate=[Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.]:bitrate:' \
+        '--sample-rate=[Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.]:sample rate:' \
+        '--no-expand-abbrev[Disable Russian acronym auto-expansion (ВОЗ → '\''вэ о зэ'\'') for ru-vosk-* voices. <say-as interpret-as='\''characters'\''> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.]' \
+        '--verbose[Log TTS synthesis time to stderr]' \
+        '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]'
+      ;;
+    stats)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--format=[Export format: json | csv]:format:'
+      ;;
+    status)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--disk[Include recursive cache disk usage]'
+      ;;
+    support-bundle)
+      _arguments '--help[Show help]' \
+        '-h[Show help]' \
+        '--output=[Write archive to this .tar.gz path]:output:'
+      ;;
+    *)
+      _arguments '--help[Show help]' \
+      '-h[Show help]' \
+      '--version[Show version]' \
+      '-v[Show version]' \
+      '--json[Output results as JSON]' \
+      '--toon[Output results as TOON (compact, LLM-friendly encoding of the same data as --json)]' \
+      '--timestamps[Include timestamped transcript segments in JSON/TOON output]' \
+      '--speakers[Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).]' \
+      '--include-errors[With --json, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
+      '--verbose[Show language detection details]' \
+      '--format=[Output format: transcript | json | toon (long-form alias for --json / --toon)]:format:' \
+      '--lang=[Expected language code (ISO 639-1), warn if mismatch]:lang:' \
+      '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]' \
+      '--vad[Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.]' \
+      '--no-vad[Force full-file ASR for short/medium files; long audio fails early]'
+      ;;
+  esac
+}
+
+_kesha "$@"

package/docs/product-positioning.md

@@ -8,6 +8,7 @@ The product promise is not "one model for every audio problem." The promise is a
 
 - Developers and agent builders who need local speech-to-text for voice messages, meetings, support clips, or batch audio files.
 - OpenClaw users who want private, low-latency voice-message transcription through a CLI model route.
+- Hermes Agent users who want command-provider STT/TTS without cloud audio uploads.
 - macOS users who want the fastest path on Apple Silicon through CoreML, with a CPU/ONNX fallback on Linux and Windows.
 - Automation-heavy users who prefer stdout/stderr contracts, JSON/TOON output, and shell-friendly commands over a hosted dashboard.
 - Projects that can accept explicit model downloads and local cache management in exchange for no API keys and no cloud audio upload.
@@ -24,6 +25,7 @@ The product promise is not "one model for every audio problem." The promise is a
 | Use macOS system voices without model downloads | Stable on macOS | `kesha say --voice macos-*` |
 | Label speakers in meeting transcripts | Preview, darwin-arm64 only | `kesha --json --vad --speakers meeting.m4a` |
 | Integrate with OpenClaw as a local voice model | Stable integration surface, user-configured route | `docs/openclaw.md` |
+| Integrate with Hermes Agent as local STT/TTS commands | Stable CLI surface, user-configured route | `docs/hermes.md` |
 | Use Raycast actions for selected-file transcription or clipboard speech | Beta, macOS only | `raycast/` extension |
 | Install through Nix instead of Bun/npm | Beta, selected systems | `docs/nix-install.md` |
 
@@ -51,6 +53,7 @@ The product promise is not "one model for every audio problem." The promise is a
 | Speaker diarization | Preview | darwin-arm64 only; cluster IDs are stable within one file only. |
 | Raycast extension | Beta | Convenience UI over the CLI; macOS-only. |
 | OpenClaw plugin | Stable integration surface | Discovery is packaged; actual audio route remains explicit user config. |
+| Hermes Agent command provider | Stable CLI surface | Hermes owns the command-provider lifecycle; Kesha supplies the local STT/TTS commands. |
 | Nix flake | Beta | Reproducible alternate install path for selected systems; Bun/npm remains canonical. |
 
 ## Platform matrix
@@ -66,6 +69,7 @@ The product promise is not "one model for every audio problem." The promise is a
 | Speaker diarization | Preview, darwin-arm64 only | Not supported | Not supported | Not supported | Not wired into the Nix build yet |
 | Raycast extension | Supported | Not shipped | Not applicable | Not applicable | Not applicable |
 | OpenClaw integration | Supported through CLI route | Not shipped | Supported through CLI route | Supported through CLI route | Use the installed `kesha` command from the chosen path |
+| Hermes Agent integration | Supported through command providers | Not shipped | Supported through command providers | Supported through command providers | Use the installed `kesha` command from the chosen path |
 
 `macOS x64` means Intel Macs. Kesha does not currently publish a `darwin-x64` engine binary, so Intel Macs are intentionally marked as not shipped rather than implied to use the ONNX fallback.
 

package/man/kesha.1

@@ -0,0 +1,174 @@
+.TH KESHA 1 "May 2026" "kesha 1.18.3" "User Commands"
+.SH NAME
+kesha \- open-source local voice toolkit
+.SH SYNOPSIS
+.B kesha
+[OPTIONS] AUDIO_FILE...
+.br
+.B kesha
+COMMAND [OPTIONS]
+.SH DESCRIPTION
+Kesha Voice Kit is a local speech-to-text and text-to-speech toolkit with a Bun TypeScript CLI and a Rust engine.
+.SH COMMANDS
+.TP
+.B completions
+Print shell completion script for bash, zsh, or fish
+.TP
+.B doctor
+Collect support diagnostics without changing local state
+.TP
+.B install
+Download inference engine and models
+.TP
+.B manpage
+Print the kesha(1) manpage
+.TP
+.B record
+Record microphone audio to a WAV file
+.TP
+.B say
+Synthesize speech from text (TTS). Writes audio to stdout (or \-\-out file). Defaults to WAV; use \-\-format ogg\-opus for messenger\-ready voice notes.
+.TP
+.B stats
+Manage local anonymous Kesha Stats
+.TP
+.B status
+Show backend installation status
+.TP
+.B support-bundle
+Create a redacted diagnostics archive for support
+.SH OPTIONS
+.TP
+.B \-\-json
+Output results as JSON
+.TP
+.B \-\-toon
+Output results as TOON (compact, LLM\-friendly encoding of the same data as \-\-json)
+.TP
+.B \-\-timestamps
+Include timestamped transcript segments in JSON/TOON output
+.TP
+.B \-\-speakers
+Include speaker labels in transcript segments. Requires \-\-json / \-\-toon / \-\-format json. Implies \-\-timestamps. Currently darwin\-arm64 only (#199).
+.TP
+.B \-\-include\-errors
+With \-\-json, output { results, errors } so scripts can read per\-file failures without parsing stderr
+.TP
+.B \-\-verbose
+Show language detection details
+.TP
+.B \-\-format
+Output format: transcript | json | toon (long\-form alias for \-\-json / \-\-toon)
+.TP
+.B \-\-lang
+Expected language code (ISO 639\-1), warn if mismatch
+.TP
+.B \-\-debug
+Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)
+.TP
+.B \-\-vad
+Force Silero VAD preprocessing (kesha install \-\-vad first). Without this, VAD auto\-engages on audio ≥ 120s.
+.TP
+.B \-\-no\-vad
+Force full\-file ASR for short/medium files; long audio fails early
+.SH SUBCOMMAND OPTIONS
+.SS doctor
+.TP
+.B \-\-json
+Output diagnostics as JSON
+.TP
+.B \-\-redact
+Redact secrets and user\-home paths from diagnostic output
+.SS install
+.TP
+.B \-\-coreml
+Force CoreML backend (macOS arm64)
+.TP
+.B \-\-onnx
+Force ONNX backend
+.TP
+.B \-\-no\-cache
+Re\-download even if cached
+.TP
+.B \-\-plan
+Show download, disk, and warm\-up plan without changing local state
+.TP
+.B \-\-tts
+Also install TTS models (Kokoro EN + Vosk\-TTS RU, ~990MB)
+.TP
+.B \-\-vad
+Also install Silero VAD (~2.3MB) for long\-audio preprocessing
+.TP
+.B \-\-diarize
+Also install the Sortformer streaming\-diarization model (~245MB, darwin\-arm64 only — #199)
+.SS record
+.TP
+.B \-\-out
+Write recorded WAV audio to this path
+.TP
+.B \-\-max\-seconds
+Maximum recording duration in seconds
+.TP
+.B \-\-debug
+Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)
+.SS say
+.TP
+.B \-\-voice
+Voice id, e.g. en\-am_michael
+.TP
+.B \-\-lang
+BCP 47 language code (default en\-us)
+.TP
+.B \-\-out
+Write audio to file instead of stdout
+.TP
+.B \-\-rate
+Speaking rate 0.5–2.0
+.TP
+.B \-\-list\-voices
+List installed voices and exit
+.TP
+.B \-\-ssml
+Parse input as SSML (supports <speak>, <break>; strips unknown tags)
+.TP
+.B \-\-format
+Output format: wav (default) or ogg\-opus (Telegram\-ready voice note). Inferred from \-\-out extension when omitted.
+.TP
+.B \-\-bitrate
+Opus bitrate in bits/sec (e.g. 32000). Only with \-\-format ogg\-opus.
+.TP
+.B \-\-sample\-rate
+Opus encoder sample rate (8000/12000/16000/24000/48000). Only with \-\-format ogg\-opus.
+.TP
+.B \-\-no\-expand\-abbrev
+Disable Russian acronym auto\-expansion (ВОЗ → 'вэ о зэ') for ru\-vosk\-* voices. <say\-as interpret\-as='characters'> still works. Applies to Russian (ru\-vosk\-*) and English (en\-*) voices.
+.TP
+.B \-\-verbose
+Log TTS synthesis time to stderr
+.TP
+.B \-\-debug
+Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)
+.SS stats
+.TP
+.B \-\-format
+Export format: json | csv
+.SS status
+.TP
+.B \-\-disk
+Include recursive cache disk usage
+.SS support-bundle
+.TP
+.B \-\-output
+Write archive to this .tar.gz path
+.SH FILES
+.TP
+.B completions/kesha.bash
+Bash completion script included in the npm package.
+.TP
+.B completions/kesha.zsh
+Zsh completion script included in the npm package.
+.TP
+.B completions/kesha.fish
+Fish completion script included in the npm package.
+.SH SEE ALSO
+.BR bun (1)

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.18.1",
-  "description": "Open-source voice toolkit. Speech-to-text (25 langs, ~19x faster than Whisper on Apple Silicon, ONNX fallback on CPU), text-to-speech (Kokoro + Vosk-TTS + ~180 macOS system voices, SSML), voice-activity detection, language detection (107 langs). Rust engine, OpenClaw skill.",
+  "version": "1.18.3",
+  "description": "Give your local tools a voice: fast STT in 25 languages (~19x faster than Whisper on Apple Silicon, ONNX CPU fallback), TTS via Kokoro/Vosk/macOS voices, VAD + 107-language detection. Rust engine, Bun CLI, OpenClaw skill.",
   "type": "module",
   "bin": {
-    "kesha": "bin/kesha.js",
-    "parakeet": "bin/kesha.js"
+    "kesha": "bin/kesha.js"
   },
   "exports": {
     ".": "./src/cli.ts",
@@ -13,6 +12,8 @@
   },
   "files": [
     "bin/",
+    "completions/",
+    "man/",
     "src/",
     "package.json",
     "tsconfig.json",
@@ -38,6 +39,11 @@
     "test:unit": "bun test tests/unit/",
     "test:cli-fast": "bun test tests/unit/ tests/integration/cli-contracts.test.ts tests/integration/e2e-cli.test.ts tests/integration/say.test.ts",
     "test:integration": "bun test tests/integration/",
+    "coverage:ts": "bun run test:cli-fast --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage/ts",
+    "coverage:check:ts": "bun .github/scripts/check-coverage.ts --preset=ts --lcov=coverage/ts/lcov.info --summary=coverage/ts/summary.md",
+    "coverage:rust": "mkdir -p coverage/rust && cd rust && cargo llvm-cov nextest --features tts --lcov --output-path ../coverage/rust/lcov.info",
+    "coverage:check:rust": "bun .github/scripts/check-coverage.ts --preset=rust --lcov=coverage/rust/lcov.info --summary=coverage/rust/summary.md",
+    "generate:shell-artifacts": "bun scripts/generate-shell-artifacts.ts",
     "lint": "bunx tsc --noEmit",
     "lint:tsgo": "bunx tsgo --noEmit",
     "check": "bun run lint && bun run check:versions && bun run test:cli-fast",

package/src/cli/completions.ts

@@ -0,0 +1,41 @@
+import { defineCommand } from "citty";
+import { log } from "../log";
+
+const SHELL_FILES = {
+  bash: "kesha.bash",
+  zsh: "kesha.zsh",
+  fish: "kesha.fish",
+} as const;
+
+type Shell = keyof typeof SHELL_FILES;
+
+interface CompletionsCommandArgs {
+  shell?: string;
+}
+
+function isShell(value: string): value is Shell {
+  return value === "bash" || value === "zsh" || value === "fish";
+}
+
+export const completionsCommand = defineCommand({
+  meta: {
+    name: "completions",
+    description: "Print shell completion script for bash, zsh, or fish",
+  },
+  args: {
+    shell: {
+      type: "positional",
+      required: true,
+      description: "Shell: bash | zsh | fish",
+    },
+  },
+  async run({ args }: { args: CompletionsCommandArgs }) {
+    const shell = args.shell;
+    if (!shell || !isShell(shell)) {
+      log.error("usage: kesha completions <bash|zsh|fish>");
+      process.exit(2);
+    }
+    const file = new URL(`../../completions/${SHELL_FILES[shell]}`, import.meta.url);
+    process.stdout.write(await Bun.file(file).text());
+  },
+});