> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.heard.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.heard.dev/_mcp/server.

# Claude Code

Heard gives Claude Code a voice: it reads progress, questions, failures, and completed work aloud while you do something else. It connects to Claude Code with local hooks. The hooks send meaningful session events to Heard and return immediately, while narration and playback happen asynchronously.

#### Two ways to run Heard

Heard is one engine with two distributions. The **downloadable macOS app** is the official managed build: sign in and it works, with premium voices and managed narration on Pro and the full voice-input suite on Power. The **open source engine** ([github.com/heardlabs/heard](https://github.com/heardlabs/heard), Apache 2.0) is free forever: clone or fork it and run it yourself with a local voice or your own provider keys. Dictation, spoken replies, ambient input, Heard Parrot, and iPhone pairing exist only in the app.

## Managed app setup

#### Open Heard

Keep Heard running in the macOS menu bar and open its integration settings.

#### Enable Claude Code

Turn on the Claude Code integration. Heard installs and manages the local hook.

#### Start a new Claude Code session

Launch Claude Code normally after the integration is enabled.

#### Verify the connection

Ask Claude Code to complete a small task that ends with a clear result. Heard should narrate a useful progress update or the final result.

## Open source setup

After installing the engine, run:

```bash title="Terminal"
heard install claude-code
```

Start Claude Code normally. The Heard daemon starts when the first integrated event arrives.

## What Heard can narrate

* Meaningful progress and tool activity
* Questions, approvals, blockers, and failures
* Test results and completed work
* Several Claude Code sessions with separate context

## If Claude Code stays quiet

1. Confirm Heard is running and not paused.
2. Start a new Claude Code session after enabling the integration.
3. Use a task that produces a question or final response. Routine activity may stay quiet by design.
4. Return to the default listening mode while diagnosing the connection.

Heard is not a screen reader for every tool call. It decides what deserves airtime based on the event and your listening mode.