Vocalize

vocalize

[](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.

Quickstart

pipx install vocalize-cli

vocalize config

Walks you through your API key, a voice, and a speed, and saves it all.

vocalize speak "hello"

To set up just the key, skip the wizard and run `vocalize auth login` — it stores the key in your OS keychain.

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

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 `voca