heard AGENTS.md

Heard — contributor & agent guide

A macOS voice companion that narrates Claude Code / Codex / arbitrary CLI agents. py2app menu-bar bundle + CLI. Apache 2.0. heard.dev · Releases

This file is the guide for contributors and for coding agents opened in this repo (Claude Code auto-reads it via CLAUDE.md). Keep it current when the architecture shifts. For setup, the test gate, and the PR flow, see CONTRIBUTING.md.

---

Process model

One process — the menu-bar app (Heard.app) — runs the daemon as an in-process thread. Hooks installed by Claude Code / Codex are spawned as short-lived python -m heard.hook <agent> subprocesses. They read the hook payload from stdin, send a JSON message over a Unix-domain socket to the daemon, and exit.

CC tool call
  ↓
~/.claude/settings.json hook → python -m heard.hook claude-code
  ↓ stdin: {"hook_event_name": "PreToolUse", ...}
heard.client.send_event() → Unix socket
  ↓
Heard.app (daemon thread) — _handle_event routes by kind:
  ├─ tool_pre / tool_post  → fast-path templates (no LLM)   → speech queue
  ├─ prose / finals        → harness (the brain)            → speech queue
  └─ harness punts (None)  → no-LLM floor (canned/template) → speech queue
  ↓
afplay → history.append (after successful play)

The harness brain is the mandatory narration path for prose and finals. There are exactly three lanes:

1. Brain (harness.narrate) — prose + finals. One narration-brain call with access to the persona, the Agent State scoreboard, and Working Memory.
2. Fast-path templates — tool actions ("Editing auth.py"); never the brain (latency/cost). Cheap, no LLM.
3. No-LLM floor (Daemon._floor_text) — fires only when the brain punts (LLM unreachable: daily cap, outage, no provider). Tools keep their clean template; a final is read as-is if short, else swapped for a bounded lead of the message prefixed with the project. This floor — not any legacy path — is the only fallback. The floor (and the local Kokoro TTS option) is what keeps Heard from going silent, which for an ambient tool reads as "broken."