Heard documentation

The shortest path is the managed macOS app. Download Heard, complete setup, connect one agent, and run a small task that produces a clear question or result.

Install the managed app

Download Heard

Download the latest Heard app, move it into Applications if needed, and open it. The shipped app requires macOS 14 or later.

Complete setup

Sign in in your browser, approve the macOS permissions Heard asks for, and follow the short setup tour. It downloads the on-device speech model and has you try holding right ⌘ once. With Heard Power, you also meet Heard Parrot.

Connect one coding agent

Turn on Claude Code or Codex in Heard Settings under Connections. Start with one integration so the first spoken event is easy to identify.

Run a small task

Keep Heard in the menu bar and use your agent normally. A question, blocker, failure, or completed task should produce a useful spoken update. Heard starts in Co-pilot; see Listening modes to change how much it says.

Try your voice (Power)

Hold right ⌘ with your cursor in a text field, speak, and release. Heard types what you said.
Hold right ⌘ and start with “Claude” to message your Claude Code session.
Say “Hey Parrot, what does this project do?” to ask about your code.

Ask your coding agent to install Heard

Paste this prompt into Claude Code, Codex, or another coding tool:

Installation prompt

Install Heard so you can narrate your work to me out loud. Run: curl -L https://heard.dev/download/cc -o /tmp/heard.zip && unzip -o /tmp/heard.zip -d /Applications && xattr -dr com.apple.quarantine /Applications/Heard.app && open /Applications/Heard.app, then hand it back to me. A setup window opens and I will take it from there.

Build the open source engine

Use this path when you want full control, local speech, or your own provider keys.

Terminal

git clone https://github.com/heardlabs/heard.git
cd heard
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Provider keys are optional. Without them, the engine can use local Kokoro speech and neutral local templates.

Optional provider configuration

heard config set elevenlabs_api_key <your-key>
heard config set speechify_api_key <your-key>
heard config set anthropic_api_key <your-key>

Install the adapter you need:

Choose one integration

heard install claude-code
heard install codex        # Codex CLI and the Codex desktop app

Narration runs asynchronously. Your coding agent should not wait for Heard to finish speaking.

Next steps

Claude Code

Install and verify the native Claude Code adapter.

Codex CLI

Install the Codex hook and approve it in Codex.

Codex app

Follow local Codex desktop activity.

Privacy and data

Choose local and hosted processing deliberately.