Skip to navigation
Connect an agent

Wrap any CLI agent so it narrates aloud

Put heard run in front of a command line agent and Heard speaks what it is doing.
View as Markdown

To make any command line agent narrate what it is doing, put heard run in front of the command you normally use. Heard’s open source engine (github.com/heardlabs/heard, Apache 2.0) starts the process, passes its output through, and speaks useful terminal activity aloud.

Terminal
heard run <command> [args...]

For example:

Terminal
heard run your-agent --project ./my-project

Claude Code and Codex do not need the wrapper: they have native adapters (heard install claude-code, heard install codex) with richer event context.

In the managed app

heard run is part of the open source engine, not the Mac app. In the app, connect Cursor, GitHub Copilot CLI, Gemini CLI, Qwen Code, Kimi, OpenCode, Antigravity, Pi or Hermes in Settings → Connections → On this Mac: Heard shows their sessions, and approval requests where the tool supports it, without narrating them. Cloud agents such as Grok Bot and Meta Muse report by voice through the cloud agent connector.

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 managed narration and premium voices, and on Power you press right ⌘ to talk to Heard Parrot. The open source engine (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. It speaks; it does not listen. Parrot and texting Parrot from your iPhone exist only in the app.

What to expect

  • The wrapper can only interpret information the terminal process exposes.
  • Full screen terminal interfaces may not provide enough structured output for reliable narration.
  • Questions or approvals may still require the original agent interface.
  • Native Claude Code and Codex adapters provide richer event context when available.

Verify compatibility

1

Wrap a short task

Start with a familiar command and a low risk task that produces visible terminal output.

2

Listen for a clear result

Confirm Heard speaks a useful summary instead of reading raw lines one by one.

3

Tune the listening mode

The open source engine has three listening modes: Co-pilot for short updates, Companion for fuller narration, or Focus to hear only what needs you. See Listening modes.

Wrapper support varies by workflow. Test your command before relying on it while away from the screen.