VibeHandler › Guides

How to open VibeHandler on macOS

The macOS build of VibeHandler is ad-hoc code-signed but not yet notarized by Apple, so the first time you open it macOS shows a security warning: “Apple could not verify ‘VibeHandler’ is free of malware.” This is normal for apps installed outside the App Store — and it takes under a minute to open it. Here's how.

Before you start

• Apple Silicon Mac (M1–M4). The current build is arm64; an Intel build isn't provided yet.
• Claude Code CLI installed and signed in (claude on your PATH). VibeHandler is a front-end for the CLI and runs on your own Anthropic Claude subscription — it doesn't replace it.

Method 1 — System Settings (macOS Sonoma & Sequoia)

On recent macOS, the old right-click trick is gone; you approve the app once in Settings:

1. Open the downloaded .dmg and drag VibeHandler into your Applications folder.
2. Double-click VibeHandler. You'll see “Apple could not verify…” — click Done (not “Move to Trash”).
3. Open System Settings → Privacy & Security.
4. Scroll down to the Security section. You'll see “‘VibeHandler’ was blocked to protect your Mac.” Click Open Anyway.
5. Confirm with Touch ID or your password, then click Open in the final dialog.

macOS remembers your choice — from now on VibeHandler opens with a normal double-click.

Method 2 — Right-click → Open (macOS Ventura and earlier)

On older macOS you can approve it straight from Finder:

1. In Applications, right-click (or Control-click) VibeHandler.
2. Choose Open, then Open again in the dialog.

Method 3 — Terminal (one command)

This removes the “quarantine” flag macOS adds to downloads, so no warning appears at all. Make sure the app is in Applications first, then run:

xattr -dr com.apple.quarantine "/Applications/VibeHandler.app"

Now open VibeHandler with a normal double-click.

Is it safe? Why the warning appears

The warning doesn't mean the app is unsafe — it means Apple hasn't notarized it yet. VibeHandler is ad-hoc code-signed and open about exactly what it is: a desktop front-end for the official Claude Code CLI. Notarization removes the prompt entirely but requires a paid Apple Developer account; it's on our roadmap. Until then, any of the methods above lets you run it in seconds.

Troubleshooting: “VibeHandler is damaged”

If you downloaded a very early build you might have seen “…is damaged and can't be opened.” That older file was fully unsigned. Re-download the current build (it's ad-hoc signed), or fix an existing copy with:

xattr -cr "/Applications/VibeHandler.app"
codesign --force --deep --sign - "/Applications/VibeHandler.app"

What works on macOS today

The core — running many Claude Code sessions in one window, the conductor agent, and crash-safe session recovery — works on macOS. Voice input / push-to-talk isn't available on macOS yet (it's Windows-only for now). Everything else behaves the same as on Windows.

Download for Apple Silicon (M1–M4) Download for Intel Mac

Not sure? Apple menu › About This Mac: “Apple M…” = Apple Silicon, “Intel” = Intel. ~96 MB · runs on your Claude subscription · also available for Windows.