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

# Codex CLI

Codex CLI uses a first class Heard adapter. Heard installs a local hook, and Codex asks you to review and trust that hook before it can send session events.

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

#### Enable Codex in Heard

Open Heard and turn on the Codex integration.

#### Approve the hook

Open Codex CLI, run `/hooks`, and trust the Heard hooks when Codex asks.

#### Start a new session

Reopen the Codex session after changing hook permissions.

#### Verify the connection

Run a small task that returns a clear result. Heard should attribute the spoken update to the correct Codex session.

## Open source setup

```bash title="Terminal"
heard install codex-cli
```

Then open Codex CLI, run `/hooks`, approve the Heard hook, and begin a new session.

## If Codex CLI stays quiet

* Confirm the Heard hook appears in `/hooks` and is trusted.
* Start a new session after approving the hook.
* Confirm Heard is running and narration is not paused.
* Test with one Codex session before adding parallel work.

Codex CLI and the Codex desktop app use different local integration paths. Diagnose them separately.