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.
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 — , ... |
| | | Task completed successfully. |
| | | Something went wrong. |
| | | Claude needs permission. Approve (⌥A) or deny (⌥D). |
| | | Claude asked a question. Waiting for your response. |
| | | Recording your voice for dictation. |
| | | Reading Claude's last response aloud. |
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.
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 — plain curl hooks 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.json anytime
Technical Details
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.
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.
On launch, CC-Beeper pings ports 19222-19230 via HTTP to detect if another instance is already running, preventing conflicts.
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.
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)
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
