> 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.

# Quickstart

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](https://heard.dev/download/manual?format=zip), move it into Applications if needed, and open it. The shipped app requires macOS 14 or later.

#### Complete setup

Sign in, approve the requested macOS permissions, choose a voice, and select a listening mode.

#### Connect one coding agent

Enable Claude Code or Codex in Heard. 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.

## Ask your coding agent to install Heard

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

```text title="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.

```bash title="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.

```bash title="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:

```bash title="Choose one integration"
heard install claude-code
heard install codex-cli
heard install codex-app
```

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

## Next steps

#### [Claude Code](/claude-code)

Install and verify the native Claude Code adapter.

#### [Codex CLI](/codex-cli)

Install the Codex hook and approve it in Codex.

#### [Codex app](/codex-app)

Follow local Codex desktop activity.

#### [Privacy and data](/privacy-and-data)

Choose local and hosted processing deliberately.