Getting started

Run one command for your OS (needs git; on Windows, Git for Windows). It installs uv, Python, ONNX models, Cursor / Claude / Codex hooks, the daemon, and enables spoken TTS under ~/aftertone or %USERPROFILE%\aftertone. In Cursor you only turn on Hooks and trust the workspace.

Watch the demo on the homepage hero — short dev question and a longer clone-repo task with Claude Code (/aftertone_on).

• Nothing to pay for Aftertone speech — open source, no subscription
• No API keys — localhost daemon only; no cloud TTS signup
• No Hugging Face token required for default model download (public weights)
• Your coding agent may still need its own plan — separate from Aftertone

curl -fsSL https://raw.githubusercontent.com/omarelkhal/aftertone/main/scripts/install.sh | bash -s -- --install-uv --start-daemon

irm https://raw.githubusercontent.com/omarelkhal/aftertone/main/scripts/install.ps1 | iex

Free to use — nothing to pay for speech

Aftertone is the local TTS layer only. It does not replace your coding agent and does not require its own paid plan.

Your coding agent (Cursor, Claude, etc.) may still need its own subscription — separate from Aftertone.

Then in Cursor

• Enable Hooks in Cursor Settings and trust each workspace where you want TTS.
• Optional: run /aftertone-status in Agent chat.
• Ask the agent something — listen for one short line after the reply.

Then in Claude Code

• Run claude (no --plugin-dir required after global install).
• In chat: /aftertone_on to enable speech for the session.
• Substantive replies need a <spoken_summary> tag at the end — see Claude slash commands.

Then in Codex

• Run codex normally.
• Review or trust the installed ~/.codex/hooks.json entry if Codex prompts for hook trust.
• Enable this session with $aftertone-on, or open /skills and choose aftertone-on.
• The skill sends one reply with a <spoken_summary> tag so the Stop hook registers the session id.

Slash commands

After a global install, use slash commands in Cursor or Claude Code. In Agent chat, type / and pick an aftertone- (Cursor) or aftertone_ (Claude) command. Each runs one python -m aftertone … from your install dir — do not hand-edit speak_summary.toml for everyday changes.

Cursor (hyphens)

Commands live in ~/.cursor/commands/ and work in any trusted workspace.

Command definitions: .cursor/commands/ on GitHub.

Claude Code (underscores)

Global install registers Stop hooks in ~/.claude/settings.json and copies slash commands to ~/.claude/commands/. After install: run claude, then /aftertone_on to enable speech for the session.

Guide on GitHub: docs/adapters/claude.md · command sources claude-plugin/aftertone/commands/

Codex (skills)

Global install registers a Codex Stop hook in ~/.codex/hooks.json, guidance in ~/.codex/AGENTS.md, and user skills in ~/.agents/skills/aftertone-*. Invoke them with $aftertone-on or through /skills. CLI commands remain available as terminal fallbacks.

Guide on GitHub: docs/adapters/codex.md

Aftertone CLI (v2)

From your install root (path in ~/.cursor/hooks/aftertone-install-dir or %USERPROFILE%\.cursor\hooks\aftertone-install-dir):

cd "$(cat ~/.cursor/hooks/aftertone-install-dir)"
uv run --directory py python -m aftertone status
uv run --directory py python -m aftertone on
uv run --directory py python -m aftertone set lang fr
uv run --directory py python -m aftertone set voice F4 --ensure
uv run --directory py python -m aftertone restart
uv run --directory py python -m aftertone doctor
uv run --directory py python -m aftertone repair

set voice restarts the daemon by default. set lang syncs spoken-summary.mdc. Install runs apply-defaults (summary_mode = tag_only, total_step = 8, spoken_summary_max_sentences = 0 for the full tag).

Cursor setup

What runs: afterAgentResponse → speak_summary.sh → speak_summary_prepare.py → POST /say on the daemon. The hook uses inline reply text from the payload (not the transcript file).

Claude setup

Claude Code uses global Stop hooks in ~/.claude/settings.json, slash commands in ~/.claude/commands/, and the shared local daemon. After global install, run claude, then enable speech for that chat with /aftertone_on.

Codex setup

Codex uses the official Codex hooks Stop event. Aftertone reads last_assistant_message from the hook JSON and passes it through the shared local TTS pipeline.

Daemon commands

Prefer /aftertone-restart or uv run --directory py python -m aftertone restart after changing voice, port, ONNX path, or GPU. /aftertone-voice restarts for you.

Recommended: from install root — uv run --directory py python -m aftertone {status|restart} (see Aftertone CLI).

Lower level — run from py/ with --repo-root ..:

cd py
uv run python tts_daemon_ctl.py start --repo-root ..
uv run python tts_daemon_ctl.py status --repo-root ..
uv run python tts_daemon_ctl.py restart --repo-root ..
uv run python tts_daemon_ctl.py stop --repo-root ..

Configuration

Use slash commands for enabled, lang, speed, mode, and voice_type. The file .cursor/hooks/speak_summary.toml is updated by those commands; edit it directly only for advanced keys. Common knobs:

/aftertone-lang updates lang and syncs the Cursor rule automatically. Manual sync from repo root: uv run --directory py python sync_spoken_rule_lang.py

Spoken summaries

Best quality is a flow briefing for vibe coding: what happened, why it matters, optional next move — not a changelog. Put one tag at the very end of substantive replies:

<spoken_summary>
Tests pass and the daemon is restarted!! Your next reply should sound cleaner??
</spoken_summary>

The hook uses the last </spoken_summary> and pairs it with the nearest opening tag before it. Do not leave a bare <spoken_summary> in code or prose above your real tag (that can swallow the wrong text).

Repo default summary_mode = "tag_only" — no speech when the tag is missing (set summary_mode = "auto" in TOML for heuristic fallback). For livelier delivery, end each sentence in the tag with !!, ??, ?!, or !?. Inline <sigh> tags are optional via /aftertone-expression (default off).

Rules for agents: .cursor/rules/spoken-summary.mdc.

Windows hook latency (Cursor, not Aftertone)

If speech feels slow on Windows but the install looks healthy, split the wait into two parts: (1) Cursor calling the hook after the reply, and (2) Aftertone preparing audio once the hook runs. On Linux and macOS, part (1) is usually much smaller; on Windows it often dominates.

What Aftertone does once the hook runs: read the reply text, POST to the local tts_daemon, synthesize, and play. That path is typically a few seconds on CPU, tunable with total_step and voice settings.

What Aftertone cannot fix: how long Cursor waits after the assistant message before it invokes afterAgentResponse.

How to verify on your machine (install dir, e.g. %USERPROFILE%\aftertone):

• .cursor/hooks/state/speak_summary-hook.log — step lines tagged latency
• .cursor/hooks/state/pipeline_trace.jsonl — full trace per reply (phase: hook and phase: sound)
• hook_minus_transcript_mtime_ms — proxy for Cursor delay after the transcript file was last written
• first_sound_since_hook_ms — Aftertone time from hook start to first audio

Run /aftertone-doctor or uv run --directory py python -m aftertone doctor after a slow reply. Updating Cursor may help; comparing the same project on Ubuntu or macOS is the clearest A/B test.

Troubleshooting

Full reference

Every TOML key, language list, and log file paths:

• .cursor/hooks/README.md — hook + daemon reference
• AGENTS.md — short agent-oriented digest
• py/README.md — Python env
• py/aftertone/README.md — v2 package (python -m aftertone)
• README.md — project overview