A macOS menu bar app that monitors Claude Code sessions and notifies you when tasks complete.
- Auto-Detection: Automatically finds running Claude Code sessions across all terminals and IDEs
- Task Completion Alerts: Notification, sound, and voice alerts (individually toggleable)
- Quick Navigation: Click to jump directly to the terminal/IDE where the task completed
- Multi-App Support: Works with WezTerm, iTerm2, Terminal.app, VS Code, Cursor, PyCharm, and more
- iTerm2 Tab Navigation: Click-to-focus navigates to the exact iTerm2 tab/session via session ID, TTY, or working directory matching
- Session Groups: Organize sessions into color-coded groups with custom names
- Group by Application: Toggle view to organize sessions by terminal/IDE (Cursor, VS Code, PyCharm, etc.)
- Collapsible Groups: Expand/collapse groups to show or hide sessions
- Drag & Drop: Reorder sessions within groups or move between groups
- Per-Session Settings: Override notification, sound, and voice settings per session
- Per-Group Settings: Set default overrides for all sessions in a group
- Text-to-Speech: Speaks the project name when a task completes
- Language Detection: Automatically uses Korean voice for Korean text, English for English
- Pronunciation Rules: Define custom pronunciations (e.g., "vitess" → "vitesse")
- Cursor Extension: Beacon Terminal Navigator extension for reliable terminal tab navigation
- VS Code Extension: Shared extension for VS Code terminal integration
- PyCharm Plugin: Optional JetBrains plugin for terminal tab navigation (no AX permissions needed)
- Plugin Management: Auto-detect, one-click install, and status indicators in Settings → About
- Zoom Meeting Auto-Mute: Suppresses alerts when Zoom microphone is active (supports English and Korean locales); Accessibility permission is prompted only when enabling the feature
- DND Awareness: Automatically suppresses sound and voice when Focus/Do Not Disturb is active
- Smart Permission Prompts: Notification and Accessibility permissions are requested only when needed, not on every launch
- Auto-Update: Checks for updates from git hourly, one-click update with automatic restart
- Backward Compatibility: Safely preserves groups and settings across updates
git clone git@github.com:sendbird-playground/claude-code-beacon.git
cd claude-code-beacon
./install.sh- Launch Beacon from Applications
- Bell icon appears in menu bar (badge shows unacknowledged alerts)
- Click to see running sessions organized by groups
- When a task completes, receive notification/sound/voice alert
- Click notification or session to navigate and acknowledge
Access via ⚙️ gear icon in the popover header:
- Notification - macOS notification banner
- Sound - Glass alert sound with volume control
- Voice - Speaks project name aloud
- Zoom Auto-Mute - Suppress alerts during Zoom meetings
- Test buttons - Test sound and voice
- Create groups with custom names and colors (5 presets + custom hex)
- Double-click to edit group name inline
- Click color circle to change group color
- Drag sessions between groups
- Add rules to customize how project names are spoken
- Click to edit pattern or pronunciation inline
- Useful for technical terms or non-English words
- Version info and auto-update status
- Plugin detection and one-click installation (Cursor, VS Code, PyCharm)
- Links to GitHub repository and issues
| Application | Detection | Click-to-Focus |
|---|---|---|
| iTerm2 | Auto | Exact tab/session (session ID → TTY → working directory) |
| Terminal.app | Auto | Window & tab by TTY |
| WezTerm | Auto | Pane by TTY |
| Cursor | Auto | Window & terminal tab (via Beacon extension) |
| VS Code | Auto | Window & terminal tab (via Beacon extension) |
| PyCharm | Auto | Window & tab (via Beacon plugin or AX) |
| Other JetBrains IDEs | Auto | Window activation |
| Other terminals | Auto | App activation |
System Settings → General → Login Items → Add Beacon
- macOS 13.0+
- Swift 5.9+
MIT