Background

Following the discussion in Issue #2 about expanding the project scope, this RFC proposes a three-tier architecture to balance simplicity with flexibility.

Design Goals

1. Progressive enhancement - Start simple, add complexity only when needed
2. Clear separation - Each tier serves a distinct audience and use case
3. Sensible defaults - The most common use case should be the default

Proposed Three-Tier Architecture

Tier 1: Minimal (🎯 Just Works)

Target: Users who want the simplest possible setup
Features: Claude Code's built-in terminal bell
Setup: One command

claude config set --global preferredNotifChannel terminal_bell

Tier 2: Recommended (⭐ Default Choice)

Target: Most users (80% use case)
Features:

• Different sounds for different events (e.g., Glass for notifications, Tink for completion)
• Cross-platform compatibility
• Pre-configured templates
  Example:

{
  "hooks": {
    "Notification": [{
      "hooks": [{
        "type": "command",
        "command": "afplay /System/Library/Sounds/Glass.aiff"
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "afplay /System/Library/Sounds/Tink.aiff"
      }]
    }]
  }
}

Tier 3: Personalized (🚀 Power Users)

Target: Advanced users with specific needs
Features:

• System/desktop notifications (visual + sound)
• Custom notification scripts
• Webhook integrations
• Multi-channel notifications
• Full control over notification behavior
  Example:

{
  "hooks": {
    "Notification": [{
      "hooks": [{
        "type": "command",
        "command": "~/.claude/custom-notify.sh"
      }]
    }]
  }
}

Questions for Discussion

1. Tier naming: Which naming scheme is most intuitive?

   • Option A: Minimal / Recommended / Personalized (current)
   • Option B: Basic / Standard / Advanced
   • Option C: Simple / Default / Pro
   • Your suggestion?

2. Default tier: Confirm that Recommended (Tier 2) should be the default?

3. Feature boundaries: Are the features correctly distributed across tiers?

   • Should system notifications be in Tier 2 or Tier 3?
   • What else belongs in each tier?

4. Cross-platform handling: How should we handle OS differences?

   • Automatic detection?
   • Platform-specific configurations?

Success Metrics

• New users can get started in < 30 seconds
• 80% of users find the recommended tier sufficient
• Power users have the flexibility they need

Please share your thoughts on:

• Is three tiers the right number?
• Are the features in the right tiers?
• What's missing or unnecessary?

cc @Biaoo - your system notification work would fit perfectly in the Personalized tier!