Skip to navigation
Reference

Troubleshooting

Diagnose the connection from the app outward.
View as Markdown

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. Switch to Co-pilot while testing. In Focus, or with How much set to Needs me, only questions, approvals, and failures speak.
  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 Claude Code is connected in Heard Settings under Connections.
  • 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 connected in Heard Settings under Connections.
  • 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 Stay quiet during calls: while another app uses the microphone, Heard holds narration. To narrate over a screen recording, turn the setting off in Settings under Parrot.

Voice input does not type

Open Settings, go to Dictation, and run Check hold-to-speak. It tests the key, your microphone, and the typing, and tells you which part to fix. Also check microphone and Accessibility access in macOS System Settings, and confirm Heard Power is active.

”Hey Parrot” does not answer

  • Confirm Heard Power is active. Parrot and its wake word are part of Power.
  • In Settings under Your voice, check that the wake word is downloaded.
  • In Settings under Your voice, check that push-to-talk works with Check hold-to-speak.

Something is lit on screen

A light along the bottom edge means a Parrot conversation is open; it fades when the conversation ends. The small status card shows agent tool activity and goes away when the agent finishes. See On screen.

Narration uses the wrong project name

Add a project label:

.heard.yaml
label: My project

Get support

If the problem remains, report an issue on GitHub or ask in Discord. Include the integration type, Heard version, macOS version, and the last step that worked.