Heard CLI
Local voice layer for Claude Code and Codex on macOS: when the agent finishes or fails, it says in a sentence or two what happened
- 218 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Writes hooks into Claude Code and Codex settings, so it sees the events of every tool call
- Summary text goes to ElevenLabs or Speechify when their keys are set, and to Anthropic on a claude -p call
- Product analytics are on by default; narration text and source code are kept out of them
Install
- Works in
Manual install
git clone https://github.com/heardlabs/heard.git && cd heard && python3 -m venv .venv && source .venv/bin/activate && pip install -e .Build from source on macOS. The closed Heard app is a separate download from heard.dev.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Writes hooks into Claude Code and Codex settings, so it sees the events of every tool call
- Summary text goes to ElevenLabs or Speechify when their keys are set, and to Anthropic on a claude -p call
- Product analytics are on by default; narration text and source code are kept out of them
This is third-party code. Review the repository files before installing.
What it does
Heard installs from source as a Python package and narrates an AI agent's work on macOS. heard install claude-code adds Stop, PreToolUse, PostToolUse and UserPromptSubmit hooks to ~/.claude/settings.json, and heard install codex does the same for the Codex CLI in ~/.codex/hooks.json. Heard also follows Codex desktop app sessions. The hooks return immediately, so the agent never waits for speech to end. Heard does not read a reply back in full. It picks what to say from context: what just ran, whether a decision is yours to make, what you have already heard. Co-pilot mode gives short signposts for screen-on work, Companion gives fuller briefings when your hands are busy, and Focus stays quiet until a question, a failure or a blocker. With several sessions, the most important one gets the voice, the rest are summarized, and a change of speaker starts with the session name. Speech comes from Kokoro on the Mac itself after a one-time model download with heard download-voice, about 350 MB. An ElevenLabs or Speechify key can replace it, and an Anthropic key adds connected summaries: without one, phrases are built from templates and the agent's own text. Four personas set the manner of speech: aria, friday, jarvis and atlas, and a Markdown file in ~/Library/Application Support/heard/personas/ adds your own. heard run attaches narration to any other CLI.
Who it is for. Developers on macOS who start long Claude Code or Codex tasks and step away from the screen while the agent works.
Good fit when
- Your agent is refactoring and you stepped away: the voice says the tests pass and asks a question about the migration
- Several Claude Code and Codex sessions run in parallel and you need to know which one waits for you
- You want narration without an account or keys: Kokoro runs on the Mac itself
- A beep is not enough and you want to hear what exactly the agent did
- Each project needs its own voice: the multi_agent_auto_voices setting in config.yaml hands out ElevenLabs voices
Not a fit when
- You work on Linux or Windows: the engine targets macOS
- You need voice input: push to talk, dictation and spoken replies live in the closed Heard app on the Power plan, while the engine in the repository only speaks
- Your agents run in the cloud, for example Devin or Manus: their connectors ship with the app
- A banner or a stock sound is enough: a separate notification hook is simpler for that
Example request
Install Heard from the repository, download the local Kokoro voice and connect narration to Claude Code so I hear the outcome of every taskLimitations
- Works on macOS only. The repository holds the Apache 2.0 open-source engine, while the downloadable Heard 2.0 app is a closed build with cloud voices and the paid Power plan.
- The Kokoro voice needs a one-time model download of about 350 MB.
- The engine speaks but does not listen. Voice input, the Parrot assistant and cloud-agent connectors ship only in the app.
- If the claude command is installed, the engine may send agent activity to Anthropic through claude -p with your login. Product analytics are on by default and switch off with product_analytics: false.
How to disable. The hooks live in ~/.claude/settings.json and ~/.codex/hooks.json. Remove the heard entries there and the agents stop calling the Heard daemon. Shift, Option and period pause narration on the fly, Shift, Option and comma resume it. The clone folder and the virtual environment can be deleted by hand.
FAQ
How is Heard different from a sound or a say-command hook?
A beep tells you something happened, Heard tells you what. For example: "Tests pass, I have one question about the migration." With several sessions, routine steps are batched into short summaries, and questions and failures come first.
How do I get spoken notifications from Codex?
Run heard install codex. Heard writes hooks into ~/.codex/hooks.json and follows Codex desktop app sessions. The same engine serves Claude Code, so one voice covers both agents.
Does the agent's output leave my machine?
That depends on settings. Kokoro synthesizes speech locally. ElevenLabs and Speechify receive the spoken text over HTTPS. For summaries the engine uses your Anthropic key or templates, and with the claude command installed it may call claude -p. Narration text and source code are kept out of analytics.
Will narration slow the agent down?
No. Hooks hand the event to the daemon and return immediately, while speech is synthesized and played separately.
What does narration through ElevenLabs cost?
The free tier covers light daily use. A heavy day of pair programming on the Starter plan costs, by the author's estimate, from a few cents to a few dimes. Kokoro is free and sets a hard ceiling on spending.
Discussion
No questions or reviews yet.
Related
CLI toolsHook-driven sounds for coding agents: starts, failures, completions and even individual Bash commands each get their own cue
A realtime voice layer on top of Claude Code, Codex and OpenCode that keeps talking and listening while background tasks run in parallel
An MCP server for voice conversations with Claude Code and other MCP agents: speech recognition and voice synthesis, local or cloud
Voice control of Claude Code and Codex sessions on your machines: a small agent on each box links it to the pitupitu cloud.
Code-Notify sends a desktop notification when Claude Code, Codex or Gemini CLI finishes a task or waits for your input
Agent Standup shows Claude Code, Codex and Mistral Vibe sessions as a live team call: who works, who waits.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Heard (this card) | no | 218 | ||
| VoiceMode | yes | not required | 1,439 | two-way voice conversation with the agent over MCP, not hook-based narration of its results |
| Code-Notify | no | 291 | a desktop notification when a task ends, without a spoken account of the work |
README in short
The front page asks what a voice layer is and contrasts Heard with the /voice command in Claude Code, which covers input only. It then walks through listening modes, personas, multi-agent narration and a list of what leaves the machine. Paid app features sit in separate blocks, and building from source is covered in the Self-host section.