vocalize-cli 0.1.1__tar.gz

vocalize_cli-0.1.1/.env.example

@@ -0,0 +1,3 @@
+# Copy this file to .env and fill in your key.
+# Get a free key at https://elevenlabs.io/app/settings/api-keys
+ELEVENLABS_API_KEY=your-api-key-here

vocalize_cli-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev,dotenv]"
+      - run: ruff check .
+      - run: pytest -v --cov=vocalize --cov=hooks --cov-report=term-missing

vocalize_cli-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+htmlcov/
+.env
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+*.mp3
+*.wav

vocalize_cli-0.1.1/LICENSE

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

vocalize_cli-0.1.1/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.5
+Name: vocalize-cli
+Version: 0.1.1
+Summary: A CLI that turns text, markdown, or piped stdin into speech via the ElevenLabs API, with markdown-table-aware preprocessing.
+Project-URL: Homepage, https://github.com/matthager12-collab/vocalize
+Project-URL: Repository, https://github.com/matthager12-collab/vocalize
+Author: Mat
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,cli,elevenlabs,markdown,text-to-speech
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: elevenlabs>=2.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.0; extra == 'dotenv'
+Description-Content-Type: text/markdown
+
+# vocalize
+
+[![CI](https://github.com/matthager12-collab/vocalize/actions/workflows/ci.yml/badge.svg)](https://github.com/matthager12-collab/vocalize/actions/workflows/ci.yml)
+
+A command-line tool that turns text, markdown files, or piped stdin into
+natural-sounding speech using the [ElevenLabs](https://elevenlabs.io) API —
+plus a hook that wires it directly into [Claude Code](https://claude.com/claude-code),
+so Claude's responses get read aloud automatically in your terminal or IDE.
+
+## Why this exists
+
+Text-to-speech readers are good at *voices* and bad at *structure*. Point one
+at a markdown report and it reads a table cell-by-cell, left to right, with
+no sense of which row or column you're in — "Q1. 4.2 million. Q2. 5.1
+million" instead of "for Q1, revenue is 4.2 million." Headings, bullet
+lists, and inline code fare the same way: read exactly as typed, syntax and
+all.
+
+`vocalize` fixes the part of that problem that's actually fixable without a
+vision model: a preprocessing pass (`vocalize/preprocess.py`) rewrites
+markdown into short, declarative sentences *before* it ever reaches the TTS
+API — tables become "for X, Y is Z" sentences, bullets become "First, ...
+Second, ...", links keep their text and drop the URL, and fenced code blocks
+are replaced with a spoken placeholder instead of being read character by
+character. It's a text transform, so it's fully unit tested without any
+API key or network access (see `tests/test_preprocess.py`).
+
+## Install
+
+```bash
+pipx install vocalize-cli
+```
+
+(or `uvx --from vocalize-cli vocalize` for a one-off run without installing
+anything). The package is published on PyPI as `vocalize-cli`; the command
+it installs is still `vocalize`.
+
+For a from-source or dev install:
+
+```bash
+git clone <this-repo>
+cd vocalize
+pip install -e .
+```
+
+Get a free ElevenLabs API key at
+[elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys)
+(free tier: 10,000 characters/month, API access included, no commercial
+license). Then either:
+
+```bash
+export ELEVENLABS_API_KEY=your-key-here
+```
+
+or copy `.env.example` to `.env` and fill it in (requires the optional
+`python-dotenv` extra: `pip install -e ".[dotenv]"`).
+
+## Usage
+
+```bash
+# Speak a string directly
+vocalize speak "Hello, this is a test."
+
+# Speak a markdown file — tables and formatting get flattened first
+vocalize speak-file report.md
+
+# Pipe anything in
+cat notes.md | vocalize speak-file -
+
+# List available voices and grab an ID
+vocalize voices
+
+# Use a specific voice/model, save without playing
+vocalize speak-file report.md --voice <voice-id> --model eleven_flash_v2_5 \
+  --output out.mp3 --no-play
+
+# Cap how much gets sent (handy for free-tier character budgets)
+vocalize speak-file long-report.md --max-chars 2000
+
+# Skip the markdown flattening entirely
+vocalize speak "raw **markdown** stays raw" --raw
+```
+
+Every synthesis result is cached on disk under `~/.cache/vocalize/`, keyed
+by a hash of (text, voice, model, format) — re-running the same command
+twice doesn't burn API quota twice.
+
+## Claude Code integration
+
+The hook scripts ship in the git repository, not the PyPI package — clone
+the repo to install the hook (it shells out to the `vocalize` command, so a
+pipx-installed CLI plus a cloned repo works fine together).
+
+`hooks/claude_stop_hook.py` is a [Claude Code Stop
+hook](https://docs.claude.com/en/docs/claude-code/hooks): a script Claude
+Code runs every time it finishes a response. This one reads the transcript,
+pulls out Claude's last message, and pipes it through the same `vocalize`
+CLI — so it works identically whether Claude Code is running in a bare
+terminal or inside an IDE's integrated terminal (VS Code, Cursor, etc.),
+since both use the same `~/.claude/settings.json` hook config.
+
+**On-demand mode.** If you'd rather trigger speech yourself than have every
+response spoken, skip the install and run the script with `--latest`. It
+finds your most recent Claude Code response — in any session — and speaks
+that one:
+
+```bash
+python3 hooks/claude_stop_hook.py --latest
+```
+
+Combine it with `VOCALIZE_MAX_CHARS` to control how much gets read.
+
+To install it as an automatic hook instead:
+
+```bash
+python3 hooks/install_hook.py
+```
+
+This merges a `Stop` hook entry into `~/.claude/settings.json` (backing up
+the existing file first) rather than overwriting your other hooks. Every
+Claude Code response after that gets spoken aloud automatically. Uninstall
+by removing the `vocalize` entry from the `Stop` array in that file.
+
+By default the hook truncates each response to 500 characters before
+speaking it (`DEFAULT_MAX_CHARS` in `claude_stop_hook.py`) — a Stop hook
+fires after every turn, so a long response would burn through the
+ElevenLabs free-tier quota fast. Override with `VOCALIZE_MAX_CHARS` in the
+environment.
+
+The hook looks up the `vocalize` binary on `PATH`, but Claude Code hooks
+run in Claude Code's own environment, not your interactive shell — if
+`vocalize` was installed into a virtualenv that isn't on that `PATH`, set
+`VOCALIZE_BIN` to the full path (e.g. `/path/to/.venv/bin/vocalize`) to
+point the hook at it directly.
+
+## How it's built
+
+Four decisions shaped the design:
+
+- **The markdown flattener is a pure function.** The hardest logic in the
+  project — deciding what a table, list, or code block should *sound* like —
+  takes a string and returns a string. No I/O, no client, no key. That's why
+  it has the deepest test coverage in the repo, including the edge cases
+  that bit during review: prose containing a stray `|`, single-dash GFM
+  separators, ragged rows, duplicate column names.
+- **One code path for humans and hooks.** The Claude Code hook doesn't
+  reimplement synthesis; it shells out to the same `vocalize` CLI you'd
+  type by hand (with an `--` argv guard so a response starting with a
+  bullet isn't parsed as a flag). Anything the hook can do, you can
+  reproduce and debug from your own terminal.
+- **The hook may fail; the session may not.** Every failure path in the
+  Stop hook logs one line to stderr and exits 0. A dead API key or a hung
+  request costs you the audio, never the coding session.
+- **The cache is an optimization, never a failure source.** Synthesis
+  results are content-addressed on disk; an unreadable or unwritable cache
+  degrades to a fresh API call instead of an error.
+
+## Architecture
+
+```
+vocalize/
+  __init__.py     # package version
+  __main__.py     # python -m vocalize entry point
+  preprocess.py   # markdown -> speakable text (pure function, fully unit tested)
+  config.py       # API key resolution: --api-key > $ELEVENLABS_API_KEY > .env
+  exceptions.py   # VocalizeError / TTSRequestError
+  tts.py          # ElevenLabs API wrapper + disk cache (client is injected, so
+                   # it's mockable in tests without hitting the network)
+  audio.py        # save to disk + play via the OS's native player
+                   # (afplay / mpg123 / ffplay / PowerShell, whichever exists)
+  cli.py          # click-based CLI wiring the above together
+hooks/
+  claude_stop_hook.py  # Claude Code Stop hook -> calls the vocalize CLI
+  install_hook.py      # safely merges the hook into ~/.claude/settings.json
+tests/                  # pytest, all mocked — no API key needed to run these
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+All tests run offline: the ElevenLabs client is dependency-injected into
+`tts.py`, so tests pass in a fake client instead of hitting the real API.
+
+## Known limitations
+
+- **Charts and images aren't described.** Flattening markdown tables is a
+  text problem; a rendered chart is an image, and describing it well needs
+  a vision model in the loop, not a text transform. Out of scope for this
+  project, but a natural next step — pipe the image through a
+  vision-capable model first, feed its description into `vocalize` in
+  place of the chart.
+- **Free tier is 10,000 characters/month** — plenty for reading a handful
+  of documents aloud, not for continuous use. `--max-chars` and the disk
+  cache both help stretch it.
+- Table flattening handles standard GFM pipe tables; it doesn't attempt to
+  handle merged cells or nested tables (rare enough in practice that it
+  wasn't worth the complexity).
+- **Windows playback is untested.** The PowerShell `SoundPlayer` fallback
+  only plays WAV, so the mp3 files this tool generates likely won't play
+  there. Use `--no-play` and open the saved file with whatever's on hand.
+- **The disk cache under `~/.cache/vocalize` grows unbounded.** It's
+  content-addressed (keyed by a hash of text, voice, model, and format),
+  so it's always safe to delete some or all of it — nothing will break,
+  you'll just re-pay for a re-synthesized clip.
+- **`--api-key` on the command line is visible to other local processes**
+  (anything that can run `ps`). Prefer the `ELEVENLABS_API_KEY` environment
+  variable or a `.env` file instead.
+- `vocalize voices` lists only the first page of results from the
+  ElevenLabs API.
+
+## License
+
+MIT

vocalize_cli-0.1.1/README.md

@@ -0,0 +1,217 @@
+# vocalize
+
+[![CI](https://github.com/matthager12-collab/vocalize/actions/workflows/ci.yml/badge.svg)](https://github.com/matthager12-collab/vocalize/actions/workflows/ci.yml)
+
+A command-line tool that turns text, markdown files, or piped stdin into
+natural-sounding speech using the [ElevenLabs](https://elevenlabs.io) API —
+plus a hook that wires it directly into [Claude Code](https://claude.com/claude-code),
+so Claude's responses get read aloud automatically in your terminal or IDE.
+
+## Why this exists
+
+Text-to-speech readers are good at *voices* and bad at *structure*. Point one
+at a markdown report and it reads a table cell-by-cell, left to right, with
+no sense of which row or column you're in — "Q1. 4.2 million. Q2. 5.1
+million" instead of "for Q1, revenue is 4.2 million." Headings, bullet
+lists, and inline code fare the same way: read exactly as typed, syntax and
+all.
+
+`vocalize` fixes the part of that problem that's actually fixable without a
+vision model: a preprocessing pass (`vocalize/preprocess.py`) rewrites
+markdown into short, declarative sentences *before* it ever reaches the TTS
+API — tables become "for X, Y is Z" sentences, bullets become "First, ...
+Second, ...", links keep their text and drop the URL, and fenced code blocks
+are replaced with a spoken placeholder instead of being read character by
+character. It's a text transform, so it's fully unit tested without any
+API key or network access (see `tests/test_preprocess.py`).
+
+## Install
+
+```bash
+pipx install vocalize-cli
+```
+
+(or `uvx --from vocalize-cli vocalize` for a one-off run without installing
+anything). The package is published on PyPI as `vocalize-cli`; the command
+it installs is still `vocalize`.
+
+For a from-source or dev install:
+
+```bash
+git clone <this-repo>
+cd vocalize
+pip install -e .
+```
+
+Get a free ElevenLabs API key at
+[elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys)
+(free tier: 10,000 characters/month, API access included, no commercial
+license). Then either:
+
+```bash
+export ELEVENLABS_API_KEY=your-key-here
+```
+
+or copy `.env.example` to `.env` and fill it in (requires the optional
+`python-dotenv` extra: `pip install -e ".[dotenv]"`).
+
+## Usage
+
+```bash
+# Speak a string directly
+vocalize speak "Hello, this is a test."
+
+# Speak a markdown file — tables and formatting get flattened first
+vocalize speak-file report.md
+
+# Pipe anything in
+cat notes.md | vocalize speak-file -
+
+# List available voices and grab an ID
+vocalize voices
+
+# Use a specific voice/model, save without playing
+vocalize speak-file report.md --voice <voice-id> --model eleven_flash_v2_5 \
+  --output out.mp3 --no-play
+
+# Cap how much gets sent (handy for free-tier character budgets)
+vocalize speak-file long-report.md --max-chars 2000
+
+# Skip the markdown flattening entirely
+vocalize speak "raw **markdown** stays raw" --raw
+```
+
+Every synthesis result is cached on disk under `~/.cache/vocalize/`, keyed
+by a hash of (text, voice, model, format) — re-running the same command
+twice doesn't burn API quota twice.
+
+## Claude Code integration
+
+The hook scripts ship in the git repository, not the PyPI package — clone
+the repo to install the hook (it shells out to the `vocalize` command, so a
+pipx-installed CLI plus a cloned repo works fine together).
+
+`hooks/claude_stop_hook.py` is a [Claude Code Stop
+hook](https://docs.claude.com/en/docs/claude-code/hooks): a script Claude
+Code runs every time it finishes a response. This one reads the transcript,
+pulls out Claude's last message, and pipes it through the same `vocalize`
+CLI — so it works identically whether Claude Code is running in a bare
+terminal or inside an IDE's integrated terminal (VS Code, Cursor, etc.),
+since both use the same `~/.claude/settings.json` hook config.
+
+**On-demand mode.** If you'd rather trigger speech yourself than have every
+response spoken, skip the install and run the script with `--latest`. It
+finds your most recent Claude Code response — in any session — and speaks
+that one:
+
+```bash
+python3 hooks/claude_stop_hook.py --latest
+```
+
+Combine it with `VOCALIZE_MAX_CHARS` to control how much gets read.
+
+To install it as an automatic hook instead:
+
+```bash
+python3 hooks/install_hook.py
+```
+
+This merges a `Stop` hook entry into `~/.claude/settings.json` (backing up
+the existing file first) rather than overwriting your other hooks. Every
+Claude Code response after that gets spoken aloud automatically. Uninstall
+by removing the `vocalize` entry from the `Stop` array in that file.
+
+By default the hook truncates each response to 500 characters before
+speaking it (`DEFAULT_MAX_CHARS` in `claude_stop_hook.py`) — a Stop hook
+fires after every turn, so a long response would burn through the
+ElevenLabs free-tier quota fast. Override with `VOCALIZE_MAX_CHARS` in the
+environment.
+
+The hook looks up the `vocalize` binary on `PATH`, but Claude Code hooks
+run in Claude Code's own environment, not your interactive shell — if
+`vocalize` was installed into a virtualenv that isn't on that `PATH`, set
+`VOCALIZE_BIN` to the full path (e.g. `/path/to/.venv/bin/vocalize`) to
+point the hook at it directly.
+
+## How it's built
+
+Four decisions shaped the design:
+
+- **The markdown flattener is a pure function.** The hardest logic in the
+  project — deciding what a table, list, or code block should *sound* like —
+  takes a string and returns a string. No I/O, no client, no key. That's why
+  it has the deepest test coverage in the repo, including the edge cases
+  that bit during review: prose containing a stray `|`, single-dash GFM
+  separators, ragged rows, duplicate column names.
+- **One code path for humans and hooks.** The Claude Code hook doesn't
+  reimplement synthesis; it shells out to the same `vocalize` CLI you'd
+  type by hand (with an `--` argv guard so a response starting with a
+  bullet isn't parsed as a flag). Anything the hook can do, you can
+  reproduce and debug from your own terminal.
+- **The hook may fail; the session may not.** Every failure path in the
+  Stop hook logs one line to stderr and exits 0. A dead API key or a hung
+  request costs you the audio, never the coding session.
+- **The cache is an optimization, never a failure source.** Synthesis
+  results are content-addressed on disk; an unreadable or unwritable cache
+  degrades to a fresh API call instead of an error.
+
+## Architecture
+
+```
+vocalize/
+  __init__.py     # package version
+  __main__.py     # python -m vocalize entry point
+  preprocess.py   # markdown -> speakable text (pure function, fully unit tested)
+  config.py       # API key resolution: --api-key > $ELEVENLABS_API_KEY > .env
+  exceptions.py   # VocalizeError / TTSRequestError
+  tts.py          # ElevenLabs API wrapper + disk cache (client is injected, so
+                   # it's mockable in tests without hitting the network)
+  audio.py        # save to disk + play via the OS's native player
+                   # (afplay / mpg123 / ffplay / PowerShell, whichever exists)
+  cli.py          # click-based CLI wiring the above together
+hooks/
+  claude_stop_hook.py  # Claude Code Stop hook -> calls the vocalize CLI
+  install_hook.py      # safely merges the hook into ~/.claude/settings.json
+tests/                  # pytest, all mocked — no API key needed to run these
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+All tests run offline: the ElevenLabs client is dependency-injected into
+`tts.py`, so tests pass in a fake client instead of hitting the real API.
+
+## Known limitations
+
+- **Charts and images aren't described.** Flattening markdown tables is a
+  text problem; a rendered chart is an image, and describing it well needs
+  a vision model in the loop, not a text transform. Out of scope for this
+  project, but a natural next step — pipe the image through a
+  vision-capable model first, feed its description into `vocalize` in
+  place of the chart.
+- **Free tier is 10,000 characters/month** — plenty for reading a handful
+  of documents aloud, not for continuous use. `--max-chars` and the disk
+  cache both help stretch it.
+- Table flattening handles standard GFM pipe tables; it doesn't attempt to
+  handle merged cells or nested tables (rare enough in practice that it
+  wasn't worth the complexity).
+- **Windows playback is untested.** The PowerShell `SoundPlayer` fallback
+  only plays WAV, so the mp3 files this tool generates likely won't play
+  there. Use `--no-play` and open the saved file with whatever's on hand.
+- **The disk cache under `~/.cache/vocalize` grows unbounded.** It's
+  content-addressed (keyed by a hash of text, voice, model, and format),
+  so it's always safe to delete some or all of it — nothing will break,
+  you'll just re-pay for a re-synthesized clip.
+- **`--api-key` on the command line is visible to other local processes**
+  (anything that can run `ps`). Prefer the `ELEVENLABS_API_KEY` environment
+  variable or a `.env` file instead.
+- `vocalize voices` lists only the first page of results from the
+  ElevenLabs API.
+
+## License
+
+MIT

vocalize_cli-0.1.1/hooks/claude_stop_hook.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Speak Claude's last response aloud via vocalize. Two modes:
+
+1. As a Claude Code `Stop` hook. Claude Code invokes Stop hooks with a JSON
+   payload on stdin that includes `transcript_path` — the path to a JSONL
+   file of the conversation so far — and every response gets spoken.
+2. On demand, with `--latest`. Nothing is read from stdin; the script finds
+   the most recently written transcript under ~/.claude/projects and speaks
+   that response. Run it when you want speech instead of installing the
+   hook and getting it after every turn.
+
+Either way it pulls the most recent assistant text message out of the
+transcript and pipes it through the `vocalize` CLI (the same one used
+directly from the command line), so there's exactly one code path for
+"turn text into speech".
+
+See hooks/install_hook.py to wire this into ~/.claude/settings.json, or
+do it by hand — add to the "Stop" array:
+
+    {
+      "matcher": "",
+      "hooks": [{"type": "command", "command": "python3 /path/to/claude_stop_hook.py"}]
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+# Keep spoken responses short by default — a Stop hook fires after every
+# turn, and a long response would eat the ElevenLabs free-tier quota fast.
+# Override with VOCALIZE_MAX_CHARS in the environment.
+DEFAULT_MAX_CHARS = 500
+
+
+def _extract_last_assistant_text(transcript_path: str) -> str:
+    last_text_parts: list[str] = []
+    try:
+        with open(transcript_path, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+    except OSError:
+        return ""
+
+    for line in reversed(lines):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        if entry.get("type") != "assistant":
+            continue
+
+        message = entry.get("message", {})
+        content = message.get("content", [])
+        if isinstance(content, str):
+            # Older / alternate transcript shapes store the whole message as
+            # a plain string rather than a list of content blocks.
+            if content:
+                last_text_parts.append(content)
+        else:
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "text":
+                    text = block.get("text", "")
+                    if text:
+                        last_text_parts.append(text)
+
+        if last_text_parts:
+            break  # got the most recent assistant turn; stop scanning
+
+    return "\n".join(last_text_parts)
+
+
+def _find_latest_transcript(projects_dir=None) -> str | None:
+    """Most recently modified Claude Code transcript, or None if there are none.
+
+    Claude Code stores one directory per project under ~/.claude/projects,
+    each holding <session-id>.jsonl files, so newest mtime is "the session
+    you were just talking to".
+    """
+    base = Path(projects_dir) if projects_dir else Path.home() / ".claude" / "projects"
+    transcripts = list(base.glob("*/*.jsonl"))
+    if not transcripts:
+        return None
+    return str(max(transcripts, key=lambda p: p.stat().st_mtime))
+
+
+def main() -> int:
+    if "--latest" in sys.argv[1:]:
+        # On-demand mode: no hook payload on stdin, so don't read it at all.
+        transcript_path = _find_latest_transcript()
+    else:
+        try:
+            payload = json.load(sys.stdin)
+        except json.JSONDecodeError:
+            payload = {}
+        transcript_path = payload.get("transcript_path")
+
+    if not transcript_path:
+        return 0  # nothing to do — don't block Claude Code on a hook error
+
+    text = _extract_last_assistant_text(transcript_path)
+    if not text.strip():
+        return 0
+
+    # VOCALIZE_BIN wins over PATH so a venv install still resolves when the
+    # hook runs from Claude Code's environment rather than your own shell.
+    vocalize_bin = os.environ.get("VOCALIZE_BIN") or shutil.which("vocalize")
+    if not vocalize_bin:
+        # Silently no-op rather than breaking the user's session if the
+        # tool isn't installed / not on PATH in this shell.
+        return 0
+
+    max_chars = os.environ.get("VOCALIZE_MAX_CHARS", str(DEFAULT_MAX_CHARS))
+
+    # Options first, then "--", then the text. Click treats any argv token
+    # starting with "-" as an option, so a reply that opens with a bullet
+    # ("- fixed the parser") or an arrow ("-> next") would otherwise make
+    # vocalize exit 2 with "No such option" and speak nothing. The "--"
+    # end-of-options separator makes the text unambiguously an argument.
+    try:
+        result = subprocess.run(
+            [vocalize_bin, "speak", "--max-chars", max_chars, "--play", "--", text],
+            timeout=60,
+            check=False,
+        )
+        if result.returncode != 0:
+            print(f"vocalize hook: vocalize exited {result.returncode}", file=sys.stderr)
+    except Exception as exc:  # noqa: BLE001 — must not crash the Stop hook
+        # A speech failure should never break the coding session, so this
+        # still returns 0 — but it's logged to stderr rather than swallowed
+        # silently, so a broken hook is diagnosable.
+        print(f"vocalize hook: speech failed: {exc}", file=sys.stderr)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())