claude-can-speak 0.1.1 → 0.1.3

package/README.md

@@ -8,15 +8,22 @@ 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.
+If you *do* want the firehose, it is one switch away: a Stop hook that speaks
+every finished reply, with its own explicit on/off (`claude-can-speak on` /
+`off`, off by default). 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`.
+  to voice. Active after `claude-can-speak setup`.
+- **Firehose mode (optional)** - a Stop hook speaks every reply when you turn it
+  on with `claude-can-speak on` (off by default), or `/ccs on` from inside
+  Claude Code.
+
+> **The toggle is a command, not a built-in slash setting.** claude-can-speak
+> does not hook into Claude Code's `/voice`; if you type `/` in Claude Code
+> before setup and find nothing, that is expected. Control the firehose from the
+> terminal with `claude-can-speak on` / `off`, or from inside Claude Code with
+> the `/ccs on` / `/ccs off` / `/ccs status` slash command that `setup`
+> installs.
 
 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)
@@ -37,40 +44,61 @@ network at speak time, no telemetry.
 
 ```sh
 npm install -g claude-can-speak
-
-# one-time: build the local TTS container image (needs Docker)
-claude-can-speak build
+claude-can-speak setup     # Docker check, build image, install skill + hook
 ```
 
+`setup` is the one command that does everything (it needs Docker). Then
+**restart Claude Code once** so it loads the new skill and hook.
+
 > 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:
+`setup` also installs a `/ccs` slash command into Claude Code, so the firehose
+toggle is reachable from where you would instinctively look for it. **Restart
+Claude Code once** after setup so it discovers the skill and the command.
+
+After setup:
+
+- **Deliberate mode** (the headline) is active: Claude can voice notifications
+  through the `speak` skill whenever it judges something worth hearing.
+- **Firehose mode** (speak every reply) is **off by default**. Turn it on when
+  you want it, from the terminal or from inside Claude Code:
 
 ```sh
-claude-can-speak install-skill    # deliberate mode: the 'speak' skill
-claude-can-speak install-hooks    # firehose mode: speak every reply on /voice
+claude-can-speak on      # speak every reply
+claude-can-speak off     # back to silent (default)
+```
+
+```text
+/ccs on        # same, from inside Claude Code
+/ccs off
+/ccs status
 ```
 
 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:
+Check everything with:
 
 ```sh
 claude-can-speak status
 claude-can-speak test          # speak a sample line
 ```
 
+If you prefer to do the steps by hand instead of `setup`: `claude-can-speak
+build`, then `claude-can-speak install-skill` and/or `claude-can-speak
+install-hooks`.
+
 ## 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 on | off          # firehose: speak every reply, or not (default off)
+claude-can-speak say <text>        # speak text now (always speaks; used by the skill)
 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
@@ -102,7 +130,7 @@ claude-can-speak voice tr_TR-dfki-medium     # Turkish
 ## How it works
 
 ```
-Claude Code reply ─▶ Stop hook (gated on /voice) ─▶ strip markdown & code
+Claude Code reply ─▶ Stop hook (when firehose on) ─▶ strip markdown & code
                                                    ─▶ docker exec synth (Kokoro/Piper)
                                                    ─▶ play WAV on the host
 ```
@@ -118,8 +146,11 @@ 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.
+The firehose on/off state is a single file, `~/.config/claude-can-speak/firehose.enabled`
+(present = on, absent = off), written by `claude-can-speak on` / `off`. It is
+deliberately independent of Claude Code's `/voice`, which is speech-in dictation,
+a separate concern. The `speak` skill is toggled via `skillOverrides` in
+`~/.claude/settings.json`.
 
 ## Uninstall
 
@@ -154,9 +185,9 @@ 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.
+also adds multilingual output (Piper for German, Turkish, and more) and Docker
+isolation so the engines never touch your host Python. The firehose mode is
+included, with its own explicit on/off switch, but it is not the headline.
 
 ## Licence
 

package/bin/claude-can-speak

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# claude-can-speak: speech-out for Claude Code, gated on /voice mode.
+# claude-can-speak: speech-out for Claude Code (deliberate skill + optional firehose).
 #
 # 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,
@@ -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.1"
+VERSION="0.1.3"
 
 # 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}"
@@ -58,16 +59,18 @@ require_docker() {
 
 cmd_help() {
   cat <<EOF
-claude-can-speak $VERSION - speech-out for Claude Code (gated on /voice)
+claude-can-speak $VERSION - speech-out for Claude Code
 
 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).
@@ -76,21 +79,28 @@ COMMANDS
   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.
+  install-command   Install the '/ccs' slash command into ~/.claude/commands.
+  remove-command    Remove the '/ccs' slash command.
   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'.
+  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' from the terminal, or
+             '/ccs on' / '/ccs off' from inside Claude Code (the /ccs slash
+             command is a convenience wrapper; run 'install-command' to add it).
 
 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 +189,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 +242,45 @@ 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/4 installing the 'speak' skill ..."
+  cmd_install_skill
+  echo "3/4 installing the '/ccs' slash command ..."
+  cmd_install_command
+  echo "4/4 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, the /ccs command, and the
+  hook. After that you can toggle the firehose from inside Claude Code with
+  '/ccs on' and '/ccs off', or from the terminal:
+    claude-can-speak on
+    claude-can-speak test
+EOF
+}
+
 cmd_install_skill() {
   # Locate the packaged skill (deb vs git checkout).
   local src
@@ -247,6 +295,25 @@ cmd_install_skill() {
   echo "if ~/.claude/skills did not exist before, restart your session to discover it."
 }
 
+cmd_install_command() {
+  # Locate the packaged slash command (deb vs git checkout).
+  local src
+  for cand in "/usr/share/claude-can-speak/commands/ccs.md" "$SELF/../commands/ccs.md"; do
+    [ -f "$cand" ] && { src="$cand"; break; }
+  done
+  [ -n "${src:-}" ] || die "packaged slash command not found"
+  local dest="$HOME/.claude/commands/ccs.md"
+  mkdir -p "$(dirname "$dest")"
+  cp "$src" "$dest"
+  echo "installed '/ccs' slash command -> $dest"
+  echo "restart Claude Code once so it discovers the new command, then use /ccs status."
+}
+
+cmd_remove_command() {
+  local dest="$HOME/.claude/commands/ccs.md"
+  if [ -f "$dest" ]; then rm -f "$dest"; echo "removed '/ccs' slash command"; else echo "'/ccs' not installed"; fi
+}
+
 cmd_skill() {
   case "${1:-}" in
     on)  _skill_override on;  echo "'speak' skill enabled" ;;
@@ -280,6 +347,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 "$@" ;;
@@ -292,6 +362,8 @@ case "${1:-help}" in
   install-hooks)  cmd_install_hooks ;;
   remove-hooks)   cmd_remove_hooks ;;
   install-skill)  cmd_install_skill ;;
+  install-command) cmd_install_command ;;
+  remove-command)  cmd_remove_command ;;
   skill)          shift; cmd_skill "${1:-}" ;;
   build)          cmd_build ;;
   help|-h|--help) cmd_help ;;

package/bin/postinstall.js

@@ -0,0 +1,29 @@
+#!/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,",
+  "  the '/ccs' slash command, and 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 from the",
+  "  terminal with 'claude-can-speak on', or inside Claude Code with '/ccs on'.",
+  "",
+  "  Provided AS IS, no warranty. https://ra-yavuz.github.io/claude-can-speak/",
+  "",
+];
+process.stdout.write(L.join("\n") + "\n");

package/commands/ccs.md

@@ -0,0 +1,22 @@
+---
+description: Control claude-can-speak (status / on / off)
+argument-hint: [status|on|off]
+allowed-tools: Bash(claude-can-speak:*)
+---
+
+The user invoked the claude-can-speak control command with argument: "$ARGUMENTS"
+
+Run the matching CLI command and report the result plainly. The argument is one
+of `status` (default if empty), `on`, or `off`:
+
+- empty or `status` -> show current state:
+  !`claude-can-speak status`
+- `on` -> turn the speak-every-reply firehose on:
+  !`if [ "$ARGUMENTS" = "on" ]; then claude-can-speak on; fi`
+- `off` -> turn the firehose off (replies go silent again):
+  !`if [ "$ARGUMENTS" = "off" ]; then claude-can-speak off; fi`
+
+Note for the user if relevant: `claude-can-speak` is a terminal command too; this
+slash command is just a convenience wrapper so the firehose toggle is reachable
+from inside Claude Code. The firehose hook hot-reloads, so `on`/`off` take effect
+on the next reply without restarting the session.

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,6 +1,6 @@
 {
   "name": "claude-can-speak",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",
@@ -28,12 +28,17 @@
   "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/",
     "skills/",
+    "commands/",
     "THIRD_PARTY.md",
     "LICENSE",
     "README.md"