claude-can-speak 0.1.0 → 0.1.2

package/README.md

@@ -1,16 +1,22 @@
 # 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.
+**Let Claude decide what to say out loud.** Most "speak Claude Code aloud" tools
+read *every* reply at you. claude-can-speak leads with the opposite: a Claude
+Code **skill** that gives the model a deliberate "say this" capability, so Claude
+voices only what is worth hearing, a spoken "the build is done and tests passed"
+when you have stepped away, a heads-up that a deploy needs confirmation, a short
+shoutout you asked for, while everything else stays text-only. Selective, on
+purpose, model-controlled.
+
+If you *do* want the firehose, it is one command away: a Stop hook that speaks
+every finished reply, gated on the built-in `/voice` mode so one switch controls
+both directions (you talk to it, it talks back). But the deliberate skill is the
+point.
+
+- **Deliberate mode (the headline)** - the `speak` skill lets Claude choose what
+  to voice. Install with `claude-can-speak install-skill`.
+- **Firehose mode (optional)** - a Stop hook speaks every reply while `/voice` is
+  on. Install with `claude-can-speak install-hooks`.
 
 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)
@@ -138,6 +144,20 @@ 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)).
 
+## Related projects
+
+Speaking Claude Code's replies aloud is a well-trodden idea, and several tools do
+the firehose well: `claude-voice` (Kokoro plus karaoke word highlighting),
+`claude-code-tts` (OpenAI or Kokoro auto-speak), `claude-voice-mcp` and
+`soliloquy-tts` (MCP-based auto-speak). If all you want is "read every reply
+aloud", any of those is a fine choice and lighter than this one (no Docker).
+
+claude-can-speak is built around a different default: the deliberate `speak`
+skill, so Claude voices only what is worth hearing rather than everything. It
+also adds multilingual output (Piper for German, Turkish, and more), Docker
+isolation so the engines never touch your host Python, and gating on the built-in
+`/voice` switch. The firehose mode is included, but it is not the headline.
+
 ## Licence
 
 MIT - see [LICENSE](LICENSE). Author: Ramazan Yavuz. Part of the public,

package/bin/claude-can-speak

@@ -9,7 +9,7 @@
 # any damage or loss arising from its use. By using it you accept all risk.
 set -uo pipefail
 
-VERSION="0.1.0"
+VERSION="0.1.2"
 
 # 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
@@ -27,6 +27,7 @@ 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"
+ENABLED_FLAG="$CCS_HOME/firehose.enabled"
 CONTAINER="${CCS_CONTAINER:-ccs-tts}"
 IMAGE="${CCS_IMAGE:-claude-can-speak:latest}"
 MODELS_DIR="${CCS_MODELS_DIR:-$HOME/.cache/claude-can-speak/models}"
@@ -64,10 +65,12 @@ USAGE
   claude-can-speak <command> [args]
 
 COMMANDS
-  status            Show gate state, container, config, and model cache.
+  setup             One-shot install: Docker check, build, skill, hook.
+  on | off          Turn the firehose (speak every reply) on or off. Default off.
+  status            Show firehose 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).
+  say <text>        Speak arbitrary text now (always speaks; used by the skill).
   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).
@@ -81,16 +84,19 @@ COMMANDS
   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'.
+  Deliberate (the headline): the 'speak' skill lets Claude choose what to
+             voice (notifications, shoutouts) via 'claude-can-speak say'.
+             Install with 'claude-can-speak install-skill'.
+  Firehose (optional): the Stop hook speaks every reply when the firehose is
+             on. Install the hook with 'claude-can-speak install-hooks', then
+             toggle with 'claude-can-speak 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.
+  The firehose has its own explicit on/off switch ('claude-can-speak on|off',
+  default OFF), stored in ~/.config/claude-can-speak/firehose.enabled. It is
+  intentionally NOT tied to Claude Code's /voice, which is speech-IN dictation
+  and is a separate concern. The deliberate 'speak' skill always speaks when
+  invoked, regardless of the firehose switch.
 
 DISCLAIMER
   Provided AS IS, with NO WARRANTY. You accept all risk. See the project
@@ -179,12 +185,11 @@ cmd_test() {
 
 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)"
+  printf 'firehose     : '
+  if [ -f "$ENABLED_FLAG" ]; then
+    echo "ON  (replies spoken; 'claude-can-speak off' to silence)"
   else
-    echo "off (/voice disabled) - replies will be silent"
+    echo "off (replies silent; 'claude-can-speak on' to enable)"
   fi
   printf 'engine/voice : %s / %s (%s)\n' "$ENGINE" "$VOICE" "$LANG"
   printf 'image        : '; ensure_image && echo "$IMAGE present" || echo "$IMAGE MISSING (run: build)"
@@ -233,6 +238,41 @@ EOF
   fi
 }
 
+cmd_on() {
+  mkdir -p "$CCS_HOME"
+  : > "$ENABLED_FLAG"
+  echo "firehose ON: replies will be spoken (needs the Stop hook; run install-hooks if you have not)."
+}
+
+cmd_off() {
+  rm -f "$ENABLED_FLAG" 2>/dev/null
+  # Also stop anything currently speaking.
+  cmd_stop >/dev/null 2>&1 || true
+  echo "firehose OFF: replies will not be spoken."
+}
+
+# One-shot setup: the happy path after `npm install -g`. Docker check, build the
+# image, install the deliberate skill and the firehose hook. Idempotent.
+cmd_setup() {
+  echo "claude-can-speak setup"
+  require_docker
+  echo "1/3 building the TTS container image (first time pulls deps, ~2 min) ..."
+  cmd_build
+  echo "2/3 installing the 'speak' skill ..."
+  cmd_install_skill
+  echo "3/3 installing the firehose Stop hook ..."
+  cmd_install_hooks
+  cat <<EOF
+
+Setup complete.
+  - Deliberate mode: Claude can voice notifications via the 'speak' skill (active now).
+  - Firehose mode:   turn it on with 'claude-can-speak on' (off by default).
+  Restart Claude Code once so it loads the new skill and hook, then try:
+    claude-can-speak on
+    claude-can-speak test
+EOF
+}
+
 cmd_install_skill() {
   # Locate the packaged skill (deb vs git checkout).
   local src
@@ -280,6 +320,9 @@ cmd_remove_hooks() {
 }
 
 case "${1:-help}" in
+  setup)          cmd_setup ;;
+  on)             cmd_on ;;
+  off)            cmd_off ;;
   status)         cmd_status ;;
   test)           shift; cmd_test "$@" ;;
   say)            shift; cmd_say "$@" ;;

package/bin/postinstall.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Printed once after `npm install -g claude-can-speak`. Deliberately does NO
+// heavy or side-effecting work (no docker build, no editing ~/.claude): it only
+// tells the user the single next command. The real setup is explicit and
+// user-chosen, which keeps `npm install` fast, quiet, and unsurprising.
+"use strict";
+
+// Skip the banner in CI / non-interactive installs to avoid log noise.
+if (process.env.CI || process.env.npm_config_loglevel === "silent") process.exit(0);
+
+const L = [
+  "",
+  "  claude-can-speak installed.",
+  "",
+  "  One more step (needs Docker):",
+  "      claude-can-speak setup",
+  "",
+  "  That builds the local TTS container and installs the 'speak' skill",
+  "  plus the optional firehose hook. Then restart Claude Code once.",
+  "",
+  "  Deliberate mode (Claude voices notifications) is on after setup.",
+  "  Firehose mode (speak every reply) is off by default; turn it on with:",
+  "      claude-can-speak on",
+  "",
+  "  Provided AS IS, no warranty. https://ra-yavuz.github.io/claude-can-speak/",
+  "",
+];
+process.stdout.write(L.join("\n") + "\n");

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

@@ -17,7 +17,6 @@ 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}"
@@ -51,23 +50,13 @@ done
 # --- 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; }
+# --- Gate: only speak when the firehose is explicitly ON ------------------
+# claude-can-speak owns its own on/off state, decoupled from Claude Code's
+# /voice (which is speech-IN dictation and is not reliably readable here).
+# Default is OFF: the state file exists only when the user ran
+# `claude-can-speak on`. This guarantees a real, predictable off-switch.
+ENABLED_FLAG="${CCS_ENABLED_FLAG:-$CCS_HOME/firehose.enabled}"
+[ -f "$ENABLED_FLAG" ] || { log "firehose off; silent"; exit 0; }
 
 # --- Extract the reply text ----------------------------------------------
 extract_text() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.1.2",
+  "description": "Let Claude Code decide what to say out loud: a skill that voices deliberate notifications (not every reply), plus an optional speak-everything Stop hook. Local neural TTS via Kokoro/Piper in Docker, gated on /voice.",
   "keywords": [
     "claude",
     "claude-code",
@@ -28,8 +28,12 @@
   "bin": {
     "claude-can-speak": "bin/cli.js"
   },
+  "scripts": {
+    "postinstall": "node bin/postinstall.js"
+  },
   "files": [
     "bin/cli.js",
+    "bin/postinstall.js",
     "bin/claude-can-speak",
     "lib/claude-can-speak/",
     "container/",