audio-hooks

# audio-hooks skill

This plugin is the AI control surface for the echook project. The user does NOT operate this project by hand. You operate it on their behalf via the `audio-hooks` binary that this plugin adds to your Bash tool's PATH.

**Golden rule:** when in doubt about the project's current capabilities, run `audio-hooks manifest` first. The manifest is the canonical machine description of every subcommand, every config key, every hook, every audio file, and every error code. It is always up to date with the running version. Treat this SKILL.md as an orientation; treat `audio-hooks manifest` as the source of truth.

## What the user can ask for and what you should run

**Install / set up the project**

The plugin install (which you are using right now) is the recommended path for Claude Code users. If a user is not yet on the plugin, tell them to run `/plugin marketplace add ChanMeng666/echook` and `/plugin install audio-hooks@chanmeng-audio-hooks` inside Claude Code. **Cursor IDE 3.2.16+ users get audio-hooks for free via Cursor's built-in third-party hooks bridge** — no separate Cursor install needed. For users who run Cursor *without* Claude Code, use `audio-hooks install --cursor` (see "Install for Cursor-only users" below). **Codex users** should use the Codex plugin path when available, or `audio-hooks install --codex` as the native hooks.json fallback — Codex does NOT auto-bridge Claude Code plugins (see "Install for Codex users" below). Once installed, verify with:

```bash
audio-hooks status
audio-hooks test all
```

**Snooze / mute / quiet hours**

| User says | Run |
|---|---|
| "snooze audio for 30 minutes" | `audio-hooks snooze 30m` |
| "shut up for an hour" | `audio-hooks snooze 1h` |
| "mute audio for the rest of the day" | `audio-hooks snooze 8h` |
| "unmute" / "resume" / "cancel snooze" | `audio-hooks snooze off` |
| "is audio snoozed?" | `audio-hooks snooze status` |

Duration syntax: `30m`, `1h`, `90s`, `2d`, or a bare integer (interpreted as minutes).

**Upgrade the plugin without losing config**

`audio-hooks upgrade` is the AI-first way to refresh the plugin code (and `~/.claude/plugins/cache/`) without touching the user's preferences. Use it whenever:

| User says | Run |
|---|---|
| "upgrade audio-hooks" / "refresh the cache" / "Cursor still plays old theme" | `audio-hooks upgrade` |
| "is there a new version?" | `audio-hooks upgrade --check-only` |
| "the upgrade got stuck" | `audio-hooks upgrade --force` (only after confirming via `audio-hooks status`) |

`upgrade` auto-detects scope via `claude plugin list --json`, tries `claude plugin update` first (data-preserving), falls back to `uninstall --keep-data + install` if needed. On success, the user's `~/.claude/plugins/data/audio-hooks-chanmeng-audio-hooks/user_preferences.json` is preserved verbatim, then loaded through auto-migration so new keys from the new template are merged in non-destructively.

**Restore from a backup**

| User says | Run |
|---|---|
| "what configurations have I changed?" | `audio-hooks status` (look at the `customizations` field) |
| "show me available backups" | `audio-hooks backup list` |
| "restore my config from before the upgrade" | `audio-hooks backup restore latest-external` |
| "delete old backups" | `audio-hooks backup prune` |

**Enable / disable individual hooks**

Run `audio-hooks hooks list` to see all 26 hooks with their current state. Then:

| User says | Run |
|---|---|
| "stop the audio for tool execution" | `audio-hooks hooks disable pretooluse` and `audio-hooks hooks disable posttooluse` |
| "enable rate-limit warnings" | `audio-hooks set rate_limit_alerts.enabled true` |
| "I only want stop and notification audio" | `audio-hooks hooks enable-only stop notification permission_request` |
| "enable the v5.0 permission_denied hook" | `audio-hooks hooks enable permission_denied` |
| "watch .env files for changes" | `audio-hooks hooks enable file_changed` and `audio-hooks set file_changed.watch '[".env",".envrc"]'` |

**Check project status**

Run `audio-hooks status` when the user asks "what's the current audio config?", "is audio working?", "show me audio status", etc. It returns a full snapshot: version, theme, enabled hooks count, snooze state, focus flow, webhook, TTS, rate-limit alerts, and install mode.

```bash
audio-hooks status                     # full state snapshot
audio-hooks version                    # version + install type detection
```

**Change audio theme**

The project ships two themes. `default` is voice recordings, `custom` is non-voice chimes.

```bash
audio-hooks theme list                  # show available + current
audio-hooks theme set custom            # switch to chimes
audio-hooks theme set default           # switch to voice
```

**Webhook fan-out (Slack / Discord / Teams / ntfy / raw)**

```bash
audio-hooks webhook                     # view current webhook config
audio-hooks webhook set --url https://ntfy.sh/my-claude-channel --format ntfy
audio-hooks webhook set --url https://hooks.slack.com/services/... --format slack
audio-hooks webhook test                # POST a test payload
audio-hooks webhook clear               # disable
```

Supported formats: `slack`, `discord`, `teams`, `ntfy`, `raw`. The raw format ships the `audio-hooks.webhook.v1` schema. Every event includes `session_id`, `session_name`, `worktree`, `agent`, `rate_limits`, `last_assistant_message`, `notification_type`, `error_type`, `source`, `trigger`, `load_reason`, and `permission_suggestions` at the top level.

**Text-to-speech**

```bash
audio-hooks tts set --enabled true
# v5.0: TTS Claude's actual final reply on stop/subagent_stop
audio-hooks tts set --speak-assistant-message true
audio-hooks tts set --assistant-message-max-chars 200
```

**Rate-limit alerts (v5.0)**

The runner inspects every hook's stdin for `rate_limits.{five_hour,seven_day}` and plays a one-shot warning when crossing thresholds. Default thresholds are `[80, 95]`. Each (window, threshold