Why I Made This
You kick off a task in Claude Code. Then life happens. Claude finishes, or hits an error, or needs a permission — but your terminal is buried under three windows.
CC-Beeper fixes that. It's a small widget that sits on your desktop, shows what Claude is doing, and lets you respond without switching apps. Never miss an update. Respond without breaking your flow.
See It in Action
https://github.com/user-attachments/assets/9df11591-ec91-4ddb-8cbe-a6c4b2a41c9a
Features
Real-Time States
At a glance, know exactly what Claude is up to. CC-Beeper tracks 8 states, each with its own pixel-art animation. Higher-urgency events always take priority.
| State | What it means | |
|---|---|---|
| SNOOZING |  | No active session. Claude is idle. |
| WORKING |  | Claude is running a tool — Busy with bash, Tinkering with write... |
| DONE! |  | Task completed successfully. |
| ERROR |  | Something went wrong. |
| ALLOW? |  | Claude needs permission. Approve (⌥A) or deny (⌥D). |
| INPUT? |  | Claude asked a question. Waiting for your response. |
| LISTENING |  | Recording your voice for dictation. |
| RECAP |  | Reading Claude's last response aloud. |
Auto-Accept Modes
When Claude Code needs to use a tool, CC-Beeper can auto-approve it or ask you first. Four presets let you dial the automation while keeping control. Switchable anytime from the menu bar.
| Mode | What happens |
|---|---|
| Strict | Ask me every time. Nothing runs without your approval. |
| Relaxed | Reads are fine. Asks before writes and commands. |
| Trusted | File operations are fine. Asks before shell commands. |
| YOLO | Don't ask. Just do it. Auto-approves everything — including file writes, deletes, and shell commands. |
Voice
Dictation
Prompt Claude, or answer its questions, just by talking. Toggle with ⌥R from anywhere, or double clap to go fully hands-free.
- WhisperKit — on-device, 99 languages, no cloud, no API key
- Apple Speech — built-in fallback, no download needed
- Works with Terminal.app, iTerm2, Warp, Alacritty, Kitty, and WezTerm
Read Aloud
Claude finished? Hear the summary out loud.
- Kokoro — on-device, 54 voices across 9 languages
- Apple Speech — built-in fallback
Global Hotkeys
Use them from any app, in any keyboard layout (AZERTY, QWERTZ, Dvorak). All remappable in Settings.
| Hotkey | Action |
|---|---|
| ⌥A | Approve pending permission |
| ⌥D | Deny pending permission |
| ⌥R | Toggle voice recording |
| ⌥T | Focus the active terminal |
| ⌥M | Stop TTS / replay last response |
Themes, Sizes & Sound
- 10 shell colors
- 3 widget sizes — Large (buttons + LCD), Compact (LCD only), or Menu Only (icon in the menu bar)
- Sound & haptics — ping on permission requests, chime on task completion, vibration until resolved
Getting Started
Requirements: macOS 14 Sonoma+ · Claude Code CLI
- Download the latest release
- Move
CC-Beeper.appto/Applications - Launch — the onboarding wizard handles hooks, theme, permissions, voice engines, and hotkeys
Everything is optional and can be changed later in Settings.
Privacy
All local. No API keys. Nothing leaves your Mac.
- All communication happens over
127.0.0.1— plaincurlhooks to a local HTTP server - No telemetry, no analytics, no crash reporting — zero outbound connections
- WhisperKit and Kokoro run on-device. Your voice is never uploaded
- No accounts, no sign-up, no tokens
- Hooks are transparent — inspect or remove them from
~/.claude/settings.jsonanytime
Technical Details
How the hooks work
CC-Beeper binds to a local port (19222-19230) on launch and registers 7 hook scripts in ~/.claude/settings.json: UserPromptSubmit, PreToolUse, PostToolUse, Stop, StopFailure (all async), plus Notification and PermissionRequest (blocking — CC-Beeper holds the TCP connection open until the user responds).
Hooks are identified by cc-beeper/port in the command string for safe update/removal without touching user hooks.
Session management
CC-Beeper tracks multiple concurrent Claude Code sessions. The displayed state resolves by priority across all active sessions. Sessions auto-prune after 2 hours of inactivity.
Instance detection
On launch, CC-Beeper pings ports 19222-19230 via HTTP to detect if another instance is already running, preventing conflicts.
Menu bar
The menu bar icon reflects the current state: normal (outline), attention (orange), YOLO (purple), recording (red circle), speaking (green speaker), or hidden (dimmed).
The menu contains: session count, state label, Mute/Unmute, Sleep/Wake, Clap Dictation toggle, Fix Permissions (when needed), auto-accept preset picker, size picker, hotkey reference, Settings, and Quit.
Settings
| Tab | What's inside |
|---|---|
| Theme | 10 shell colors |
| Dictation | Double Clap Dictation toggle, Whisper model size (small/medium), download |
| Read Over | Auto-speak toggle, Kokoro/Apple picker, language & voice |
| Feedback | Sound + vibration toggles |
| Hotkeys | 5 remappable hotkey fields |
| Permissions | 4 preset radio buttons |
| Setup | Reinstall hooks, reopen onboarding |
| About | Version, credits, links |
Disclaimer
CC-Beeper is an independent, community-built project. It is not affiliated with, endorsed by, or sponsored by Anthropic.
CC-Beeper was designed and fully vibe-coded with Claude Code. Use it at your own risk.
Auto-accept modes approve Claude Code tool requests on your behalf — including file modifications, shell commands, and network requests. YOLO mode approves everything without prompting. You are responsible for reviewing what you approve.
The authors are not liable for any damage, data loss, or unintended consequences.
Contributing
Feature suggestions and code improvements are welcome.
- Fork the repo
- Create a feature branch (
git checkout -b feature/your-idea) - Commit your changes
- Open a Pull Request
License
GPL-3.0 — see LICENSE for details.
Built by Victor Cartier
Free · Open Source · Native macOS
If CC-Beeper saves you from one missed permission prompt, give it a ⭐