@domdhi/claude-code-tts 1.0.0 → 1.1.0

package/.claude/commands/voice/off.md

@@ -0,0 +1,7 @@
+Disable TTS voice output by removing the enable file. Run the appropriate command for your OS silently using the Bash tool, then respond with only: "TTS disabled."
+
+Mac/Linux:
+rm -f ~/.claude/hooks/tts/on
+
+Windows:
+del /F "%USERPROFILE%\.claude\hooks\tts\on" 2>nul

package/.claude/commands/voice/on.md

@@ -0,0 +1,7 @@
+Enable TTS voice output by creating the enable file. Run the appropriate command for your OS silently using the Bash tool, then respond with only: "TTS enabled."
+
+Mac/Linux:
+touch ~/.claude/hooks/tts/on
+
+Windows:
+echo. > "%USERPROFILE%\.claude\hooks\tts\on"

package/.claude/commands/voice/repeat.md

@@ -0,0 +1 @@
+/voice:repeat

package/.claude/commands/voice/stop.md

@@ -0,0 +1 @@
+/voice:stop

package/INSTALL.md

@@ -21,46 +21,68 @@ Full reference for install options, voice configuration, hooks wiring, and troub
 
 ## Install
 
-### Option A — installer script (recommended)
+### Option A — npx (recommended)
 
 ```bash
-git clone https://github.com/domdhi/claude-code-tts
-cd claude-code-tts
-pip install edge-tts miniaudio sounddevice cffi
-python install.py
+# Install for current project only (commands + settings.local.json in ./.claude/)
+npx @domdhi/claude-code-tts
+
+# Install globally (commands + settings.json in ~/.claude/, all projects)
+npx @domdhi/claude-code-tts --global
 ```
 
-The installer:
+Requires Node.js 16+ and Python 3.10+. No cloning required.
+
+The installer automatically:
 1. Checks Python version (3.10+ required)
-2. Installs required packages
-3. Copies hook files to `~/.claude/hooks/tts/`
+2. Installs required packages (`edge-tts`, `miniaudio`, `sounddevice`, `cffi`)
+3. Copies hook scripts to `~/.claude/hooks/tts/`
 4. Creates the `on` file (TTS enabled immediately)
 5. Optionally installs kokoro-onnx offline fallback (~82MB)
-6. Prints the `settings.json` snippet to add
+6. Installs `/voice:*` slash commands
+7. Patches `settings.json` / `settings.local.json` with hook entries (backs up original first)
+
+**Local vs global:**
+- Default (no flag): commands go to `./.claude/commands/voice/`, hooks registered in `./.claude/settings.local.json` (gitignored — safe to commit the project)
+- `--global`: commands go to `~/.claude/commands/voice/`, hooks registered in `~/.claude/settings.json`
+
+### Option B — installer script
+
+```bash
+git clone https://github.com/Domdhi/claude-code-tts
+cd claude-code-tts
+pip install edge-tts miniaudio sounddevice cffi
+python install.py           # project-local
+python install.py --global  # global (all projects)
+```
 
-### Option B — manual
+### Option C — manual (Mac/Linux)
 
 ```bash
 # Install packages
 pip install edge-tts miniaudio sounddevice cffi
 
-# Create install dir
+# Copy hook scripts
 mkdir -p ~/.claude/hooks/tts
+cp .claude/hooks/tts/daemon.py .claude/hooks/tts/stop.py \
+   .claude/hooks/tts/task-hook.py .claude/hooks/tts/repeat.py \
+   .claude/hooks/tts/voices.json ~/.claude/hooks/tts/
 
-# Copy files
-cp daemon.py stop.py task-hook.py repeat.py voices.json ~/.claude/hooks/tts/
+# Copy slash commands (global)
+mkdir -p ~/.claude/commands/voice
+cp .claude/commands/voice/*.md ~/.claude/commands/voice/
 
 # Enable TTS
 touch ~/.claude/hooks/tts/on
 ```
 
-Then add the settings.json snippet below manually.
+Then add the settings snippet below manually.
 
 ---
 
 ## Claude Code Settings
 
-Add to `~/.claude/settings.json`. If you already have a `"hooks"` key, merge these entries — don't replace the whole object.
+The installer patches this automatically. For manual setup, add to `~/.claude/settings.json` (global) or `.claude/settings.local.json` (project-local, gitignored). If you already have a `"hooks"` key, merge these entries — don't replace the whole object.
 
 **Mac/Linux:**
 ```json
@@ -259,8 +281,10 @@ Type in the Claude Code prompt:
 
 | Prompt | Effect |
 |--------|--------|
-| `/voice:stop` or `/stop` | Stop speech immediately, clear queue |
-| `/repeat` | Replay last spoken response |
+| `/voice:stop` | Stop speech immediately, clear queue |
+| `/voice:repeat` | Replay last spoken response |
+| `/voice:on` | Re-enable TTS (creates `on` file) |
+| `/voice:off` | Disable TTS (removes `on` file) |
 
 ---
 
@@ -294,10 +318,10 @@ After editing daemon.py, restart the daemon:
 # Mac/Linux
 pkill -f daemon.py
 
-# Windows
-taskkill /F /IM python.exe  # kills all python processes
+# Windows (kills all Python processes — close other Python apps first)
+taskkill /F /IM python.exe
 ```
-The daemon auto-restarts on the next response.
+The daemon auto-restarts on the next Claude response.
 
 ---
 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Domdhi
+
+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

@@ -4,26 +4,31 @@ Neural TTS hook system for [Claude Code](https://claude.ai/code). Reads Claude's
 
 **Engines:** Edge TTS (Microsoft neural voices, free, requires internet) with automatic offline fallback to kokoro-onnx.
 **Platform:** Windows, macOS, Linux
-**Install:** one Python script, no build tools required
+**Install:** one command, no build tools required
 
 ---
 
 ## Quick Start
 
 ```bash
+# Install for current project only
 npx @domdhi/claude-code-tts
+
+# Install globally (all projects)
+npx @domdhi/claude-code-tts --global
 ```
 
-That's it. The installer copies the hook files, enables TTS, optionally installs the offline fallback, and prints the `settings.json` snippet to add to Claude Code.
+That's it. The installer copies the hook files, enables TTS, optionally installs the offline fallback, and automatically patches `settings.json` and installs the slash commands.
 
 **Requirements:** Node.js 16+ and Python 3.10+ must both be installed. The hooks run in Python — Node is only used for the install command.
 
 **Or install manually:**
 ```bash
-git clone https://github.com/domdhi/claude-code-tts
+git clone https://github.com/Domdhi/claude-code-tts
 cd claude-code-tts
 pip install edge-tts miniaudio sounddevice cffi
-python install.py
+python install.py           # project-local
+python install.py --global  # all projects
 ```
 
 ---
@@ -36,7 +41,7 @@ Three Claude Code hooks work together:
 |------|------|---------------|
 | `Stop` | `stop.py` | After every Claude response — reads it aloud |
 | `PostToolUse:Task` | `task-hook.py` | After a subagent finishes — reads its output |
-| `UserPromptSubmit` | `repeat.py` | On `/repeat` or `/voice:stop` commands |
+| `UserPromptSubmit` | `repeat.py` | On `/voice:repeat` or `/voice:stop` commands |
 
 A persistent daemon (`daemon.py`) keeps the TTS model loaded in the background. Hook files connect to it via TCP on `localhost:6254`, starting it automatically if needed.
 
@@ -62,16 +67,15 @@ Edit `~/.claude/hooks/tts/voices.json` to customize voices per agent or per proj
 | `am_liam` | RyanNeural | energetic male |
 | `am_onyx` | ChristopherNeural | authoritative male |
 
-**Per-agent voices** (add to `voices.json`):
+**Per-agent voices** — `task-hook.py` reads `subagent_type` from the Task tool and looks up the agent by name:
 ```json
 {
   "default": {"voice": "af_heart", "speed": 1.0},
   "general-purpose": {"voice": "am_michael", "speed": 1.0}
 }
 ```
-The `task-hook.py` reads `subagent_type` from the Task tool input to look up the agent's voice automatically.
 
-**Per-project voices** (add a `"projects"` section):
+**Per-project voices** — add a `"projects"` section with keys matched against the project path:
 ```json
 {
   "projects": {
@@ -79,16 +83,16 @@ The `task-hook.py` reads `subagent_type` from the Task tool input to look up the
   }
 }
 ```
-Project keys are matched as case-insensitive substrings of the encoded project path under `~/.claude/projects/`.
 
-**Per-agent prefix** — any agent that begins its response with `[AgentName]:` gets routed to that voice:
+**Per-agent prefix** — add `Always begin your response with [AgentName]:` to an agent's system prompt, then add it to `voices.json`:
 ```json
 {
   "MyAgent": {"voice": "am_adam", "speed": 0.9}
 }
 ```
+The hook strips the `[AgentName]:` prefix before speaking.
 
-See [INSTALL.md](INSTALL.md) for full configuration reference.
+See [INSTALL.md](INSTALL.md) for the full configuration reference.
 
 ---
 
@@ -99,7 +103,9 @@ Type these in the Claude Code prompt:
 | Command | Effect |
 |---------|--------|
 | `/voice:stop` | Stop speech immediately |
-| `/repeat` | Replay last response |
+| `/voice:repeat` | Replay last response |
+| `/voice:on` | Re-enable TTS |
+| `/voice:off` | Disable TTS |
 
 ---
 
@@ -111,9 +117,11 @@ TTS is controlled by the presence of an `on` file in the install directory:
 # Disable
 rm ~/.claude/hooks/tts/on
 
-# Re-enable
-touch ~/.claude/hooks/tts/on          # Mac/Linux
-echo. > %USERPROFILE%\.claude\hooks\tts\on  # Windows
+# Re-enable (Mac/Linux)
+touch ~/.claude/hooks/tts/on
+
+# Re-enable (Windows cmd)
+echo. > %USERPROFILE%\.claude\hooks\tts\on
 ```
 
 ---
@@ -121,13 +129,14 @@ echo. > %USERPROFILE%\.claude\hooks\tts\on  # Windows
 ## Requirements
 
 - Python 3.10+
+- Node.js 16+ (for `npx` install only)
 - Claude Code
 - Internet connection (for Edge TTS primary engine)
-- `edge-tts`, `miniaudio`, `sounddevice`, `cffi`
+- `edge-tts`, `miniaudio`, `sounddevice`, `cffi` (installed automatically)
 - Optional: `kokoro-onnx` + model files (~82MB) for offline fallback
 
 ---
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE)

package/install.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
 """
 claude-code-tts installer
-Copies hook files into ~/.claude/hooks/tts/ and prints the settings.json snippet.
+Copies hook files to ~/.claude/hooks/tts/, installs slash commands, and patches settings.json.
 """
 
 import argparse
+import json
 import os
 import shutil
 import subprocess
@@ -24,12 +25,25 @@ KOKORO_MODEL_URLS = [
     ),
 ]
 
-# voices.json is excluded from HOOK_FILES — handled separately to avoid clobbering customizations
+# voices.json is excluded from HOOK_FILES -- handled separately to avoid clobbering customizations
 HOOK_FILES = ['daemon.py', 'stop.py', 'task-hook.py', 'repeat.py']
+COMMAND_FILES = ['stop.md', 'repeat.md', 'on.md', 'off.md']
 
-INSTALL_DIR = os.path.join(os.path.expanduser('~'), '.claude', 'hooks', 'tts')
-MODELS_DIR = os.path.join(INSTALL_DIR, 'models')
 SOURCE_DIR = os.path.dirname(os.path.abspath(__file__))
+HOOKS_SOURCE    = os.path.join(SOURCE_DIR, '.claude', 'hooks', 'tts')
+COMMANDS_SOURCE = os.path.join(SOURCE_DIR, '.claude', 'commands', 'voice')
+
+INSTALL_DIR          = os.path.join(os.path.expanduser('~'), '.claude', 'hooks', 'tts')
+MODELS_DIR           = os.path.join(INSTALL_DIR, 'models')
+
+# Default: project-local install (current directory's .claude/)
+# Overridden to ~/.claude/ when --global is passed
+_project_claude      = os.path.join(os.getcwd(), '.claude')
+COMMANDS_INSTALL_DIR = os.path.join(_project_claude, 'commands', 'voice')
+# Use settings.local.json for local scope — gitignored, machine-specific (absolute Python paths)
+SETTINGS_FILE        = os.path.join(_project_claude, 'settings.local.json')
+
+GLOBAL_SCOPE = False
 
 
 def step(msg):
@@ -83,7 +97,7 @@ def create_dirs():
 def copy_files():
     step('Copying hook files...')
     for filename in HOOK_FILES:
-        src = os.path.join(SOURCE_DIR, filename)
+        src = os.path.join(HOOKS_SOURCE, filename)
         dst = os.path.join(INSTALL_DIR, filename)
         if not os.path.exists(src):
             fail(f'Source file not found: {src}')
@@ -91,8 +105,8 @@ def copy_files():
         shutil.copy2(src, dst)
         ok(filename)
 
-    # voices.json: only copy on first install — preserve existing customizations
-    voices_src = os.path.join(SOURCE_DIR, 'voices.json')
+    # voices.json: only copy on first install -- preserve existing customizations
+    voices_src = os.path.join(HOOKS_SOURCE, 'voices.json')
     voices_dst = os.path.join(INSTALL_DIR, 'voices.json')
     if os.path.exists(voices_dst):
         ok('voices.json (kept existing, not overwritten)')
@@ -101,6 +115,19 @@ def copy_files():
         ok('voices.json')
 
 
+def copy_commands():
+    step('Installing slash command files...')
+    os.makedirs(COMMANDS_INSTALL_DIR, exist_ok=True)
+    for filename in COMMAND_FILES:
+        src = os.path.join(COMMANDS_SOURCE, filename)
+        dst = os.path.join(COMMANDS_INSTALL_DIR, filename)
+        if not os.path.exists(src):
+            warn(f'Command file not found: {src} -- skipping')
+            continue
+        shutil.copy2(src, dst)
+        ok(filename)
+
+
 def enable_tts():
     step('Enabling TTS (creating on file)...')
     on_file = os.path.join(INSTALL_DIR, 'on')
@@ -149,119 +176,159 @@ def offer_kokoro():
             ok(filename)
     except Exception as e:
         fail(f'Model download failed: {e}')
-        print('    You can download manually — see INSTALL.md for URLs.')
+        print('    You can download manually -- see INSTALL.md for URLs.')
+
+
+def _hook_command(script_name):
+    """Return the shell command string for a given hook script."""
+    path = os.path.join(INSTALL_DIR, script_name)
+    return f'{sys.executable} "{path}"'
 
 
-def print_settings_snippet():
-    tts_dir = INSTALL_DIR.replace('\\', '\\\\')
+def _has_command(hook_list, command):
+    """Return True if command already appears in any entry in hook_list."""
+    for entry in hook_list:
+        for h in entry.get('hooks', []):
+            if h.get('command') == command:
+                return True
+    return False
+
 
-    if sys.platform == 'win32':
-        py = sys.executable.replace('\\', '\\\\')
-        stop_cmd   = f'{py} \\"{tts_dir}\\\\stop.py\\"'
-        task_cmd   = f'{py} \\"{tts_dir}\\\\task-hook.py\\"'
-        repeat_cmd = f'{py} \\"{tts_dir}\\\\repeat.py\\"'
+def patch_settings_json():
+    step(f'Patching Claude Code settings: {SETTINGS_FILE}')
+
+    stop_cmd   = _hook_command('stop.py')
+    task_cmd   = _hook_command('task-hook.py')
+    repeat_cmd = _hook_command('repeat.py')
+
+    # Load existing settings (or start fresh)
+    settings = {}
+    if os.path.exists(SETTINGS_FILE):
+        try:
+            with open(SETTINGS_FILE, 'r', encoding='utf-8') as f:
+                settings = json.load(f)
+        except Exception as e:
+            warn(f'Could not parse settings.json: {e}')
+            warn('Skipping auto-patch. Add the hooks manually -- see INSTALL.md.')
+            return
+
+    hooks = settings.setdefault('hooks', {})
+    changed = False
+
+    # Stop hook
+    if not _has_command(hooks.get('Stop', []), stop_cmd):
+        hooks.setdefault('Stop', []).append({
+            'hooks': [{'type': 'command', 'command': stop_cmd}]
+        })
+        changed = True
+        ok('Added Stop hook')
     else:
-        py = sys.executable
-        stop_cmd   = f'{py} "{INSTALL_DIR}/stop.py"'
-        task_cmd   = f'{py} "{INSTALL_DIR}/task-hook.py"'
-        repeat_cmd = f'{py} "{INSTALL_DIR}/repeat.py"'
-
-    snippet = f'''{{
-  "hooks": {{
-    "Stop": [
-      {{
-        "hooks": [
-          {{
-            "type": "command",
-            "command": "{stop_cmd}"
-          }}
-        ]
-      }}
-    ],
-    "PostToolUse": [
-      {{
-        "matcher": "Task",
-        "hooks": [
-          {{
-            "type": "command",
-            "command": "{task_cmd}"
-          }}
-        ]
-      }}
-    ],
-    "UserPromptSubmit": [
-      {{
-        "hooks": [
-          {{
-            "type": "command",
-            "command": "{repeat_cmd}"
-          }}
-        ]
-      }}
-    ]
-  }}
-}}'''
-
-    settings_path = os.path.join(os.path.expanduser('~'), '.claude', 'settings.json')
-    print(f"""
-  -------------------------------------------------------------
-  Add this to your Claude Code settings (~/.claude/settings.json):
+        ok('Stop hook already registered')
+
+    # PostToolUse:Task hook
+    if not _has_command(hooks.get('PostToolUse', []), task_cmd):
+        hooks.setdefault('PostToolUse', []).append({
+            'matcher': 'Task',
+            'hooks': [{'type': 'command', 'command': task_cmd}]
+        })
+        changed = True
+        ok('Added PostToolUse:Task hook')
+    else:
+        ok('PostToolUse:Task hook already registered')
+
+    # UserPromptSubmit hook
+    if not _has_command(hooks.get('UserPromptSubmit', []), repeat_cmd):
+        hooks.setdefault('UserPromptSubmit', []).append({
+            'hooks': [{'type': 'command', 'command': repeat_cmd}]
+        })
+        changed = True
+        ok('Added UserPromptSubmit hook')
+    else:
+        ok('UserPromptSubmit hook already registered')
 
-  If settings.json already has a "hooks" key, merge these entries
-  into your existing hooks object -- don't replace the whole file.
-  -------------------------------------------------------------
+    if not changed:
+        ok('settings.json already up to date')
+        return
 
-{snippet}
+    # Backup before writing
+    if os.path.exists(SETTINGS_FILE):
+        backup = SETTINGS_FILE + '.bak'
+        shutil.copy2(SETTINGS_FILE, backup)
+        ok(f'Backed up original to settings.json.bak')
 
-  Settings file location: {settings_path}
-  -------------------------------------------------------------
-""")
+    os.makedirs(os.path.dirname(SETTINGS_FILE), exist_ok=True)
+    with open(SETTINGS_FILE, 'w', encoding='utf-8') as f:
+        json.dump(settings, f, indent=2)
+    ok(f'settings.json saved')
 
 
 def print_success():
+    on_file = os.path.join(INSTALL_DIR, 'on')
+    scope_note = '(global)' if GLOBAL_SCOPE else '(project-local)'
     print(f"""
-  DONE: claude-code-tts installed to {INSTALL_DIR}
+  DONE: claude-code-tts installed.
+
+  Hooks:     {INSTALL_DIR}
+  Commands:  {COMMANDS_INSTALL_DIR} {scope_note}
+  Settings:  {SETTINGS_FILE} {scope_note}
 
-  Quick test (after adding settings.json snippet):
-    Run Claude Code, ask anything -- response will be read aloud.
+  Quick test:
+    Run Claude Code and ask anything -- the response will be read aloud.
 
   Commands (type in Claude Code prompt):
     /voice:stop    Stop speech immediately
-    /repeat        Replay last response
+    /voice:repeat  Replay last response
+    /voice:on      Re-enable TTS
+    /voice:off     Disable TTS
 
   To disable TTS:
-    Delete {os.path.join(INSTALL_DIR, 'on')}
-
-  To re-enable:
-    touch {os.path.join(INSTALL_DIR, 'on')}   (Mac/Linux)
-    echo. > {os.path.join(INSTALL_DIR, 'on').replace('/', chr(92))}  (Windows)
+    Delete {on_file}
 
   Full docs: INSTALL.md
 """)
 
 
 def main():
-    global INSTALL_DIR, MODELS_DIR
+    global INSTALL_DIR, MODELS_DIR, COMMANDS_INSTALL_DIR, SETTINGS_FILE, GLOBAL_SCOPE
 
     parser = argparse.ArgumentParser(description='claude-code-tts installer')
     parser.add_argument(
         '--dir', metavar='PATH',
-        help='Install hooks to PATH instead of ~/.claude/hooks/tts/'
+        help='Install hooks to PATH instead of ~/.claude/hooks/tts/ (for testing)'
+    )
+    parser.add_argument(
+        '--global', dest='global_scope', action='store_true',
+        help='Install commands and settings into ~/.claude/ (all projects) instead of ./.claude/ (current project)'
     )
     args = parser.parse_args()
 
-    if args.dir:
+    testing = bool(args.dir)
+    if testing:
         INSTALL_DIR = os.path.abspath(args.dir)
         MODELS_DIR = os.path.join(INSTALL_DIR, 'models')
 
-    print('\nclaude-code-tts installer\n')
+    if args.global_scope:
+        GLOBAL_SCOPE = True
+        global_claude = os.path.join(os.path.expanduser('~'), '.claude')
+        COMMANDS_INSTALL_DIR = os.path.join(global_claude, 'commands', 'voice')
+        SETTINGS_FILE = os.path.join(global_claude, 'settings.json')
+
+    scope_label = 'global (~/.claude/)' if args.global_scope else 'project-local (.claude/)'
+    print(f'\nclaude-code-tts installer  [{scope_label}]\n')
     check_python()
     install_packages()
     create_dirs()
     copy_files()
     enable_tts()
     offer_kokoro()
-    print_settings_snippet()
+
+    if testing:
+        step(f'Test install mode (--dir): skipping settings.json patch and command install.')
+        ok(f'Hook files installed to {INSTALL_DIR}')
+    else:
+        copy_commands()
+        patch_settings_json()
+
     print_success()
 
 

package/package.json

@@ -1,19 +1,16 @@
 {
   "name": "@domdhi/claude-code-tts",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Neural TTS hook system for Claude Code. Reads Claude's responses aloud as they finish.",
   "bin": {
     "claude-code-tts": "bin/install.js"
   },
   "files": [
     "bin/",
-    "daemon.py",
-    "stop.py",
-    "task-hook.py",
-    "repeat.py",
-    "voices.json",
+    ".claude/",
     "install.py",
-    "INSTALL.md"
+    "INSTALL.md",
+    "LICENSE"
   ],
   "keywords": [
     "claude",