claude-code-hooks: audio feedback for every Claude Code hook event
claude code hooks - adding voice on each hook
At a glance
- What is it?
- A configuration collection that maps all 30 Claude Code hook events to sound and speech, so you hear what the agent is doing instead of watching the terminal. The judgement: useful as a reference for hook wiring, thin as software, and platform-dependent.
- Who is it for?
- Adopt it if you run Claude Code in a terminal you do not stare at and you want audio cues for session start, tool use and agent responses, and if you are willing to follow the per-platform install notes for Mac, Linux or Windows. Do not adopt it if you need a maintained program with a test suite, or if you work on a machine where a hook error on startup would block your workflow.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 103 days ago.
- What is it written in?
- Mainly HTML, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What the repository is actually made of
The repository is HTML, not a scripting language, and that is the first thing to understand about it. The README is a landing page with embedded SVG assets (a speaking mascot, pill-shaped install buttons, video thumbnails), and the substantive material lives in the .claude/hooks directory and in per-platform install documents: install/README-mac.md, install/README-linux.md and install/README-windows.md. There is no package manifest described, no build step, and no release has been published. You are not installing a library. You are copying hook configuration and audio assets into a Claude Code setup. The value is in the mapping between hook events and sounds, and in the changelog that tracks which Claude Code version introduced each event. The README states the project supports all 30 hooks, and the changelog table is the evidence for that claim, listing each addition with a date and a Claude Code version.
The problem: long agent runs with no signal
Claude Code sessions are asynchronous in practice. You send a prompt, the agent reads files, calls tools, waits on permissions, compacts context, and eventually stops. If you switch to another window while that happens, you have no cheap way to know whether the agent is still working, blocked on a permission prompt, or finished. Polling the terminal is the alternative, and it breaks concentration. This project addresses that by attaching audio to lifecycle events: the README describes a sound on session start, on tool use, on agent response, and more. The repo description puts it more specifically: mouse click on PreToolUse, keyboard on PostToolUse, human voice on other hooks. That is the whole design intent. It is a notification layer built on top of an event system that already exists, aimed at people who run agentic coding sessions in a terminal and want peripheral awareness of them.
How the hook wiring works
Claude Code exposes lifecycle events that fire at defined points, and each event can run a command. The project's mechanism is to bind a sound or a speech invocation to each of those events. The README's own framing of the split is worth quoting because it defines the audio vocabulary: mouse click on PreToolUse, keyboard on PostToolUse, human voice on other hooks. So tool invocations get short mechanical sounds, and the broader lifecycle events (session start, agent stop, notifications, and the rest) get spoken audio. The changelog shows how the event surface grew over time: it started with four events on v1.0.38 (PreToolUse, PostToolUse, Stop, SessionEnd) and now lists 30, including narrower ones such as PermissionRequest, PreCompact, PostCompact, SubagentStart, WorktreeCreate and TaskCreated. Because each event maps to a distinct sound, the audio becomes a coarse state readout: you can distinguish a permission prompt from a completed task without looking. The repository also maintains a HOOKS-README.md with a section titled Not in Official Docs, which implies the author has found event behaviour that Anthropic's own documentation does not describe. That section is the most interesting part of the repo and the README does not summarise its contents.
Getting it running on Mac, Linux or Windows
Installation is deliberately split by platform, and the README links three separate documents rather than giving one set of commands. The usage instructions themselves are minimal. Step 1 is to start Claude Code with the claude command. Step 2 is to send a prompt, with Hi given as the example, after which the documentation says you will hear a sound on session start, tool use, agent response, and more. The prerequisites are not spelled out in the README body; the README instead warns that if you do not follow them, Claude Code will print SessionStart:startup hook error on start. That error string is the diagnostic to watch for. Because the audio layer is platform-specific (speech synthesis and sound playback differ across macOS, Linux and Windows), the per-platform documents are where the real setup lives, and the README does not reproduce their contents. Treat those three files as required reading before you touch your Claude Code configuration, and expect the Windows path to be the least uniform of the three.
Where this breaks down
The most concrete limitation is version coupling. Each hook event in the changelog is tied to a specific Claude Code release, from v1.0.38 through v2.1.152. If your installed Claude Code predates an event the configuration references, the hook will not fire, and the README's stated failure mode is an error message at startup rather than a graceful degradation. That means upgrading Claude Code can be a prerequisite for the configuration working at all, and it also means the configuration can lag behind new events. The second limitation is that this is configuration, not software. There is no test suite described, no CI, no versioned release, and the primary language is HTML. If a sound stops playing after a Claude Code update, you are debugging your own machine, not filing a reproducible bug. Third, audio feedback is a poor fit in shared offices, on calls, or on machines where you have muted output; the entire value proposition disappears in those settings. Finally, the README's Common Errors section covers exactly one error, which suggests the author has not catalogued the failure modes users will hit on unusual shell or audio configurations.
Alternatives and the real difference in approach
The obvious alternative is a single notification hook that fires only on Stop or Notification and sends a desktop notification, a terminal bell, or a message to a chat service. That approach is one hook and one command, and it answers only the question of whether the agent has finished. This project answers a finer-grained question: which phase the agent is in right now. The cost of that granularity is 30 hook bindings to install and maintain, plus audio assets, plus three platform documents. There is a middle path the repository itself points at: its own changelog and HOOKS-README.md function as a reference for hook event names and versions, so you can take the event list and wire it to your own notification mechanism instead of the bundled sounds. The author also maintains sibling repositories, codex-cli-hooks and gemini-cli-hooks, linked from the README, which suggests the pattern is portable across agent CLIs rather than specific to Claude Code. If you already have a notification pipeline, the event mapping table is the part worth borrowing.
Maintenance cost and licence
The changelog is the maintenance story. The README describes it as tracking new hook additions only, with entries dated from Jun 30, 2025 through Jun 04, 2026, and the most recent entries (MessageDisplay, PostToolBatch, UserPromptExpansion) are dated the same day. That cadence tells you the author is tracking Anthropic's releases closely, but it also tells you the maintenance burden is real: every new Claude Code hook event is a potential update here. If you adopt this, you are accepting a dependency on someone else's update schedule for a configuration that sits between you and your agent's startup path. The licence is MIT, which permits use, modification and redistribution with the licence and copyright notice retained. That is permissive enough for internal or commercial use, but the repository is configuration and assets rather than a distributed binary, so the practical question is not licence compatibility but whether you want to vendor the hook files into your own dotfiles. No legal advice is offered here; read the LICENSE file if you plan to redistribute the audio assets.
Editorial conclusion
Adopt it if you run Claude Code in a terminal you do not stare at and you want audio cues for session start, tool use and agent responses, and if you are willing to follow the per-platform install notes for Mac, Linux or Windows. Do not adopt it if you need a maintained program with a test suite, or if you work on a machine where a hook error on startup would block your workflow. Before installing, verify that your Claude Code version exposes the hook events the configuration references, because the README ties each event to a specific Claude Code release and an unsupported event surfaces as a SessionStart:startup hook error rather than a silent skip.
Community notes