claude-can-speak 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramazan Yavuz
+
+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,144 @@
+# claude-can-speak
+
+**Now Claude Code talks back.** Speech-out for Claude Code: a companion to the
+built-in `/voice` speech-in. Turn `/voice` on and Claude can read its replies
+aloud through your speakers; turn it off and you are back to silent, text-only.
+Two ways to use it, a local neural voice, nothing sent to the cloud.
+
+- **Firehose mode** - a Stop hook speaks every finished reply while `/voice` is
+  on. One switch (`/voice`) controls both directions: you talk to it, it talks
+  back.
+- **Deliberate mode** - a `speak` skill lets Claude choose what to voice: a
+  spoken "the build is done", a heads-up while you are looking away, a shoutout.
+  Selective, on purpose, not a firehose.
+
+Speech is synthesised locally by [Kokoro](https://github.com/thewh1teagle/kokoro-onnx)
+(natural English, the default) or [Piper](https://github.com/OHF-Voice/piper1-gpl)
+(multilingual: English, German, Turkish, and more), running in a Docker
+container so they never touch your host Python environment. No API keys, no
+network at speak time, no telemetry.
+
+## Requirements
+
+- **Claude Code** (this is an extension for it).
+- **Node.js >= 16 / npm** (to install the CLI).
+- **Docker** (the TTS engines run in a container). The CLI checks for it and
+  tells you how to install it if it is missing.
+- **An audio player**: `pw-play` (PipeWire), `paplay` (PulseAudio), or `aplay`
+  (ALSA) on Linux. (macOS/Windows playback support is on the roadmap.)
+
+## Install
+
+```sh
+npm install -g claude-can-speak
+
+# one-time: build the local TTS container image (needs Docker)
+claude-can-speak build
+```
+
+> If `npm install -g` fails with `EACCES` (a system-owned npm prefix like
+> `/usr`), either use a user-level prefix once:
+> `npm config set prefix ~/.npm-global && export PATH="$HOME/.npm-global/bin:$PATH"`
+> (add that `export` to your shell profile), or install with `sudo`.
+
+Then pick the mode(s) you want:
+
+```sh
+claude-can-speak install-skill    # deliberate mode: the 'speak' skill
+claude-can-speak install-hooks    # firehose mode: speak every reply on /voice
+```
+
+Models are downloaded on first use into `~/.cache/claude-can-speak/models`
+(nothing model-shaped is bundled in the package; see
+[THIRD_PARTY.md](THIRD_PARTY.md)).
+
+Then in Claude Code, toggle `/voice` on. Check everything with:
+
+```sh
+claude-can-speak status
+claude-can-speak test          # speak a sample line
+```
+
+## Usage
+
+```sh
+claude-can-speak status            # gate state, container, voice, model cache
+claude-can-speak test [text]       # speak a sample (or your text)
+claude-can-speak say <text>        # speak text now (ignores the /voice gate)
+claude-can-speak stop              # interrupt whatever is being spoken
+claude-can-speak voice <name>      # set the default voice (e.g. af_heart)
+claude-can-speak engine kokoro|piper
+claude-can-speak voices            # list voices for the current engine
+claude-can-speak skill on|off      # enable/disable the 'speak' skill
+claude-can-speak install-hooks | remove-hooks
+claude-can-speak install-skill
+claude-can-speak build             # (re)build the TTS container image
+```
+
+### Interrupting
+
+You can stop playback three ways: run `claude-can-speak stop`, just send your
+next message (a `UserPromptSubmit` hook stops the previous reply), or let a new
+reply supersede the old one. Interrupts kill both in-flight synthesis and active
+playback.
+
+### Choosing a voice
+
+The default is Kokoro `af_heart` (natural US English, female). List options with
+`claude-can-speak voices`. For German or Turkish, switch to Piper:
+
+```sh
+claude-can-speak engine piper
+claude-can-speak voice de_DE-thorsten-high   # German
+claude-can-speak voice tr_TR-dfki-medium     # Turkish
+```
+
+## How it works
+
+```
+Claude Code reply ─▶ Stop hook (gated on /voice) ─▶ strip markdown & code
+                                                   ─▶ docker exec synth (Kokoro/Piper)
+                                                   ─▶ play WAV on the host
+```
+
+The container is persistent: it starts once and stays warm, so the Python and
+ONNX import cost is paid once, not per reply. Only audio crosses back to the
+host. The `speak` skill drives the same pipeline through `claude-can-speak say`,
+but only when Claude (or you) chooses to speak.
+
+## Configuration
+
+Per-user config lives in `~/.config/claude-can-speak/config.env` (written by the
+`voice` / `engine` commands). Environment overrides: `CCS_IMAGE`,
+`CCS_CONTAINER`, `CCS_MODELS_DIR`, `CLAUDE_SETTINGS`.
+
+The `/voice` gate is read from `~/.claude/settings.json` (`voiceEnabled` or
+`voice.enabled`). The `speak` skill is toggled via `skillOverrides` there.
+
+## Uninstall
+
+```sh
+claude-can-speak remove-hooks
+claude-can-speak skill off
+claude-can-speak stop-container
+npm uninstall -g claude-can-speak
+rm -rf ~/.config/claude-can-speak ~/.claude/skills/speak
+# optional: reclaim the model cache and image
+rm -rf ~/.cache/claude-can-speak
+docker image rm claude-can-speak:latest
+```
+
+## Disclaimer
+
+This software is provided **AS IS, with NO WARRANTY** of any kind, express or
+implied. The author is not liable for any damage, data loss, or other harm
+arising from its use. It runs background processes, plays audio, builds and runs
+a Docker container, and downloads third-party models from the internet on your
+behalf. **By installing and using it you accept all risk.** You are responsible
+for complying with the licences of the bundled engines and the downloaded models
+(see [THIRD_PARTY.md](THIRD_PARTY.md)).
+
+## Licence
+
+MIT - see [LICENSE](LICENSE). Author: Ramazan Yavuz. Part of the public,
+open-source projects at [ra-yavuz.github.io](https://ra-yavuz.github.io/).

package/THIRD_PARTY.md

@@ -0,0 +1,44 @@
+# Third-party components
+
+claude-can-speak is MIT-licensed and ships only its own code: the CLI, the hook
+and worker scripts, the `speak` skill, and the container recipe. It bundles **no
+third-party model weights**. The TTS models are downloaded on first use, from
+their official upstreams, into a local cache (`~/.cache/claude-can-speak/models`)
+on your machine. Each model therefore reaches you directly from its own source
+under its own licence; this project redistributes none of them.
+
+This keeps the project cleanly MIT and avoids redistributing weights whose terms
+differ from ours.
+
+## Engines (installed into the container at build time)
+
+| Component | Licence | Source |
+|---|---|---|
+| Piper (`piper-tts`) | MIT | https://github.com/OHF-Voice/piper1-gpl |
+| Kokoro runtime (`kokoro-onnx`) | MIT | https://github.com/thewh1teagle/kokoro-onnx |
+| onnxruntime | MIT | https://github.com/microsoft/onnxruntime |
+| soundfile / libsndfile | BSD / LGPL-2.1 | https://github.com/bastibe/python-soundfile |
+| espeak-ng | GPL-3.0 | https://github.com/espeak-ng/espeak-ng |
+
+espeak-ng (GPL-3.0) is used inside the container as a grapheme-to-phoneme step.
+It is invoked as a separate program at runtime and is not linked into, or
+redistributed by, this project; it is installed from the distribution's package
+repository when the image is built.
+
+## Models (fetched on first use, not shipped)
+
+| Model | Licence | Source |
+|---|---|---|
+| Kokoro-82M weights | Apache-2.0 | https://huggingface.co/hexgrad/Kokoro-82M |
+| Kokoro ONNX + voices (v1.0) | Apache-2.0 (weights) | https://github.com/thewh1teagle/kokoro-onnx/releases |
+| Piper voices (en_US, de_DE, tr_TR, ...) | per-voice (commonly MIT / CC BY 4.0) | https://huggingface.co/rhasspy/piper-voices |
+
+Piper voice licences vary per voice; consult the voice's model card on
+`rhasspy/piper-voices` for the exact terms and any attribution requirement. The
+default voice (Kokoro `af_heart`) is covered by the Apache-2.0 Kokoro release.
+
+## No warranty
+
+This project, and your use of these third-party components and models, is
+provided AS IS with NO WARRANTY. You are responsible for complying with each
+component's and model's licence. See LICENSE for the full disclaimer.

package/bin/claude-can-speak

@@ -0,0 +1,300 @@
+#!/usr/bin/env bash
+# claude-can-speak: speech-out for Claude Code, gated on /voice mode.
+#
+# This CLI manages the TTS container and the playback lifecycle. The speaking
+# itself is driven by a Stop hook (tts-speak.sh); this command is for setup,
+# testing, picking a voice, and interrupting playback.
+#
+# Provided AS IS, with NO WARRANTY of any kind. The author is not liable for
+# any damage or loss arising from its use. By using it you accept all risk.
+set -uo pipefail
+
+VERSION="0.1.0"
+
+# Install layout: bundled scripts live in ../lib/claude-can-speak relative to
+# this CLI, whether installed via npm (into the global node_modules) or run from
+# a git checkout. SELF resolves through symlinks so a PATH symlink still works.
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [ "${SOURCE#/}" = "$SOURCE" ] && SOURCE="$DIR/$SOURCE"
+done
+SELF="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+LIBEXEC="$SELF/../lib/claude-can-speak"
+[ -f "$LIBEXEC/tts-speak.sh" ] || LIBEXEC="$SELF/../lib/claude-can-speak"
+
+CCS_HOME="${CCS_HOME:-$HOME/.config/claude-can-speak}"
+CONFIG="$CCS_HOME/config.env"
+PIDFILE="$CCS_HOME/speaking.pid"
+CONTAINER="${CCS_CONTAINER:-ccs-tts}"
+IMAGE="${CCS_IMAGE:-claude-can-speak:latest}"
+MODELS_DIR="${CCS_MODELS_DIR:-$HOME/.cache/claude-can-speak/models}"
+SETTINGS_JSON="${CLAUDE_SETTINGS:-$HOME/.claude/settings.json}"
+
+mkdir -p "$CCS_HOME" 2>/dev/null || true
+
+# Defaults; config.env overrides. (MAX_CHARS is a hook-only concern; the CLI's
+# explicit say/test never truncate, so it is not set here.)
+ENGINE="kokoro"; VOICE="af_heart"; LANG="en-us"; SPEED="1.0"
+# shellcheck source=/dev/null
+[ -f "$CONFIG" ] && . "$CONFIG"
+
+die() { echo "claude-can-speak: $*" >&2; exit 1; }
+
+# Docker is a runtime requirement (the TTS engines run in a container so they do
+# not touch the host Python env). Check for it with a clear, actionable error.
+require_docker() {
+  command -v docker >/dev/null 2>&1 || die \
+"Docker is required but was not found.
+  claude-can-speak runs the TTS engines in a container so they never touch your
+  host. Install Docker, then retry:
+    https://docs.docker.com/get-docker/"
+  docker info >/dev/null 2>&1 || die \
+"Docker is installed but the daemon is not reachable.
+  Start Docker (e.g. 'systemctl --user start docker' or Docker Desktop) and retry.
+  On Linux you may need to be in the 'docker' group: https://docs.docker.com/engine/install/linux-postinstall/"
+}
+
+cmd_help() {
+  cat <<EOF
+claude-can-speak $VERSION - speech-out for Claude Code (gated on /voice)
+
+USAGE
+  claude-can-speak <command> [args]
+
+COMMANDS
+  status            Show gate state, container, config, and model cache.
+  test [text]       Speak a sample (or the given text) with the current voice.
+  stop              Interrupt any reply currently being spoken.
+  say <text>        Speak arbitrary text now (ignores the /voice gate).
+  start | up        Start the persistent TTS container.
+  stop-container    Stop and remove the TTS container.
+  voice <name>      Set the default voice (e.g. af_heart, af_bella).
+  engine <name>     Set the engine: kokoro (English) or piper (multilingual).
+  voices            List known voices for the current engine.
+  install-hooks     Register the Stop + interrupt hooks in settings.json.
+  remove-hooks      Remove this project's hooks from settings.json.
+  install-skill     Install the 'speak' skill into ~/.claude/skills.
+  skill on|off      Enable/disable the 'speak' skill (settings skillOverrides).
+  build             Build the TTS container image locally.
+  help | --help     This text.
+
+TWO MODES
+  Firehose : the Stop hook speaks every reply while /voice is on
+             (claude-can-speak install-hooks).
+  Deliberate: the 'speak' skill lets Claude choose what to voice
+             (notifications, shoutouts) via 'claude-can-speak say'
+             (claude-can-speak install-skill). Toggle with 'skill on|off'.
+
+GATING
+  Speech-out only runs while /voice mode is on (voiceEnabled / voice.enabled
+  in $SETTINGS_JSON). Toggle /voice in Claude Code to switch both speech-in
+  and speech-out at once. Turn it off for full silence.
+
+DISCLAIMER
+  Provided AS IS, with NO WARRANTY. You accept all risk. See the project
+  README for the full text.
+EOF
+}
+
+ensure_image() {
+  docker image inspect "$IMAGE" >/dev/null 2>&1
+}
+
+cmd_build() {
+  require_docker
+  local ctx="$SELF/../container"
+  [ -f "$ctx/Dockerfile" ] || die "container build context not found ($ctx)"
+  echo "Building $IMAGE from $ctx ..."
+  docker build -t "$IMAGE" "$ctx"
+}
+
+cmd_start() {
+  require_docker
+  ensure_image || die "image $IMAGE missing; run: claude-can-speak build"
+  if docker inspect -f '{{.State.Running}}' "$CONTAINER" 2>/dev/null | grep -q true; then
+    echo "container $CONTAINER already running"; return 0
+  fi
+  docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
+  mkdir -p "$MODELS_DIR"
+  docker run -d --name "$CONTAINER" -v "$MODELS_DIR:/models" "$IMAGE" >/dev/null \
+    && echo "started $CONTAINER (models cache: $MODELS_DIR)"
+}
+
+cmd_stop_container() {
+  docker rm -f "$CONTAINER" >/dev/null 2>&1 && echo "removed $CONTAINER" \
+    || echo "no container to remove"
+}
+
+cmd_stop() {
+  # Interrupt current playback. Mirrors stop_current() in the hook.
+  local pid stopped=0
+  if [ -f "$PIDFILE" ]; then
+    pid="$(cat "$PIDFILE" 2>/dev/null)"
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+      kill -TERM "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null
+      stopped=1
+    fi
+    rm -f "$PIDFILE" 2>/dev/null || true
+  fi
+  # Belt and suspenders: stop any stray players too.
+  pkill -TERM -x pw-play 2>/dev/null && stopped=1
+  pkill -TERM -x paplay  2>/dev/null && stopped=1
+  [ "$stopped" = 1 ] && echo "stopped playback" || echo "nothing playing"
+}
+
+_synth_to() { # text -> wav path on stdout fd
+  ensure_image || die "image $IMAGE missing; run: claude-can-speak build"
+  cmd_start >/dev/null
+  docker exec -i "$CONTAINER" python3 /app/synth.py \
+    --engine "$ENGINE" --voice "$VOICE" --lang "$LANG" --speed "$SPEED"
+}
+
+_player() {
+  for p in pw-play paplay aplay; do
+    command -v "$p" >/dev/null 2>&1 && { echo "$p"; return; }
+  done
+  return 1
+}
+
+cmd_say() {
+  local text="$*"
+  [ -n "$text" ] || die "usage: claude-can-speak say <text>"
+  local player; player="$(_player)" || die "no audio player (pw-play/paplay/aplay)"
+  local wav; wav="$(mktemp --suffix=.wav)"
+  if printf '%s' "$text" | _synth_to >"$wav" && [ -s "$wav" ]; then
+    "$player" "$wav"
+  else
+    rm -f "$wav"; die "synthesis failed"
+  fi
+  rm -f "$wav"
+}
+
+cmd_test() {
+  local text="${*:-Hi Ramazan. This is Claude Code. Voice output is working, using the $VOICE voice.}"
+  echo "engine=$ENGINE voice=$VOICE lang=$LANG"
+  cmd_say "$text"
+}
+
+cmd_status() {
+  echo "claude-can-speak $VERSION"
+  printf 'voice gate   : '
+  if [ -f "$SETTINGS_JSON" ] && command -v jq >/dev/null 2>&1 \
+     && [ "$(jq -r '(.voiceEnabled // .voice.enabled // false)|tostring' "$SETTINGS_JSON" 2>/dev/null)" = true ]; then
+    echo "ON  (/voice enabled)"
+  else
+    echo "off (/voice disabled) - replies will be silent"
+  fi
+  printf 'engine/voice : %s / %s (%s)\n' "$ENGINE" "$VOICE" "$LANG"
+  printf 'image        : '; ensure_image && echo "$IMAGE present" || echo "$IMAGE MISSING (run: build)"
+  printf 'container    : '
+  docker inspect -f '{{.State.Running}}' "$CONTAINER" 2>/dev/null | grep -q true \
+    && echo "$CONTAINER running" || echo "$CONTAINER not running"
+  printf 'models cache : %s' "$MODELS_DIR"
+  [ -d "$MODELS_DIR" ] && printf ' (%s)\n' "$(du -sh "$MODELS_DIR" 2>/dev/null | cut -f1)" || printf ' (empty)\n'
+  printf 'hooks        : '
+  if [ -f "$SETTINGS_JSON" ] && grep -q 'tts-speak.sh' "$SETTINGS_JSON" 2>/dev/null; then
+    echo "registered"; else echo "NOT registered (run: install-hooks)"; fi
+}
+
+_set_config() { # key value
+  touch "$CONFIG"
+  if grep -q "^$1=" "$CONFIG" 2>/dev/null; then
+    sed -i "s|^$1=.*|$1=\"$2\"|" "$CONFIG"
+  else
+    printf '%s="%s"\n' "$1" "$2" >>"$CONFIG"
+  fi
+}
+
+cmd_voice() { [ -n "${1:-}" ] || die "usage: claude-can-speak voice <name>"; _set_config VOICE "$1"; echo "voice set to $1"; }
+cmd_engine() {
+  case "${1:-}" in
+    kokoro) _set_config ENGINE kokoro; _set_config LANG en-us; echo "engine set to kokoro (English)";;
+    piper)  _set_config ENGINE piper; echo "engine set to piper (multilingual); set a voice with: claude-can-speak voice de_DE-thorsten-high";;
+    *) die "engine must be 'kokoro' or 'piper'";;
+  esac
+}
+
+cmd_voices() {
+  if [ "$ENGINE" = piper ]; then
+    cat <<EOF
+piper voices (multilingual):
+  en_US-amy-medium  en_US-lessac-high  en_US-libritts_r-medium
+  en_US-hfc_female-medium  en_US-kristin-medium  en_GB-jenny_dioco-medium
+  de_DE-thorsten-medium  de_DE-thorsten-high  tr_TR-dfki-medium
+EOF
+  else
+    cat <<EOF
+kokoro voices (English; af_=US female, am_=US male, bf_/bm_=British):
+  af_heart  af_bella  af_nicole  af_aoede  af_kore  af_sarah
+  af_nova  af_sky  af_jessica  af_river  am_michael  am_fenrir  am_puck
+EOF
+  fi
+}
+
+cmd_install_skill() {
+  # Locate the packaged skill (deb vs git checkout).
+  local src
+  for cand in "/usr/share/claude-can-speak/skills/speak" "$SELF/../skills/speak"; do
+    [ -f "$cand/SKILL.md" ] && { src="$cand"; break; }
+  done
+  [ -n "${src:-}" ] || die "packaged skill not found"
+  local dest="$HOME/.claude/skills/speak"
+  mkdir -p "$dest"
+  cp "$src/SKILL.md" "$dest/SKILL.md"
+  echo "installed 'speak' skill -> $dest/SKILL.md"
+  echo "if ~/.claude/skills did not exist before, restart your session to discover it."
+}
+
+cmd_skill() {
+  case "${1:-}" in
+    on)  _skill_override on;  echo "'speak' skill enabled" ;;
+    off) _skill_override off; echo "'speak' skill disabled" ;;
+    *) die "usage: claude-can-speak skill on|off" ;;
+  esac
+}
+
+_skill_override() { # on|off  -> settings.json skillOverrides.speak
+  [ -f "$SETTINGS_JSON" ] || { mkdir -p "$(dirname "$SETTINGS_JSON")"; echo '{}' >"$SETTINGS_JSON"; }
+  python3 - "$SETTINGS_JSON" "$1" <<'PY'
+import json, sys, os
+path, state = sys.argv[1], sys.argv[2]
+with open(path) as f: cfg = json.load(f)
+ov = cfg.setdefault("skillOverrides", {})
+if state == "off": ov["speak"] = "off"
+else: ov.pop("speak", None)        # remove override = default 'on'
+tmp = path + ".tmp"
+with open(tmp, "w") as f: json.dump(cfg, f, indent=2); f.write("\n")
+os.replace(tmp, path)
+PY
+}
+
+cmd_install_hooks() {
+  [ -x "$LIBEXEC/install-hooks.sh" ] || die "install-hooks.sh not found in $LIBEXEC"
+  "$LIBEXEC/install-hooks.sh" install
+}
+cmd_remove_hooks() {
+  [ -x "$LIBEXEC/install-hooks.sh" ] || die "install-hooks.sh not found in $LIBEXEC"
+  "$LIBEXEC/install-hooks.sh" remove
+}
+
+case "${1:-help}" in
+  status)         cmd_status ;;
+  test)           shift; cmd_test "$@" ;;
+  say)            shift; cmd_say "$@" ;;
+  stop)           cmd_stop ;;
+  start|up)       cmd_start ;;
+  stop-container) cmd_stop_container ;;
+  voice)          shift; cmd_voice "${1:-}" ;;
+  engine)         shift; cmd_engine "${1:-}" ;;
+  voices)         cmd_voices ;;
+  install-hooks)  cmd_install_hooks ;;
+  remove-hooks)   cmd_remove_hooks ;;
+  install-skill)  cmd_install_skill ;;
+  skill)          shift; cmd_skill "${1:-}" ;;
+  build)          cmd_build ;;
+  help|-h|--help) cmd_help ;;
+  --version|-V)   echo "claude-can-speak $VERSION" ;;
+  *)              die "unknown command '$1' (try: claude-can-speak help)" ;;
+esac

package/bin/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// npm entry point for claude-can-speak. This is a thin cross-platform shim: it
+// locates the bundled bash CLI shipped in the package and execs it, passing
+// through all arguments. The real logic lives in bin/claude-can-speak (bash),
+// shared by the npm install and a direct git checkout.
+//
+// Bash is required (the CLI drives Docker + audio via shell). On Linux/macOS it
+// is present; on Windows use WSL or Git Bash. We fail with a clear message if
+// bash cannot be found rather than half-running.
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+const fs = require("node:fs");
+
+const cliPath = path.join(__dirname, "claude-can-speak");
+
+if (!fs.existsSync(cliPath)) {
+  console.error("claude-can-speak: bundled CLI not found at " + cliPath);
+  process.exit(1);
+}
+
+// Resolve a bash interpreter. PATH lookup covers Linux/macOS and Git-Bash/WSL
+// shims on Windows.
+function findBash() {
+  const candidates =
+    process.platform === "win32"
+      ? ["bash.exe", "bash"]
+      : ["/bin/bash", "/usr/bin/bash", "bash"];
+  for (const c of candidates) {
+    const r = spawnSync(c, ["-c", "exit 0"], { stdio: "ignore" });
+    if (r.status === 0) return c;
+  }
+  return null;
+}
+
+const bash = findBash();
+if (!bash) {
+  console.error(
+    "claude-can-speak: bash is required but was not found.\n" +
+      "Install bash (Linux/macOS have it; on Windows use WSL or Git Bash)."
+  );
+  process.exit(1);
+}
+
+const res = spawnSync(bash, [cliPath, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+process.exit(res.status === null ? 1 : res.status);

package/container/Dockerfile

@@ -0,0 +1,33 @@
+# claude-can-speak TTS container.
+#
+# Bundles the two synthesis engines (Piper + Kokoro) and their Python deps,
+# but NO model weights: models are fetched on first use into /models, which
+# is a host-mounted cache. The image therefore redistributes no third-party
+# model files. See ../THIRD_PARTY.md for per-model licences.
+FROM python:3.12-slim
+
+# espeak-ng is required by Kokoro's grapheme-to-phoneme stage; harmless for
+# Piper (which carries its own phonemization). libsndfile backs soundfile.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends espeak-ng libsndfile1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Pinned to keep synthesis reproducible. onnxruntime is the CPU build.
+RUN pip install --no-cache-dir \
+        piper-tts==1.4.2 \
+        kokoro-onnx==0.5.0 \
+        soundfile==0.13.1 \
+        onnxruntime==1.26.0
+
+ENV CCS_MODELS_DIR=/models
+RUN mkdir -p /models
+VOLUME ["/models"]
+
+COPY synth.py /app/synth.py
+COPY serve.sh /app/serve.sh
+RUN chmod +x /app/serve.sh
+
+# The container stays alive doing nothing; the host drives synthesis via
+# `docker exec ... python3 /app/synth.py`. This keeps the Python import cost
+# (onnxruntime, piper, kokoro) paid once per container, not once per reply.
+ENTRYPOINT ["/app/serve.sh"]

package/container/serve.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+# Keep the container alive so the host can drive synthesis via `docker exec`.
+# Paying Python + onnxruntime import cost once per container (not once per
+# reply) is the whole point of the persistent-container design.
+echo "[claude-can-speak] tts container ready; awaiting docker exec" >&2
+exec tail -f /dev/null

package/container/synth.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""claude-can-speak synthesis entrypoint (runs inside the TTS container).
+
+Reads text on stdin, writes a WAV stream on stdout. The engine and voice are
+chosen by flags so the host-side hook stays a thin wrapper. Two engines are
+supported:
+
+  piper   VITS2, multilingual (English, German, Turkish, ...). The default.
+  kokoro  Kokoro-82M, English-family only, higher naturalness.
+
+Models are NOT bundled in the image. They are fetched on first use into
+/models (a host-mounted cache) from their official upstreams, so the image
+and the .deb redistribute no third-party model weights. See THIRD_PARTY.md
+for the per-model licences.
+
+This program prints nothing to stdout except the WAV bytes; all diagnostics
+go to stderr so the audio stream stays clean.
+"""
+
+import argparse
+import os
+import sys
+import urllib.request
+
+MODELS_DIR = os.environ.get("CCS_MODELS_DIR", "/models")
+
+# Piper voices we know about: slug -> (subpath on rhasspy/piper-voices, lang).
+# Verified to resolve (HTTP 200) on huggingface.co/rhasspy/piper-voices.
+PIPER_VOICES = {
+    "en_US-amy-medium":        "en/en_US/amy/medium/en_US-amy-medium",
+    "en_US-lessac-high":       "en/en_US/lessac/high/en_US-lessac-high",
+    "en_US-libritts_r-medium": "en/en_US/libritts_r/medium/en_US-libritts_r-medium",
+    "en_US-hfc_female-medium": "en/en_US/hfc_female/medium/en_US-hfc_female-medium",
+    "en_US-kristin-medium":    "en/en_US/kristin/medium/en_US-kristin-medium",
+    "en_GB-jenny_dioco-medium": "en/en_GB/jenny_dioco/medium/en_GB-jenny_dioco-medium",
+    "de_DE-thorsten-medium":   "de/de_DE/thorsten/medium/de_DE-thorsten-medium",
+    "de_DE-thorsten-high":     "de/de_DE/thorsten/high/de_DE-thorsten-high",
+    "tr_TR-dfki-medium":       "tr/tr_TR/dfki/medium/tr_TR-dfki-medium",
+}
+PIPER_BASE = "https://huggingface.co/rhasspy/piper-voices/resolve/main"
+
+# Kokoro model + voices pack (single combined ONNX + a voices.bin).
+KOKORO_MODEL_URL = (
+    "https://github.com/thewh1teagle/kokoro-onnx/releases/download/"
+    "model-files-v1.0/kokoro-v1.0.onnx"
+)
+KOKORO_VOICES_URL = (
+    "https://github.com/thewh1teagle/kokoro-onnx/releases/download/"
+    "model-files-v1.0/voices-v1.0.bin"
+)
+
+
+def log(msg):
+    print(f"[claude-can-speak/synth] {msg}", file=sys.stderr, flush=True)
+
+
+def _download(url, dest):
+    """Fetch url to dest atomically. Skips if dest already exists."""
+    if os.path.exists(dest) and os.path.getsize(dest) > 0:
+        return dest
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+    # Unique temp per process so concurrent synths never race on the same
+    # .part file (os.replace is atomic, so the last writer wins cleanly).
+    tmp = f"{dest}.part.{os.getpid()}"
+    log(f"fetching {url}")
+    req = urllib.request.Request(url, headers={"User-Agent": "claude-can-speak"})
+    try:
+        with urllib.request.urlopen(req) as r, open(tmp, "wb") as f:
+            while True:
+                chunk = r.read(1 << 16)
+                if not chunk:
+                    break
+                f.write(chunk)
+        os.replace(tmp, dest)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+    log(f"cached {dest} ({os.path.getsize(dest)} bytes)")
+    return dest
+
+
+def ensure_piper_voice(voice):
+    if voice not in PIPER_VOICES:
+        raise SystemExit(
+            f"unknown piper voice {voice!r}; known: {', '.join(PIPER_VOICES)}"
+        )
+    subpath = PIPER_VOICES[voice]
+    onnx = os.path.join(MODELS_DIR, "piper", voice + ".onnx")
+    conf = onnx + ".json"
+    _download(f"{PIPER_BASE}/{subpath}.onnx", onnx)
+    _download(f"{PIPER_BASE}/{subpath}.onnx.json", conf)
+    return onnx
+
+
+def ensure_kokoro_model():
+    model = os.path.join(MODELS_DIR, "kokoro", "kokoro-v1.0.onnx")
+    voices = os.path.join(MODELS_DIR, "kokoro", "voices-v1.0.bin")
+    _download(KOKORO_MODEL_URL, model)
+    _download(KOKORO_VOICES_URL, voices)
+    return model, voices
+
+
+def synth_piper(text, voice, speed, wav_path):
+    from piper import PiperVoice, SynthesisConfig  # piper-tts (piper1-gpl)
+    import wave
+
+    onnx = ensure_piper_voice(voice)
+    v = PiperVoice.load(onnx)
+    # length_scale < 1 speeds speech up; invert the user-facing speed factor.
+    cfg = SynthesisConfig(length_scale=(1.0 / speed if speed else 1.0))
+    with wave.open(wav_path, "wb") as wf:
+        v.synthesize_wav(text, wf, syn_config=cfg)
+
+
+def synth_kokoro(text, voice, lang, speed, wav_path):
+    from kokoro_onnx import Kokoro
+    import soundfile as sf
+
+    model, voices = ensure_kokoro_model()
+    k = Kokoro(model, voices)
+    samples, sample_rate = k.create(text, voice=voice, speed=speed, lang=lang)
+    sf.write(wav_path, samples, sample_rate, format="WAV", subtype="PCM_16")
+
+
+def main():
+    ap = argparse.ArgumentParser(description="claude-can-speak TTS synth")
+    ap.add_argument("--engine", choices=["piper", "kokoro"], default="kokoro")
+    ap.add_argument("--voice", default="af_heart")
+    ap.add_argument("--lang", default="en-us",
+                    help="kokoro language tag (e.g. en-us); ignored by piper")
+    ap.add_argument("--speed", type=float, default=1.0)
+    ap.add_argument("--text", default=None,
+                    help="text to speak; if omitted, read from stdin")
+    args = ap.parse_args()
+
+    text = args.text if args.text is not None else sys.stdin.read()
+    text = text.strip()
+    if not text:
+        log("empty text, nothing to synthesize")
+        return 0
+
+    # WAV encoders (wave, soundfile) seek back to patch the header size, so
+    # they need a seekable target; a stdout pipe is not seekable. Synthesize
+    # to a temp file, then stream the bytes to stdout.
+    import tempfile
+
+    tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
+    tmp.close()
+    try:
+        if args.engine == "piper":
+            synth_piper(text, args.voice, args.speed, tmp.name)
+        else:
+            synth_kokoro(text, args.voice, args.lang, args.speed, tmp.name)
+        with open(tmp.name, "rb") as f:
+            sys.stdout.buffer.write(f.read())
+        sys.stdout.buffer.flush()
+    except Exception as e:  # fail loud on stderr, silent on stdout
+        log(f"synthesis failed: {e}")
+        return 1
+    finally:
+        try:
+            os.unlink(tmp.name)
+        except OSError:
+            pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/lib/claude-can-speak/clean.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Strip markdown and code from a Claude reply so it reads naturally aloud.
+
+Reads text on stdin, writes cleaned text on stdout. argv[1] (optional) is the
+maximum character count; longer text is truncated on a sentence boundary so a
+long reply does not monologue forever. Fenced code blocks are removed entirely
+(they are unlistenable); inline code keeps its contents.
+"""
+import re
+import sys
+
+
+def clean(text, maxc):
+    # Remove fenced code blocks entirely.
+    text = re.sub(r"```.*?```", " ", text, flags=re.DOTALL)
+    text = re.sub(r"~~~.*?~~~", " ", text, flags=re.DOTALL)
+    # Inline code: keep contents, drop backticks.
+    text = re.sub(r"`([^`]*)`", r"\1", text)
+    # Images / links: keep visible text, drop URL.
+    text = re.sub(r"!\[[^\]]*\]\([^)]*\)", " ", text)
+    text = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", text)
+    # Headings, list bullets, blockquote markers.
+    text = re.sub(r"^[ \t]*#{1,6}[ \t]*", "", text, flags=re.MULTILINE)
+    text = re.sub(r"^[ \t]*[-*+][ \t]+", "", text, flags=re.MULTILINE)
+    text = re.sub(r"^[ \t]*>[ \t]?", "", text, flags=re.MULTILINE)
+    # Emphasis markers around a run of text.
+    text = re.sub(r"[*_]{1,3}([^*_]+)[*_]{1,3}", r"\1", text)
+    # Collapse whitespace.
+    text = re.sub(r"\s+", " ", text).strip()
+    if maxc and len(text) > maxc:
+        cut = text[:maxc]
+        m = max(cut.rfind(". "), cut.rfind("! "), cut.rfind("? "))
+        text = cut[: m + 1] if m > maxc * 0.5 else cut
+    return text
+
+
+def main():
+    maxc = int(sys.argv[1]) if len(sys.argv) > 1 else 700
+    sys.stdout.write(clean(sys.stdin.read(), maxc))
+
+
+if __name__ == "__main__":
+    main()

package/lib/claude-can-speak/install-hooks.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# claude-can-speak: register (or remove) the Stop + UserPromptSubmit hooks in
+# the user's Claude Code settings.json, merging into any existing hooks rather
+# than overwriting them. Idempotent.
+set -uo pipefail
+
+SETTINGS_JSON="${CLAUDE_SETTINGS:-$HOME/.claude/settings.json}"
+
+# Resolve where the installed hook scripts live (deb vs git checkout).
+SELF="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "/usr/lib/claude-can-speak/tts-speak.sh" ]; then
+  HOOKDIR="/usr/lib/claude-can-speak"
+else
+  HOOKDIR="$SELF"
+fi
+SPEAK_HOOK="$HOOKDIR/tts-speak.sh"
+INTERRUPT_HOOK="$HOOKDIR/interrupt.sh"
+
+action="${1:-install}"
+
+[ -f "$SETTINGS_JSON" ] || { mkdir -p "$(dirname "$SETTINGS_JSON")"; echo '{}' >"$SETTINGS_JSON"; }
+
+python3 - "$SETTINGS_JSON" "$action" "$SPEAK_HOOK" "$INTERRUPT_HOOK" <<'PY'
+import json, sys, os, shutil
+
+path, action, speak_hook, interrupt_hook = sys.argv[1:5]
+
+with open(path) as f:
+    cfg = json.load(f)
+
+hooks = cfg.setdefault("hooks", {})
+
+MARK = "tts-speak.sh"            # how we recognise our Stop hook
+IMARK = "interrupt.sh"          # how we recognise our UserPromptSubmit hook
+
+def groups(event):
+    return hooks.setdefault(event, [])
+
+def strip(event, needle):
+    """Remove any hook entry whose command mentions needle."""
+    kept = []
+    for group in hooks.get(event, []):
+        group_hooks = [h for h in group.get("hooks", [])
+                       if needle not in str(h.get("command", ""))]
+        if group_hooks:
+            group = dict(group); group["hooks"] = group_hooks
+            kept.append(group)
+    if kept:
+        hooks[event] = kept
+    elif event in hooks:
+        del hooks[event]
+
+# Always strip our previous entries first so the operation is idempotent.
+strip("Stop", MARK)
+strip("UserPromptSubmit", IMARK)
+
+if action == "install":
+    groups("Stop").append({
+        "hooks": [{"type": "command", "command": speak_hook, "timeout": 15}]
+    })
+    groups("UserPromptSubmit").append({
+        "hooks": [{"type": "command", "command": interrupt_hook, "timeout": 5}]
+    })
+elif action == "remove":
+    pass
+else:
+    sys.stderr.write("action must be install or remove\n")
+    sys.exit(2)
+
+# Back up once, then write atomically.
+if not os.path.exists(path + ".ccs-bak"):
+    shutil.copy2(path, path + ".ccs-bak")
+tmp = path + ".tmp"
+with open(tmp, "w") as f:
+    json.dump(cfg, f, indent=2)
+    f.write("\n")
+os.replace(tmp, path)
+print(f"{action}ed claude-can-speak hooks in {path}")
+PY
+
+if [ "$action" = install ]; then
+  echo "Stop hook       -> $SPEAK_HOOK"
+  echo "UserPromptSubmit -> $INTERRUPT_HOOK"
+  echo "Note: Claude Code loads hooks at session start; restart your session to activate."
+fi

package/lib/claude-can-speak/interrupt.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# claude-can-speak: UserPromptSubmit hook. When you send your next message,
+# stop whatever the previous reply was still speaking. This makes "just start
+# typing" the natural interrupt: the moment you move on, the voice goes quiet.
+#
+# Fails silent, returns immediately.
+set -uo pipefail
+
+CCS_HOME="${CCS_HOME:-$HOME/.config/claude-can-speak}"
+PIDFILE="$CCS_HOME/speaking.pid"
+
+# Drain stdin (the hook payload) so the caller's pipe never blocks.
+cat >/dev/null 2>&1 || true
+
+if [ -f "$PIDFILE" ]; then
+  pid="$(cat "$PIDFILE" 2>/dev/null)"
+  if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+    kill -TERM "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null
+  fi
+  rm -f "$PIDFILE" 2>/dev/null || true
+fi
+exit 0

package/lib/claude-can-speak/speak-worker.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# claude-can-speak speak worker. Launched detached (setsid) by tts-speak.sh as
+# a new session leader, so $$ is this worker's process-group id. It records that
+# pid IMMEDIATELY - before the multi-second synthesis - so an interrupt issued
+# at any point (during synth or during playback) kills the whole group via
+# `kill -TERM -$pid`. Cleaned text arrives on stdin; config via the environment.
+set -uo pipefail
+
+: "${CCS_HOME:=$HOME/.config/claude-can-speak}"
+: "${LOG:=$CCS_HOME/claude-can-speak.log}"
+: "${PIDFILE:=$CCS_HOME/speaking.pid}"
+: "${CONTAINER:=ccs-tts}"
+: "${IMAGE:=claude-can-speak:latest}"
+: "${MODELS_DIR:=$HOME/.cache/claude-can-speak/models}"
+: "${PLAYER:=pw-play}"
+: "${ENGINE:=kokoro}"
+: "${VOICE:=af_heart}"
+: "${CCS_LANG:=en-us}"
+: "${SPEED:=1.0}"
+
+log() { printf '%s %s\n' "$(date -Is)" "$*" >>"$LOG" 2>/dev/null || true; }
+
+# Record our group id up front so we are interruptible during synthesis.
+printf '%s' "$$" >"$PIDFILE" 2>/dev/null || true
+# If we are signalled, drop the pidfile on the way out.
+trap 'rm -f "$PIDFILE" 2>/dev/null; exit 0' TERM INT
+
+ensure_container() {
+  if docker inspect -f '{{.State.Running}}' "$CONTAINER" 2>/dev/null | grep -q true; then
+    return 0
+  fi
+  docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
+  docker image inspect "$IMAGE" >/dev/null 2>&1 || { log "image $IMAGE missing"; return 1; }
+  mkdir -p "$MODELS_DIR" 2>/dev/null || true
+  docker run -d --name "$CONTAINER" -v "$MODELS_DIR:/models" "$IMAGE" >/dev/null 2>&1 \
+    || { log "container start failed"; return 1; }
+  log "started container $CONTAINER"
+}
+
+CLEAN="$(cat)"
+[ -n "$CLEAN" ] || { rm -f "$PIDFILE" 2>/dev/null; exit 0; }
+
+ensure_container || { rm -f "$PIDFILE" 2>/dev/null; exit 0; }
+
+wav="$(mktemp --suffix=.wav 2>/dev/null)" || { rm -f "$PIDFILE" 2>/dev/null; exit 0; }
+if printf '%s' "$CLEAN" | docker exec -i "$CONTAINER" \
+      python3 /app/synth.py \
+        --engine "$ENGINE" --voice "$VOICE" --lang "$CCS_LANG" --speed "$SPEED" \
+      >"$wav" 2>>"$LOG" && [ -s "$wav" ]; then
+  "$PLAYER" "$wav" >/dev/null 2>&1
+else
+  log "synthesis produced no audio (engine=$ENGINE voice=$VOICE)"
+fi
+rm -f "$wav" 2>/dev/null || true
+
+# Clear the pidfile only if it still points at us (a newer reply may have
+# replaced it while we were speaking).
+[ "$(cat "$PIDFILE" 2>/dev/null)" = "$$" ] && rm -f "$PIDFILE" 2>/dev/null
+exit 0

package/lib/claude-can-speak/tts-speak.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# claude-can-speak: Claude Code Stop hook that speaks each finished reply.
+#
+# Gated on /voice mode: it reads the same voiceEnabled / voice.enabled flag
+# that the built-in /voice (speech-in) toggles, so one switch controls both
+# directions. Voice off -> this exits silently and Claude Code stays text-only.
+#
+# Design contract:
+#   - Non-blocking: synthesis + playback run in a detached background job so
+#     the hook returns immediately and never delays the next turn.
+#   - Fails silent: any error (no docker, no audio, gate off) exits 0 quietly.
+#   - Absolute paths only; no reliance on the caller's PATH or cwd.
+#
+# Provided AS IS, no warranty. See the project README for the full disclaimer.
+set -uo pipefail
+
+# --- Resolve config -------------------------------------------------------
+CCS_HOME="${CCS_HOME:-$HOME/.config/claude-can-speak}"
+CCS_CONFIG="$CCS_HOME/config.env"
+SETTINGS_JSON="${CLAUDE_SETTINGS:-$HOME/.claude/settings.json}"
+CONTAINER="${CCS_CONTAINER:-ccs-tts}"
+IMAGE="${CCS_IMAGE:-claude-can-speak:latest}"
+MODELS_DIR="${CCS_MODELS_DIR:-$HOME/.cache/claude-can-speak/models}"
+LOG="$CCS_HOME/claude-can-speak.log"
+PIDFILE="$CCS_HOME/speaking.pid"
+
+# Defaults (overridable via config.env). Chosen from a listening test:
+# Kokoro af_heart, US female, is the most natural.
+ENGINE="kokoro"
+VOICE="af_heart"
+LANG="en-us"
+SPEED="1.0"
+MAX_CHARS="700"
+
+# shellcheck source=/dev/null
+[ -f "$CCS_CONFIG" ] && . "$CCS_CONFIG"
+
+mkdir -p "$CCS_HOME" 2>/dev/null || true
+
+log() { printf '%s %s\n' "$(date -Is)" "$*" >>"$LOG" 2>/dev/null || true; }
+
+# --- Tool availability ----------------------------------------------------
+command -v docker >/dev/null 2>&1 || { log "no docker; silent"; exit 0; }
+
+PLAYER=""
+for p in pw-play paplay aplay; do
+  if command -v "$p" >/dev/null 2>&1; then PLAYER="$p"; break; fi
+done
+[ -n "$PLAYER" ] || { log "no audio player; silent"; exit 0; }
+
+# --- Read the Stop hook payload ------------------------------------------
+PAYLOAD="$(cat)"
+
+# --- Gate: only speak when /voice mode is on ------------------------------
+# Read voiceEnabled OR voice.enabled from settings.json. Absent/false = off.
+voice_on() {
+  [ -f "$SETTINGS_JSON" ] || return 1
+  if command -v jq >/dev/null 2>&1; then
+    local v
+    v="$(jq -r '(.voiceEnabled // .voice.enabled // false) | tostring' \
+          "$SETTINGS_JSON" 2>/dev/null)"
+    [ "$v" = "true" ]
+    return
+  fi
+  # jq-less fallback: grep the two known keys.
+  grep -Eq '"voiceEnabled"[[:space:]]*:[[:space:]]*true' "$SETTINGS_JSON" && return 0
+  grep -Eq '"enabled"[[:space:]]*:[[:space:]]*true' "$SETTINGS_JSON" && return 0
+  return 1
+}
+voice_on || { log "voice gate off; silent"; exit 0; }
+
+# --- Extract the reply text ----------------------------------------------
+extract_text() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$PAYLOAD" | jq -r '.last_assistant_message // empty' 2>/dev/null
+  else
+    # Minimal fallback: pull last_assistant_message with python if present.
+    printf '%s' "$PAYLOAD" | python3 -c \
+      'import sys,json; print(json.load(sys.stdin).get("last_assistant_message",""))' \
+      2>/dev/null
+  fi
+}
+TEXT="$(extract_text)"
+[ -n "$TEXT" ] || { log "no last_assistant_message; silent"; exit 0; }
+
+# --- Clean text for speech ------------------------------------------------
+# Drop fenced code blocks (unlistenable), strip common markdown, collapse
+# whitespace, cap length. Logic lives in clean.py beside this script.
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLEAN_PY="${CCS_CLEAN_PY:-$SELF_DIR/clean.py}"
+[ -f "$CLEAN_PY" ] || { log "clean.py not found at $CLEAN_PY; silent"; exit 0; }
+CLEAN="$(printf '%s' "$TEXT" | python3 "$CLEAN_PY" "$MAX_CHARS" 2>>"$LOG")"
+[ -n "$CLEAN" ] || { log "empty after cleaning; silent"; exit 0; }
+
+# --- Interrupt any currently-playing reply --------------------------------
+# A new reply supersedes the previous one: stop stale playback before we
+# start. The same logic backs `claude-can-speak stop`.
+stop_current() {
+  [ -f "$PIDFILE" ] || return 0
+  local pid
+  pid="$(cat "$PIDFILE" 2>/dev/null)"
+  if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+    # Kill the player and its group so the pipeline dies with it.
+    kill -TERM "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null
+  fi
+  rm -f "$PIDFILE" 2>/dev/null || true
+}
+
+# --- Speak (detached worker) ----------------------------------------------
+# A fresh reply interrupts whatever was still being spoken.
+stop_current
+
+# Launch the worker in a new session (setsid) so the hook returns immediately
+# and the worker is a process-group leader: an interrupt can signal its whole
+# group (in-flight synth + player) by the single recorded pid. Config is passed
+# through the environment; the cleaned text arrives on the worker's stdin.
+SELF_DIR="${SELF_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}"
+WORKER="${CCS_WORKER:-$SELF_DIR/speak-worker.sh}"
+[ -f "$WORKER" ] || { log "speak-worker.sh not found at $WORKER; silent"; exit 0; }
+
+printf '%s' "$CLEAN" | \
+  CCS_HOME="$CCS_HOME" LOG="$LOG" PIDFILE="$PIDFILE" \
+  CONTAINER="$CONTAINER" IMAGE="$IMAGE" MODELS_DIR="$MODELS_DIR" PLAYER="$PLAYER" \
+  ENGINE="$ENGINE" VOICE="$VOICE" CCS_LANG="$LANG" SPEED="$SPEED" \
+  setsid bash "$WORKER" >/dev/null 2>&1 &
+exit 0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "claude-can-speak",
+  "version": "0.1.0",
+  "description": "Speech-out for Claude Code: speak replies aloud (Stop-hook firehose) or let Claude voice deliberate notifications (skill). Local neural TTS via Kokoro/Piper in Docker. Gated on /voice mode.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "tts",
+    "text-to-speech",
+    "voice",
+    "kokoro",
+    "piper",
+    "speech",
+    "skill",
+    "hook"
+  ],
+  "homepage": "https://ra-yavuz.github.io/claude-can-speak/",
+  "bugs": {
+    "url": "https://github.com/ra-yavuz/claude-can-speak/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ra-yavuz/claude-can-speak.git"
+  },
+  "license": "MIT",
+  "author": "Ramazan Yavuz <yavuzramazan1994@gmail.com>",
+  "type": "commonjs",
+  "bin": {
+    "claude-can-speak": "bin/cli.js"
+  },
+  "files": [
+    "bin/cli.js",
+    "bin/claude-can-speak",
+    "lib/claude-can-speak/",
+    "container/",
+    "skills/",
+    "THIRD_PARTY.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ]
+}

package/skills/speak/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: speak
+description: >-
+  Speak a short message aloud through the user's speakers using claude-can-speak
+  (text-to-speech). Use this for deliberate, selective audio: a spoken
+  notification when a long task finishes, a heads-up that needs attention while
+  the user is looking away, a brief shoutout or status callout, or when the user
+  asks you to say something out loud. This is NOT for reading every reply aloud
+  (that is the separate Stop-hook mode); use it only for things genuinely worth
+  hearing. Keep spoken text to one or two short sentences.
+argument-hint: "[message to speak]"
+allowed-tools: Bash(claude-can-speak say *)
+---
+
+# Speak aloud
+
+You can send a short message to the user's speakers with the `claude-can-speak`
+text-to-speech tool. Use it deliberately, not for everything.
+
+## When to speak
+
+Good uses:
+- A finished long-running task the user stepped away from: "The build is done and all tests passed."
+- A notification that wants attention now: "Heads up, the deploy needs your confirmation."
+- A short status callout or shoutout the user asked for out loud.
+- The user explicitly says "tell me out loud", "say this", "read that back", etc.
+
+Do NOT use it to narrate routine replies, read long passages, or speak code,
+file paths, commands, or anything awkward to hear. If it is not worth
+interrupting the user's ears for, keep it text-only.
+
+## How to speak
+
+Run the CLI with the exact text to say (one or two short sentences, plain
+words, no markdown or code):
+
+```
+claude-can-speak say "Your short message here."
+```
+
+If a message was passed to this skill, speak that:
+
+```
+claude-can-speak say "$ARGUMENTS"
+```
+
+Notes:
+- The user can interrupt playback at any time with `claude-can-speak stop`, or
+  simply by sending their next message.
+- `say` speaks regardless of /voice mode (it is a deliberate, explicit call),
+  whereas the firehose Stop-hook mode only speaks while /voice is on.
+- If the command reports the image or container is missing, tell the user to run
+  `claude-can-speak build` once, then retry; do not keep retrying silently.