tts-lite · Claude Code mod

README

claude-mods

Five Claude Code mods that remove the routine I kept doing by hand. Each one comes from an audit of my last 30 Claude Code sessions. A mod is a plugin of function hooks: it runs inside Claude Code and can draw a band above the prompt, a pane, a toast or a status line, and can step into prompts, tool calls and the session's start and end.

Mod	The habit it removes	What you see	Usage cost
`merge-followthrough`	Typing "616 merged" (61 times in 30 sessions), then Claude spending a turn on `git checkout main && git pull` and deleting the branch; `! git pull` by hand at session start	Band of your open PRs with CI ✓ ✗ …; toast when a merge has been pulled; `/prs`	None
`handoff-on-clear`	"give me a prompt to restart", "I've lost your feedback, can you redisplay" after `/clear`	Toast on save; band `↺ Handoff from last session [Load] [Dismiss]`; `/handoff`	One cached fork per `/clear` (option `summarize`, on by default)
`bg-task-band`	"how are we looking", "any updates", "when's the estimated end time?"	Band: `⏳ Wait for cp-22 recap 12m/25m · TASK [drain]`; toast on finish	None
`review-ledger`	"what's left to do from the review?", updating the H/M/L list by hand	Pane of items by severity (`/review`); toast when an item's PR merges	None
`tts-lite`	A Stop hook starting a full `claude -p` per reply to speak a summary, which left 200 stray transcripts	Audio only	Short replies none; longer ones one bare Haiku completion

How each one works

merge-followthrough: polls gh pr list --author @me every 60 s. When a PR it saw open is merged, it checks out the default branch, pull --ff-onlys, deletes the local branch and prunes, as long as the working tree is clean. On your next prompt it tells Claude what it already did, so Claude doesn't redo it. Typing 616 merged runs the same steps at once. At session start it fast-forwards the default branch if you're on it with no changes.

handoff-on-clear: on session.end (a /clear or an exit) it saves the last answer, your recent asks, PR numbers and artifact links mentioned, the branch, and (with summarize) a 200-word handoff from one $.model.fork, which the API serves mostly from the prompt cache. It's kept per directory for three days. It goes to Claude when you press Load, run /handoff, or ask something like "redisplay" or "prompt to restart".

bg-task-band: records background Bash, Monitor and Agent calls as they start, reads each one's output file every 10 s for the last line, and marks it done from the task notification that arrives when it ends. A TaskStop marks it stopped. Finished tasks stay on the band for 90 s.

review-ledger: registers the tool mcp__review-ledger__items, which Claude calls to record findings (H1, M3, L2) and their state: open, in-progress with a PR number, done, or won't do. It's stored per repository root, so it survives /clear and new sessions. Every 5 minutes it checks in-progress PRs and marks an item done when its PR merges. A prompt that says "review" or names an item gets the ledger as context.

tts-lite: on turn.complete it reads replies of 20 words or fewer out as they are, and asks Haiku for one sentence about anything longer. It plays them through Piper and paplay, or espeak. It reads the same CLAUDE_TTS, CLAUDE_TTS_SPEED, CLAUDE_TTS_VOICE and CLAUDE_TTS_MODEL variables as the shell hook it replaces, and stays silent while that hook (tts-speak.sh) is still in ~/.claude/settings.json, so you never hear double.

Install

Requirements: Claude Code 2.1.288 or later (function-hook mods are early access and the API moves between releases), plus git and an authenticated gh for merge-followthrough and review-ledger. tts-lite needs paplay and Piper or espeak.

Load them for every session by listing the folders in CLAUDE_CODE_PLUGIN_DIRS (colon-separated) in the env block of ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_PLUGIN_DIRS": "~/code/claude-mods/merge-followthrough:~/code/claude-mods/handoff-on-clear:~/code/claude-mods/bg-task-band:~/code/claude-mods/review-ledger:~/code/claude-mods/tts-lite"
  }
}

For one session only:

claude --plugin-dir ./merge-followthrough --plugin-dir ./bg-task-band

Or copy them into a session's hot-reload folder:

scripts/sync.sh ~/.claude/dev-mods/<session-id>

Layout

<mod>/
  .claude-plugin/plugin.json   manifest (name, version, options, state contract)
  hooks/hooks.json             { "modules": ["./register.tsx"] }
  hooks/register.tsx           the hooks module
  types/index.d.ts             $.state contract (mods that keep state)
  tests/*.test.ts              claude plugin test
scripts/
  check-mods.sh                validate / test the mods given files touch
  typecheck.sh                 tsc against Claude Code's generated API types
  sync.sh                      copy mods into a load folder

Development

pip install pre-commit && pre-commit install
claude plugin validate <mod>
claude plugin test <mod>
scripts/typecheck.sh            # all mods

The pre-commit hooks run standard hygiene, gitleaks, shellcheck, and for the mods a commit touches: claude plugin validate, a TypeScript check and claude plugin test. The type-check needs the API declarations Claude Code writes into .claude-plugin/types/ when it loads a mod. Those are generated per build, git-ignored, and found automatically in any ~/.claude/dev-mods copy. Without them the type-check is skipped with a note.

See AGENTS.md for the conventions an agent (or a person) should follow when changing a mod.

License

MIT

Source 1 files

hooks/register.tsx 91 lines

1import type { EngineInterface, Register } from 'claude-code'
2
3// Replaces ~/.claude/hooks/tts-speak.sh. That hook started a whole headless
4// `claude -p` session per reply (full system prompt, a transcript file each:
5// 200 of 269 files in ~/.claude/projects). This one speaks short replies as
6// they are, and summarizes longer ones with a single bare Haiku completion.
7//
8// Same knobs as the old hook: CLAUDE_TTS=0 turns it off, CLAUDE_TTS_SPEED,
9// CLAUDE_TTS_VOICE, CLAUDE_TTS_MODEL.
10
11const VERBATIM_WORDS = 20
12const PROMPT =
13  'The text below is a message Claude just sent to the user. In one short spoken sentence ' +
14  '(max 16 words, plain text, no markdown, start with a verb) say what was done or answered.\n\n'
15
16// Piper -> paplay, espeak -> paplay as fallback; text arrives on stdin.
17const SPEAK_SH = `
18voice="$1"; speed="$2"; piper="$HOME/.local/share/piper/piper/piper"
19command -v paplay >/dev/null 2>&1 || exit 0
20wav="$(mktemp --suffix=.wav)"; text="$(cat)"
21if [ -x "$piper" ] && [ -f "$voice" ]; then
22  printf '%s' "$text" | "$piper" --model "$voice" --length_scale "$speed" --output_file "$wav" >/dev/null 2>&1
23elif command -v espeak >/dev/null 2>&1; then
24  espeak -s 170 -w "$wav" "$text" >/dev/null 2>&1
25fi
26[ -s "$wav" ] && paplay "$wav" >/dev/null 2>&1
27rm -f "$wav"
28`
29
30function stripMarkdown(text: string): string {
31  return text
32    .replace(/```[\s\S]*?```/g, ' code block. ')
33    .replace(/`[^`]*`/g, ' ')
34    .replace(/https?:\/\/\S+/g, ' link ')
35    .replace(/[*_#>|]+/g, ' ')
36    .replace(/\s+/g, ' ')
37    .trim()
38}
39
40async function oldHookActive($: EngineInterface): Promise<boolean> {
41  const home = (await $.env.get('HOME')) ?? ''
42  const settings = await $.fs.read(`${home}/.claude/settings.json`).catch(() => '')
43  return typeof settings === 'string' && settings.includes('tts-speak.sh')
44}
45
46async function speak($: EngineInterface, answer: string) {
47  const plain = stripMarkdown(answer)
48  if (plain === '') return
49  let spoken = plain
50
51  if (plain.split(' ').length > VERBATIM_WORDS) {
52    const model = (await $.env.get('CLAUDE_TTS_MODEL')) || 'haiku'
53    const reply = await $.model.complete({ model, prompt: PROMPT + answer.slice(0, 6000), maxTokens: 60, timeoutMs: 15_000 })
54    spoken = reply.isAnswered ? stripMarkdown(reply.text) : `${plain.slice(0, 300)}. That's the gist.`
55  }
56
57  const home = (await $.env.get('HOME')) ?? ''
58  const voice = (await $.env.get('CLAUDE_TTS_VOICE')) || `${home}/.local/share/piper/voices/en_US-amy-medium.onnx`
59  const speed = (await $.env.get('CLAUDE_TTS_SPEED')) || '0.5'
60  const played = await $.process.run(['bash', '-c', SPEAK_SH, 'tts-lite', voice, speed], { stdin: spoken, timeoutMs: 120_000 })
61  if (played.exitCode !== 0) $.ui.toast(`tts-lite: playback failed (${played.stderr.trim().slice(0, 120) || played.exitCode})`)
62}
63
64const IDLE = 'tts-lite idle: remove the tts-speak.sh Stop hook from ~/.claude/settings.json to switch over'
65
66// Checked on every reply, so removing the old hook takes effect without a reload.
67async function syncIdle($: EngineInterface): Promise<boolean> {
68  const isIdle = await oldHookActive($)
69  $.ui.status(isIdle ? IDLE : undefined)
70  return isIdle
71}
72
73export const register: Register = on => {
74  on('session.start', async ($, e, next) => {
75    await syncIdle($)
76    return next(e)
77  })
78
79  on('turn.complete', async ($, e, next) => {
80    const done = await next(e)
81    const isMain = e.agentId === undefined
82    if (!isMain || e.isAborted || !('answer' in e)) return done
83    if ((await $.env.get('CLAUDE_TTS')) === '0' || (await syncIdle($))) return done
84
85    const answer = e.answer
86    // Off the turn's dispatch, so the prompt comes back at once.
87    $.clock.after(0, () => void speak($, answer).catch(err => $.ui.toast(`tts-lite: ${String(err).slice(0, 120)}`)))
88    return done
89  })
90}
91