feat: snooze / temporary mute for audio hooks (v4.4.0)

Add marker-file based snooze system that temporarily silences all audio
hooks for a specified duration with automatic resumption. Closes #7.

- New scripts/snooze.sh standalone CLI (snooze, status, resume)
- is_snoozed() check in hook_runner.py and hook_config.sh
- --snooze/--resume/--snooze-status flags in configure.sh
- Inline snooze commands in quick-configure.sh (curl | bash)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ChanMeng666

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to Claude Code Audio Hooks will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.4.0] - 2026-03-13
+
+### Added
+- **Snooze / Temporary Mute** (closes #7): Temporarily silence all audio hooks for a specified duration with automatic resumption
+  - New `scripts/snooze.sh` standalone CLI: `bash scripts/snooze.sh 1h` to snooze, `status` to check, `off` to resume
+  - Marker-file based design — no daemon or cleanup needed; hooks self-expire
+  - Accepts flexible duration formats: `30m`, `1h`, `2h`, `90m`, bare numbers (minutes), `30s`
+  - `--snooze`, `--resume`, `--snooze-status` flags added to `scripts/configure.sh`
+  - `--snooze`, `--resume`, `--snooze-status` flags added to `scripts/quick-configure.sh` (inline, works via `curl | bash`)
+  - Snooze check integrated into both `hooks/hook_runner.py` (Python) and `hooks/shared/hook_config.sh` (Bash)
+  - Debug logging: snoozed hooks log "SNOOZED" with remaining time
+
+### Changed
+- `hook_runner.py` version bumped to 4.4.0
+
+---
+
 ## [4.3.1] - 2026-02-17
 
 ### Added

CLAUDE.md

@@ -1,6 +1,6 @@
 # Claude Code Audio Hooks - AI Assistant Guide
 
-> **Version:** 4.3.1 | **Last Updated:** 2026-02-17
+> **Version:** 4.4.0 | **Last Updated:** 2026-03-13
 
 This document is designed for AI assistants (Claude Code, Cursor, Copilot, etc.) to understand and help users install this project correctly.
 
@@ -40,6 +40,16 @@ Gives: desktop notifications + system sounds for Stop, Notification, SubagentSto
 
 Gives: custom MP3 audio + desktop notifications + context-aware alerts + TTS (optional).
 
+### Snooze / Temporary Mute
+```bash
+bash scripts/snooze.sh              # Snooze 30m (default)
+bash scripts/snooze.sh 1h           # Snooze 1 hour
+bash scripts/snooze.sh status       # Show remaining time
+bash scripts/snooze.sh off          # Resume immediately
+bash scripts/configure.sh --snooze 1h   # Via configure.sh
+bash scripts/configure.sh --resume      # Cancel snooze
+```
+
 ## Platform Detection Decision Tree
 
 Use this decision tree to determine the correct installation method:
@@ -106,12 +116,13 @@ claude-code-audio-hooks/
 │
 ├── scripts/
 │   ├── quick-setup.sh           # Lite tier installer (zero deps, curl | bash)
-│   ├── quick-configure.sh      # Lite tier hook manager (enable/disable/list)
+│   ├── quick-configure.sh      # Lite tier hook manager (enable/disable/list/snooze)
 │   ├── quick-unsetup.sh         # Lite tier uninstaller
 │   ├── install-complete.sh      # Full installer (all platforms)
 │   ├── install-windows.ps1      # PowerShell installer (Windows)
 │   ├── uninstall.sh             # Uninstaller
 │   ├── configure.sh             # Configuration utility
+│   ├── snooze.sh                # Snooze / temporary mute tool
 │   ├── test-audio.sh            # Audio testing tool
 │   └── diagnose.py              # Diagnostic tool
 │
@@ -400,6 +411,7 @@ Instruct user to:
 
 | Version | Date | Key Changes |
 |---------|------|-------------|
+| 4.4.0 | 2026-03-13 | Snooze / temporary mute: `snooze.sh` CLI, marker-file based, auto-resume; `--snooze`/`--resume` in configure.sh and quick-configure.sh (closes #7) |
 | 4.3.1 | 2026-02-17 | Quick Setup customization: new `quick-configure.sh` for enabling/disabling individual hooks without cloning; fix `quick-unsetup.sh` missing PermissionRequest |
 | 4.3.0 | 2026-02-17 | Per-hook notification mode overrides: independently control audio/desktop notifications per hook type via `notification_settings.per_hook` |
 | 4.2.2 | 2026-02-14 | Robust theme switching: remove conflicting `audio_files` config, add hook_runner.py auto-sync from project dir, configure.sh syncs on theme switch |

README.md

@@ -633,6 +633,9 @@ Already using Claude Code? Just tell it what you want in plain language:
 | **Audio only, no popups** | *"Turn off all desktop notification popups, keep audio only"* |
 | **Popups only, no audio** | *"Switch to desktop notifications only, disable all audio"* |
 | **Audio + popups for critical hooks** | *"Set global mode to audio_only, but enable audio + desktop popup for stop, notification, and permission_request hooks"* |
+| **Snooze for a meeting** | *"Snooze all audio hooks for 1 hour"* |
+| **Check snooze status** | *"Are my audio hooks snoozed right now?"* |
+| **Resume after snooze** | *"Cancel the snooze and resume audio hooks"* |
 | **Silence noisy hooks** | *"Set pretooluse and posttooluse to disabled mode so they don't play audio or show popups"* |
 | **Mixed per-hook setup** | *"I want audio for all hooks, but also desktop popups only for task completion and authorization requests"* |
 
@@ -751,6 +754,38 @@ bash scripts/configure.sh --help
 
 ---
 
+#### **Snooze / Temporary Mute**
+
+Need silence during a meeting or focus session? Snooze all hooks temporarily — they auto-resume when the timer expires.
+
+**Standalone script:**
+```bash
+bash scripts/snooze.sh              # Snooze 30 minutes (default)
+bash scripts/snooze.sh 1h           # Snooze 1 hour
+bash scripts/snooze.sh 2h           # Snooze 2 hours
+bash scripts/snooze.sh 90m          # Snooze 90 minutes
+bash scripts/snooze.sh status       # Check remaining time
+bash scripts/snooze.sh off          # Resume immediately
+```
+
+**Via configure.sh:**
+```bash
+bash scripts/configure.sh --snooze 1h
+bash scripts/configure.sh --snooze-status
+bash scripts/configure.sh --resume
+```
+
+**Via quick-configure.sh (Lite tier, no clone needed):**
+```bash
+curl -sL ...quick-configure.sh | bash -s -- --snooze 1h
+curl -sL ...quick-configure.sh | bash -s -- --snooze-status
+curl -sL ...quick-configure.sh | bash -s -- --resume
+```
+
+**How it works:** A timestamp marker file is written to the temp directory. All hook runners check this file before playing audio. When the timestamp is in the past, hooks automatically resume — no cleanup daemon needed.
+
+---
+
 ### **Manual Configuration**
 
 Edit `config/user_preferences.json`:

hooks/hook_runner.py

@@ -29,7 +29,7 @@
 
 # Version used for auto-sync: when the installed copy in ~/.claude/hooks/
 # detects a newer version in the project directory, it self-updates.
-HOOK_RUNNER_VERSION = "4.3.0"
+HOOK_RUNNER_VERSION = "4.4.0"
 
 # =============================================================================
 # DEBUG LOGGING SYSTEM
@@ -383,6 +383,25 @@ def is_hook_enabled(hook_type: str) -> bool:
     return result
 
 
+def is_snoozed() -> bool:
+    """Check if hooks are temporarily snoozed via marker file."""
+    snooze_file = QUEUE_DIR / "snooze_until"
+    if not snooze_file.exists():
+        return False
+    try:
+        snooze_until = float(snooze_file.read_text(encoding="utf-8").strip())
+        if time.time() < snooze_until:
+            remaining = snooze_until - time.time()
+            log_debug(f"Snoozed: {remaining:.0f}s remaining")
+            return True
+        else:
+            log_debug("Snooze expired")
+            return False
+    except (ValueError, OSError) as e:
+        log_debug(f"Error reading snooze file: {e}")
+        return False
+
+
 CUSTOM_AUDIO_FILES = {
     "notification": "chime-notification-urgent.mp3",
     "stop": "chime-task-complete.mp3",
@@ -1020,6 +1039,11 @@ def run_hook(hook_type: str, stdin_data: dict = None) -> int:
         log_trigger(hook_type, "DISABLED")
         return 0
 
+    # Check if snoozed
+    if is_snoozed():
+        log_trigger(hook_type, "SNOOZED")
+        return 0
+
     # Check debounce
     if should_debounce(hook_type):
         log_trigger(hook_type, "DEBOUNCED")

hooks/shared/hook_config.sh

@@ -216,6 +216,16 @@ EOF
     [ "$enabled" = "true" ]
 }
 
+# Check if hooks are temporarily snoozed via marker file
+is_snoozed() {
+    local snooze_file="$QUEUE_DIR/snooze_until"
+    [ -f "$snooze_file" ] || return 1
+    local snooze_until current_time
+    snooze_until=$(cat "$snooze_file" 2>/dev/null) || return 1
+    current_time=$(date +%s)
+    [ "$current_time" -lt "${snooze_until%%.*}" ] 2>/dev/null
+}
+
 # Get audio file path for a hook type
 get_audio_file() {
     local hook_type="$1"
@@ -549,6 +559,12 @@ get_and_play_audio() {
         exit 0  # Hook disabled, exit silently
     fi
 
+    # Check if snoozed
+    if is_snoozed; then
+        log_debug "Hook $hook_type snoozed, skipping"
+        exit 0
+    fi
+
     # Check debounce (prevent rapid-fire notifications)
     if should_debounce "$hook_type"; then
         exit 0  # Debounced, exit silently
@@ -625,6 +641,7 @@ cleanup_hooks() {
 # =============================================================================
 
 # Export functions for use in hook scripts
+export -f is_snoozed
 export -f is_hook_enabled
 export -f get_audio_file
 export -f play_audio_internal

scripts/configure.sh

@@ -617,6 +617,16 @@ ${CYAN}PROGRAMMATIC MODE${NC} (with arguments):
     Reset to recommended defaults
     (Enables: notification, stop, subagent_stop, permission_request; Disables: all others)
 
+  ${BOLD}--snooze [DURATION]${NC}
+    Temporarily mute all audio hooks (default: 30m)
+    Examples: --snooze 30m, --snooze 1h, --snooze 2h
+
+  ${BOLD}--resume${NC}
+    Cancel snooze early, resume all hooks
+
+  ${BOLD}--snooze-status${NC}
+    Show current snooze status
+
   ${BOLD}--apply${NC}
     Save configuration without prompting
     (Auto-applied after --enable, --disable, --set, --reset)
@@ -927,6 +937,19 @@ process_arguments() {
                 cmd_hook_mode "${hook_modes[@]}"
                 exit 0
                 ;;
+            --snooze)
+                shift
+                bash "$PROJECT_DIR/scripts/snooze.sh" "${1:-30m}"
+                exit 0
+                ;;
+            --resume|--unsnooze)
+                bash "$PROJECT_DIR/scripts/snooze.sh" resume
+                exit 0
+                ;;
+            --snooze-status)
+                bash "$PROJECT_DIR/scripts/snooze.sh" status
+                exit 0
+                ;;
             --reset)
                 cmd_reset
                 exit 0

scripts/quick-configure.sh

@@ -40,6 +40,14 @@ error()   { printf "${RED}[ERROR]${NC} %s\n" "$1"; }
 # All Quick Setup hooks
 ALL_HOOKS=("Stop" "Notification" "SubagentStop" "PermissionRequest")
 
+# Cross-platform temp/queue directory (must match hook_runner.py / hook_config.sh)
+if [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "mingw"* ]] || [[ "$OSTYPE" == "cygwin" ]]; then
+    QUEUE_DIR="${TEMP:-${TMP:-/tmp}}/claude_audio_hooks_queue"
+else
+    QUEUE_DIR="/tmp/claude_audio_hooks_queue"
+fi
+SNOOZE_FILE="$QUEUE_DIR/snooze_until"
+
 # =============================================================================
 # PLATFORM DETECTION (same as quick-setup.sh)
 # =============================================================================
@@ -474,6 +482,9 @@ show_usage() {
     printf "  quick-configure.sh --enable <Hook> [Hook...]       Enable hooks\n"
     printf "  quick-configure.sh --disable <Hook> [Hook...]      Disable hooks\n"
     printf "  quick-configure.sh --only <Hook> [Hook...]         Keep only these hooks\n"
+    printf "  quick-configure.sh --snooze [DURATION]             Temporarily mute all hooks (default: 30m)\n"
+    printf "  quick-configure.sh --resume                        Cancel snooze, resume hooks\n"
+    printf "  quick-configure.sh --snooze-status                 Show snooze status\n"
     printf "  quick-configure.sh --help                          Show this help\n"
     printf "\n${BOLD}Available hooks:${NC}\n"
     printf "  Stop              - Sound + notification when tasks complete\n"
@@ -487,6 +498,10 @@ show_usage() {
     printf "  quick-configure.sh --only Stop Notification\n\n"
     printf "  # Re-enable everything:\n"
     printf "  quick-configure.sh --enable Stop Notification SubagentStop PermissionRequest\n\n"
+    printf "  # Snooze all hooks for 1 hour:\n"
+    printf "  quick-configure.sh --snooze 1h\n\n"
+    printf "  # Check snooze status:\n"
+    printf "  quick-configure.sh --snooze-status\n\n"
     printf "${BOLD}Remote usage (no clone needed):${NC}\n"
     printf "  curl -sL https://raw.githubusercontent.com/ChanMeng666/claude-code-audio-hooks/master/scripts/quick-configure.sh | bash -s -- --list\n"
     printf "\n"
@@ -548,6 +563,22 @@ main() {
                     shift
                 done
                 ;;
+            --snooze|-s)
+                action="snooze"
+                shift
+                if [ $# -gt 0 ] && [[ ! "$1" =~ ^-- ]]; then
+                    hook_args+=("$1")
+                    shift
+                fi
+                ;;
+            --resume|--unsnooze)
+                action="resume"
+                shift
+                ;;
+            --snooze-status)
+                action="snooze-status"
+                shift
+                ;;
             --help|-h)
                 show_usage
                 exit 0
@@ -656,6 +687,81 @@ main() {
             printf "\n${BOLD}Restart Claude Code for changes to take effect.${NC}\n"
             ;;
 
+        snooze)
+            # Inline snooze (self-contained, no external script needed)
+            local duration_str="${hook_args[0]:-30m}"
+            local duration_seconds=0
+
+            if [[ "$duration_str" =~ ^([0-9]+)h$ ]]; then
+                duration_seconds=$(( ${BASH_REMATCH[1]} * 3600 ))
+            elif [[ "$duration_str" =~ ^([0-9]+)m$ ]]; then
+                duration_seconds=$(( ${BASH_REMATCH[1]} * 60 ))
+            elif [[ "$duration_str" =~ ^([0-9]+)s$ ]]; then
+                duration_seconds=$(( ${BASH_REMATCH[1]} ))
+            elif [[ "$duration_str" =~ ^([0-9]+)$ ]]; then
+                duration_seconds=$(( ${BASH_REMATCH[1]} * 60 ))
+            else
+                error "Invalid duration format '$duration_str'. Examples: 30m, 1h, 2h, 90m"
+                exit 1
+            fi
+
+            if [ "$duration_seconds" -le 0 ]; then
+                error "Duration must be greater than 0"
+                exit 1
+            fi
+
+            if [ "$duration_seconds" -gt 86400 ]; then
+                warn "Snoozing for more than 24 hours. Consider disabling hooks instead."
+            fi
+
+            mkdir -p "$QUEUE_DIR" 2>/dev/null
+            local snooze_until=$(( $(date +%s) + duration_seconds ))
+            echo "$snooze_until" > "$SNOOZE_FILE"
+
+            success "Snoozed! All audio hooks muted for $duration_str"
+            printf "Hooks will auto-resume at %s\n" "$(date -d "@$snooze_until" 2>/dev/null || date -r "$snooze_until" 2>/dev/null || echo "epoch $snooze_until")"
+            printf "\nTo cancel: quick-configure.sh --resume\n"
+            ;;
+
+        resume)
+            if [ -f "$SNOOZE_FILE" ]; then
+                rm -f "$SNOOZE_FILE"
+                success "Resumed! Audio hooks are active again."
+            else
+                info "Not snoozed. Audio hooks are already active."
+            fi
+            ;;
+
+        snooze-status)
+            if [ ! -f "$SNOOZE_FILE" ]; then
+                info "Not snoozed — audio hooks are active."
+            else
+                local snooze_until
+                snooze_until="$(cat "$SNOOZE_FILE" 2>/dev/null)" || {
+                    info "Not snoozed — audio hooks are active."
+                    exit 0
+                }
+                snooze_until="${snooze_until%%.*}"
+                local current_time
+                current_time="$(date +%s)"
+                if [ "$current_time" -lt "$snooze_until" ] 2>/dev/null; then
+                    local remaining=$(( snooze_until - current_time ))
+                    local hours=$(( remaining / 3600 ))
+                    local minutes=$(( (remaining % 3600) / 60 ))
+                    local friendly=""
+                    if [ "$hours" -gt 0 ]; then friendly="${hours}h "; fi
+                    if [ "$minutes" -gt 0 ]; then friendly="${friendly}${minutes}m"; fi
+                    if [ -z "$friendly" ]; then friendly="${remaining}s"; fi
+                    warn "Snoozed — ~${friendly} remaining"
+                    printf "Resumes at %s\n" "$(date -d "@$snooze_until" 2>/dev/null || date -r "$snooze_until" 2>/dev/null || echo "epoch $snooze_until")"
+                    printf "\nTo cancel: quick-configure.sh --resume\n"
+                else
+                    info "Snooze expired — audio hooks are active."
+                    rm -f "$SNOOZE_FILE" 2>/dev/null
+                fi
+            fi
+            ;;
+
         *)
             show_usage
             exit 0