🤖 This is an AI-Agent-first project — you don't read this, your agent does

Humans: don't install or configure echook by hand. Point your AI agent — Claude Code, Cursor, or Codex — at this repo and say:

"Install echook from github.com/ChanMeng666/echook and set it up for me."

Your agent reads the docs, runs every command, verifies the result, and reports back. The agent-facing source of truth is AGENTS.md + llms.txt + the live audio-hooks manifest. The only thing a human ever types by hand is one /reload-plugins slash command (Claude Code has no CLI equivalent for it).

All a human needs to know is what echook does — skim Key Features below — so you can ask your agent for it in plain English: "mute audio for an hour", "switch to chimes", "watch my .env file", "put a context-usage bar in my status line". Not sure what's possible? Just ask your agent "what can I configure in echook?"

What's New

Latest: v6.2.0 — complete hook coverage + per-tool-type sounds on Cursor. 13 new lifecycle events (26 → 39 total): Claude Code's Setup / UserPromptExpansion / PostToolBatch / MessageDisplay, plus Cursor's granular per-tool-type events so shell commands, MCP calls, and file reads each get a distinct sound. All new events are opt-in.

Earlier highlights: v6.1.0 pinned the Claude Code startup banner into the status line with auto-reflow · v6.0.0 refocused echook to two tracks (audio/notification + status line) and made every operation a non-interactive CLI command.

📜 Full version history → CHANGELOG.md · GitHub Releases

Key Features

echook does exactly two things, and does them well: (1) tells you what just happened in your AI session when you're not watching the window — a sound at your desk, a spoken summary when you're away, a desktop toast or webhook when you're in another app — and (2) a status line that keeps the facts you need pinned to the bottom of the terminal.

🔔 Audio & out-of-band notifications

Hear (or get pinged) the moment your agent finishes, asks for permission, fails a tool, or hits a rate limit — so you can walk away and trust you'll be called back.

📊 Status Line — startup-banner pin + context monitor

Pins your Claude Code startup banner at the bottom (so it never scrolls away) and adds real-time context-window and quota bars — color-coded warnings before Claude enters the "agent dumb zone". Auto-reflows to fit any terminal width, so nothing is truncated.

🎚️ More

Get Started

This is an AI-first project — you don't follow install steps yourself. You tell your AI agent what to do in plain English, and it runs every command and reports back.

flowchart TB
    REPO["github.com/ChanMeng666/echook<br/>(source + GitHub Releases)"]

    REPO --> CCP["Claude Code<br/>plugin marketplace"]
    REPO --> CURB["Cursor 3.2.16+<br/>auto-bridge (Path A)"]
    REPO --> CURN["Cursor native<br/>install --cursor (Path B)"]
    REPO --> CXP["Codex plugin<br/>marketplace"]
    REPO --> CXN["Codex native<br/>install --codex"]

    CCP --> CLI["audio-hooks CLI<br/>+ JSON + /audio-hooks SKILL<br/>(identical everywhere)"]
    CURB --> CLI
    CURN --> CLI
    CXP --> CLI
    CXN --> CLI

    CLI --> OUT["37 hook events · 30 variants · 2 themes · webhooks<br/>TTS · rate-limit alerts · status line"]

    style REPO fill:#4A90E2,color:#fff
    style CLI fill:#7ED321,color:#000
    style OUT fill:#F5A623,color:#000

Find your editor, paste the prompt into your agent, done:

📖 Full step-by-step install, upgrade, and verification for every path → docs/INSTALLATION_GUIDE.md. Your agent reads this for you.

Talk to It — Natural Language Control

Once installed (Claude Code, Cursor, or Codex — same CLI everywhere), every configuration is one message. You talk; your agent runs the right audio-hooks subcommand and reports back. You don't memorise anything.

sequenceDiagram
    actor You as You
    participant CC as Your AI Agent

    rect rgb(219, 234, 254)
    Note over You,CC: Audio Theme
    You->>CC: Switch audio-hooks to the chime theme.
    CC-->>You: audio-hooks theme set custom — switched to chimes.
    end

    rect rgb(220, 252, 231)
    Note over You,CC: Snooze & Mute
    You->>CC: Snooze audio for 30 minutes.
    CC-->>You: audio-hooks snooze 30m — muted until 3:45 PM.
    You->>CC: Unmute audio.
    CC-->>You: audio-hooks snooze off — audio resumed.
    end

    rect rgb(254, 243, 199)
    Note over You,CC: Hook Selection
    You->>CC: Only fire on stop, notification, and<br/>permission_request — disable everything else.
    CC-->>You: enable-only stop notification permission_request<br/>— 3 hooks active, rest disabled.
    end

    rect rgb(207, 250, 254)
    Note over You,CC: Status Line & Webhooks
    You->>CC: Install the status line, context usage only.
    CC-->>You: statusline installed — visible segments: [context].
    You->>CC: Send alerts to my Slack webhook and test it.
    CC-->>You: Webhook set to slack format. Test delivered.
    end

A few examples — paraphrase freely:

• "Switch to chimes" / "switch to voice"
• "Snooze audio for an hour" / "is audio muted?"
• "Enable rate-limit alerts at 80% and 95%"
• "Speak Claude's actual reply when done"
• "Watch my .env file for changes"
• "Different sound for shell commands vs MCP calls in Cursor"
• "Why isn't audio playing? Diagnose and fix it."

💬 Complete prompt reference (every option, with sequence diagrams) → docs/NATURAL_LANGUAGE_CONTROL.md.

How It Works

flowchart LR
    CC[Editor event<br/>Claude Code / Cursor / Codex] -->|stdin JSON| MR{native matcher<br/>routing}
    MR -->|session_start_resume| HR[hook_runner.py]
    MR -->|stop_failure_rate_limit| HR
    MR -->|notification_idle_prompt| HR
    MR -->|...| HR

    HR -->|reads| RL[rate-limit pre-check<br/>marker debounce]
    HR -->|reads| CFG[user_preferences.json]
    HR -->|reads| MARK[snooze markers]

    HR -->|fires| AUDIO[Audio playback<br/>2 themes]
    HR -->|fires| NOTIF[Desktop notification]
    HR -->|fires| TTS[TTS announcement]
    HR -->|fires| WH[Webhook subprocess<br/>fire-and-forget]
    HR -->|writes| LOG[(NDJSON event log<br/>schema audio-hooks.v1)]

    style CC fill:#4A90E2,color:#fff
    style HR fill:#7ED321,color:#000
    style RL fill:#F5A623,color:#000
    style AUDIO fill:#F5A623,color:#000
    style WH fill:#9013FE,color:#fff
    style LOG fill:#50E3C2,color:#000

Your editor fires hook events as JSON on stdin. Native matchers route each event to hook_runner.py, which checks snooze state, rate-limit thresholds, debounce, and user filters — then fires audio, desktop notifications, TTS, and webhooks as configured.

🏗️ Internals, hook lifecycle, path resolution, and the build pipeline → docs/ARCHITECTURE.md.

Platform Support

Python 3.6+ is the only runtime requirement.

Help, Uninstall & Documentation

Agents start here: read AGENTS.md (mirrored as CLAUDE.md) or llms.txt, then run audio-hooks manifest — the complete, live, truthful state of the project. Everything below is for curious humans.

• Something wrong? Just say "audio-hooks isn't working, diagnose and fix it" — or see docs/TROUBLESHOOTING.md.
• Uninstall? Say "uninstall audio-hooks completely." Details in the Installation Guide.
• Want to contribute? See CONTRIBUTING.md for the canonical-source workflow.

License

This project is licensed under the MIT License — see LICENSE for details. Commercial use, modification, distribution, and private use all allowed.

Author

Chan Meng Creator & Lead Developer

Chan Meng
Need a custom app like this one? I build them — let's talk.