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

# Troubleshooting

Start with the simplest checks: confirm Heard is running, narration is not paused, the Mac output is audible, and the intended integration is enabled. Then test with a new agent session.

## Heard is open but says nothing

1. Confirm Heard is not paused.
2. Confirm the Mac output volume is audible and routed to the expected device.
3. Return to Co pilot mode while testing.
4. Confirm the intended agent is enabled.
5. Start a new session and produce a clear question or final result.

Routine tool activity may stay quiet by design.

## Claude Code events are missing

* Confirm the Claude Code integration is enabled in Heard.
* Start a new Claude Code session after enabling it.
* If you use the open source engine, run `heard install claude-code` again and retry with default settings.

## Codex CLI events are missing

* Open Codex CLI and run `/hooks`.
* Confirm the Heard hook is present and trusted.
* Reopen the session after changing hook permissions.
* Test with a new task that produces a clear result.

## Codex app events are missing

* Keep Heard running in the menu bar.
* Confirm Codex is enabled in Heard.
* Confirm both apps run under the same macOS user.
* Send a new message so Heard can observe fresh local activity.

## The browser says signed in, but the app shows signed out

Sign-in finishes in the browser and hands back to the app through a `heard://` link. If an old copy of Heard exists anywhere on your Mac, a previous download, a copy in the Trash, macOS can deliver that link to the wrong copy.

1. Make sure the copy you use lives in `/Applications` and delete other copies, including from the Trash.
2. Quit and reopen Heard from `/Applications`, then sign in again.

Heard 1.1.52 and later reclaims the link automatically on every launch from `/Applications`.

## Heard went quiet during a call or screen recording

That is the courtesy mute: while another app records from the microphone, Heard holds narration and catches you up after. End the call or stop the recording and the held updates play.

## Voice input does not type

Check microphone and Accessibility access in macOS System Settings. Confirm Heard Power is active and Right Command is the configured talk key.

## Narration uses the wrong project name

Add a project label:

```yaml title=".heard.yaml"
label: My project
```

## Get support

If the problem remains, [report an issue on GitHub](https://github.com/heardlabs/heard/issues) or [ask in Discord](https://discord.gg/gdC36fpeDw). Include the integration type, Heard version, macOS version, and the last step that worked.