on

Enable Narrator Voice Output

To enable narrator voice output, perform the following steps in order:

Step 1: Determine Scope

Check if the user said "locally", "for this directory", "for this project", or similar. If so, all state changes apply to a local config file in the current working directory instead of the global one.

• Global (default): ~/.claude-code-narrator/config
• Local: <cwd>/.claude-code-narrator/config

Step 2: Enable Narrator State

Global mode (default):

Read ~/.claude-code-narrator/config. If the file exists, use the Edit tool to change the enabled= line to enabled=true (preserve the existing voice and speed settings). If the file does not exist, create it with the Write tool:

enabled=true
voice=af_heart
speed=1.1

Local mode:

Read <cwd>/.claude-code-narrator/config. If the file exists, use the Edit tool to change or add enabled=true. If the file does not exist, create the <cwd>/.claude-code-narrator/ directory if needed, then create the config file with the Write tool containing just enabled=true. Do NOT include voice or speed unless the user specifies them — missing keys fall back to the global state.

IMPORTANT: Do NOT use sed to edit state files — use the Read and Edit tools instead.

Step 3: Register Auto-Hush Hook

Read ~/.claude/settings.json. If it does not have a UserPromptSubmit hook that runs hush-on-input.sh, add one. This hook silences speech when the user provides input.

Use the Edit tool to add the following to the hooks object in ~/.claude/settings.json (create the hooks key if it doesn't exist, and merge with any existing hooks):

"UserPromptSubmit": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/hush-on-input.sh",
        "timeout": 3
      }
    ]
  }
]

IMPORTANT: Do NOT replace existing hooks — merge with them. Read the file first.

Step 4: Confirm

For global mode, inform the user: "Narrator is now enabled. I will speak responses aloud using the af_heart voice."

For local mode, inform the user: "Narrator is now enabled for this directory. Voice and speed will fall back to global settings unless overridden locally."

Also remind the user to add the local config to their gitignore if they haven't already:

Tip: Add the local config to your .gitignore so it's not committed:

echo .claude-code-narrator >> .gitignore

Then speak a test confirmation. This will auto-install Kokoro TTS into a dedicated venv on first run (may take a few minutes):

echo "Narrator is now active." | bash "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/speak.sh" --force