claude-can-speak 0.1.2 → 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.2"
+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
@@ -59,7 +59,7 @@ 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]
@@ -79,6 +79,8 @@ 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.
@@ -89,7 +91,9 @@ TWO MODES
              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'.
+             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
   The firehose has its own explicit on/off switch ('claude-can-speak on|off',
@@ -258,16 +262,20 @@ cmd_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 ..."
+  echo "2/4 installing the 'speak' skill ..."
   cmd_install_skill
-  echo "3/3 installing the firehose Stop hook ..."
+  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 and hook, then try:
+  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
@@ -287,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" ;;
@@ -335,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

@@ -15,12 +15,13 @@ const L = [
   "  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.",
+  "  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 with:",
-  "      claude-can-speak on",
+  "  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/",
   "",

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-can-speak",
-  "version": "0.1.2",
+  "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",
@@ -38,6 +38,7 @@
     "lib/claude-can-speak/",
     "container/",
     "skills/",
+    "commands/",
     "THIRD_PARTY.md",
     "LICENSE",
     "README.md"