echook

# echook

> echook is an **AI-agent-first** audio + status-line notification system for Claude Code, Cursor IDE, and Codex CLI. An AI agent (Claude Code / Cursor / Codex) clones, installs, configures, tests, and uninstalls the whole project on the user's behalf — there are no human-interactive menus, no `curl | bash` flows, and nothing to hand-edit. Every capability is a non-interactive `audio-hooks` subcommand that takes and returns JSON.

If you are an AI agent operating this project, do this first:

- Run `audio-hooks manifest` — it returns the live, authoritative list of every subcommand, hook, config key, error code, env var, `editor_targets`, `supported_editors`, and `pointers`. Everything below is orientation; the manifest is source-of-truth.
- Never hand-edit `config/user_preferences.json`. Use `audio-hooks set <dotted.key> <value>` (validated, JSON result).
- Verify any change with `audio-hooks status`, `audio-hooks diagnose`, and `audio-hooks test all`.

## Operating the project (AI agent)

- [AI Operator Guide](AGENTS.md): the critical rules — CLI-only interface, manifest-first, two-track scope guard, AI-agent-first (no interactive paths), build-sync after editing canonical sources.
- [Natural-language → CLI mapping](plugins/audio-hooks/skills/audio-hooks/SKILL.md): the decision tree mapping user requests ("mute claude", "switch theme", "monitor context") to exact `audio-hooks` commands.

## Install (the agent runs these; the human types `/reload-plugins` on Claude Code and restarts the editor once on the Cursor/Codex paths)

- Claude Code (canonical): `claude plugin marketplace add ChanMeng666/echook` then `claude plugin install audio-hooks@chanmeng-audio-hooks`, then ask the user to type `/reload-plugins` (REPL-only).
- Cursor (without Claude Code): `audio-hooks install --cursor`.
- Codex (native): `audio-hooks install --codex`.
- Cloned-repo / non-plugin path: `bash scripts/install-complete.sh` — always non-interactive.
- [Installation Guide](docs/INSTALLATION_GUIDE.md) · [Troubleshooting (stable error codes)](docs/TROUBLESHOOTING.md)

## Reference

- [Architecture](docs/ARCHITECTURE.md): runner flow, hook surfaces per editor, error-code model, script inventory.
- [Status Line](docs/STATUS_LINE.md): complete reference for track 2 — Claude Code renders 29 segments (whitelist/blacklist config) plus a separate per-subagent row via `subagentStatusLine` (`statusline subagent`, NDJSON keyed by task id); Codex curates a fixed item list (`statusline codex`), it cannot render custom text. Live truth: `audio-hooks statusline segments`.
- [README](README.md): human-readable overview and platform picker.
- [Event behaviour notes](docs/EVENT_BEHAVIOR_NOTES.md): what Claude Code's hook events actually do, measured against a running install — undocumented `Stop.background_tasks`, the `agent_completed` / `agent_needs_input` matchers that never fired, and how to capture payloads before trusting an event name.
- [Changelog](CHANGELOG.md): version history (v6.5.1 = Windows desktop toasts were dead for any message containing a double quote (POSIX-shell escaping interpolated into a PowerShell string), now a real WinRT toast with a probed, budget-capped backend chain; `play_tts()` had the identical bug and was silent on the same inputs; the toast outcome is logged and `NOTIFICATION_FAILED` is finally emitted instead of returning success unconditionally; config migration had not run on any install since 5.1.5 because the template version stamp was never bumped, now gated structurally and owned by `bump-version.sh`; six new `diagnose` codes (`NO_COMPLETION_SIGNAL`, `NOTIFICATION_FAILED`, `PREFS_SCHEMA_STALE`, `STALE_PLUGIN_CACHE`, `WINDOWS_NO_GIT_BASH`, `TERMINAL_SEQUENCE_INERT` — v6.5.0's `terminalSequence` turned out to be inert, since Claude Code emits the escape only from a synchronous hook path and every handler is async); verified against the Claude Code 2.1.251 binary that no hook contract had changed, and recorded that `PreModelSwitch` is a blocking decision hook that must never be registered; v6.5.0 = `subagentStatusLine` (one row per subagent), `worktree_remove` + `directory_added` events, the 8 remaining `Notification` matchers, `filters.<hook>.min_duration_ms`, Codex `SessionEnd` behind a >=0.145.0 version gate, and a unique sound for all 83 event/variant slots in both themes; v6.4.1 = upstream-drift fixes — the `fork` `SessionStart` matcher that had gone silent since Claude Code 2.1.213, five `stop_failure` variant toggles that did nothing, `manifest` overstating Claude Code's event surface, and `uninstall.sh` leaving 19 orphaned registrations; v6.4.0 = per-variant hook toggles (30 matcher variants independently switchable), the 4 missing `Notification` matchers, `skip_if_background_tasks_running` filter, and contract tests for the Claude Code hook template; v6.3.3 = docs: status-line examples show the weekly reset date; v6.3.2 = rate-limit reset clocks show the date when not today (`resets Jul 4 5am`); v6.3.1 = fix status-line truncation on emoji-dense rows; v6.3.0 = Claude Code status line grows to 29 segments + `hidden_segments` + `statusline segments`, and `statusline codex {show,preview,apply}` curates Codex's fixed `[tui].status_line`/`terminal_title`; v6.2.0 = 13 new lifecycle events, including Cursor's per-tool-type events (the canonical count became 37 in v6.3.4, which removed `worktree_create`/`worktree_remove`); v6.1.0 = status line pins the Claude Code startup banner and auto-reflows to avoid truncation).

## Scope (what echook does NOT do)

- echook is two tracks only: audio/notification and the status line. Wellness/breathing, pomodoro/timers, gamification, opening URLs, or running side-commands are out of scope by design — do not add them.