claude-bell

name	claude-bell
description	Use when you need to alert the user outside the terminal, get confirmation before proceeding, or collect text input. Triggers include task completion, errors requiring attention, destructive operations needing approval, or questions requiring user decision.

Claude Bell

Send macOS notifications to communicate with users outside the terminal.

When to Use

Use for:

• Task completion (build done, tests passed, deploy finished)
• Errors requiring attention
• Confirmation before destructive operations
• Collecting text input (release notes, commit messages)
• Status updates during long operations

Don't use for:

• Routine progress updates (use terminal)
• Information user is actively watching
• Rapid-fire notifications (spam)

Quick Reference

Pattern	Command
Alert	cb -t "Done" -m "Build complete"
Alert with sound	cb -t "Done" -m "Build complete" --sound Glass
Yes/No	cb -t "Deploy?" -a "Yes,No" --default "No"
Multiple choice	cb -t "Action" -a "A,B,C,Cancel" --default "Cancel"
Text input	cb -t "Notes" -r "Enter notes..." --timeout 5m
Template	cb --template build-done --var 'project:myapp'

Exit Codes

Code	Meaning	Action
0	Success	Proceed with returned value
1	Timeout	Use --default value
2	Dismissed	Use --default value
3	User error	Check arguments
4	System error	Check permissions (cb doctor)
5	App error	Report bug

Critical Rules

1. Always provide --default for interactive notifications
2. Always check exit code - don't assume success
3. Use --timeout for non-critical prompts
4. Don't spam - one notification per logical event

References

• references/cli.md - Full CLI documentation
• references/examples.md - Workflow patterns
• references/setup.md - Installation & setup (read only when user requests setup)
• references/troubleshooting.md - Diagnosing issues