claude-plugins: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A collection of Claude Code plugins and skills for macOS productivity. Contains native macOS integrations (dialogs, voice alerts, statusline) that enhance Claude Code workflows.

Platform: macOS only (uses osascript, say command) Dependencies: jq (required), git (optional for statusline)

Repository Structure

plugins/
├── bvdr-smart-permissions/        # AI-powered auto-allow/deny permission hook
│   └── hooks/                     # PreToolUse + PermissionRequest scripts
├── bvdr-interactive-notifications/ # Native macOS dialogs for permissions/questions
│   └── hooks/                     # Bash scripts invoked by Claude Code hooks
└── bvdr/                          # Skills collection (voice alerts, statusline, Slack)
    └── commands/                  # Skill markdown files

Development Commands

# Test hook scripts directly (pipe JSON input)
echo '{"tool_name":"Bash","cwd":"/path","tool_input":{"command":"ls"}}' | bash plugins/bvdr-interactive-notifications/hooks/interactive-permission.sh

# View debug logs
tail -f ~/.claude/hooks/debug.log
tail -f ~/.claude/hooks/permission.log

# Test text-to-speech voices
say -v "?"                    # List all available voices
say -v Zarvox "Hello"         # Test specific voice

# Install plugin locally for testing
claude --plugin-dir ./

Hook System Architecture

Hooks intercept Claude Code events and return JSON decisions:

Claude Code Event → Hook Script (stdin: JSON) → AppleScript Dialog → JSON Response (stdout)

Hook Response Format:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow|deny|ask",
      "updatedInput": {},
      "message": "optional context"
    }
  }
}

Behavior values:

• allow - Approve the action
• deny - Block with optional message
• ask - Fall back to terminal prompt (timeout fallback)