Getting started

BlackFlare lives in your menu bar: it keeps your Mac awake while your Claude Code and Codex sessions run, and taps you the moment one finishes or needs input. This guide takes you from install to your first notification.

Requirements

macOS 13 or later, on Apple silicon or Intel. You need Claude Code or Codex already installed — BlackFlare works on the config and session files those tools already keep in ~/.claude and ~/.codex.

Install

BlackFlare ships as a notarized disk image, sold on Gumroad. It is not on the Mac App Store, and it can’t be: the App Store requires the App Sandbox, which would block reading your Claude token, launching the claude CLI, and writing to ~/.claude — that is to say, most of the app.

Buy it, download the .dmg, and drag BlackFlare.app into /Applications. (Running it from elsewhere works, but launch-at-login only persists reliably from /Applications.)
Open it. The flare icon appears in your menu bar — there is no Dock icon and no window. That is the whole app.
Walk through the three welcome pages.

First launch

The welcome window asks for two permissions, one page at a time, and only when you tap the button. Nothing is requested in the background.

Notifications. Tap Enable Notifications to grant the OS permission that lets BlackFlare post banners. Skip for now turns off every banner feature; you can enable it later. If you have previously denied notifications for BlackFlare, the page shows you where in System Settings to re-allow them.

Usage limits. Tap Allow Keychain Access to let BlackFlare read Claude Code’s own OAuth token so it can show your exact plan usage. This is off by default — Not now leaves it off and the usage section simply shows a hint. The macOS Keychain consent dialog appears after the welcome window closes, so BlackFlare is frontmost when it does. Choose Always Allow.

To see the guide again: Settings… → General → Show welcome guide again.

Your first notification

Start a Claude Code or Codex session and step away. BlackFlare posts a banner the moment the agent asks you something or finishes a turn. See Notifications for what fires when, and Telegram & Slack to route the same alerts to your phone.

You can open the BlackFlare menu from any app with a global keyboard shortcut: Settings… → General → Menu Shortcut. Click the recorder field, press a combo that includes at least one of ⌘ / ⌥ / ⌃, and it is live immediately. Clear it with the ⊗ glyph. It survives relaunch.

There is no shortcut by default, on purpose. Any combo BlackFlare picked would risk stealing a key you already use in your editor or terminal — so it ships empty and you choose. If you pick a combo macOS or another app has already claimed system-wide, the field warns you and keeps the previous one.

The shortcut is registered through Carbon’s RegisterEventHotKey, which means it needs no Accessibility or Input Monitoring permission. You will never see a TCC prompt for it.

What BlackFlare touches on your Mac

Worth knowing up front, because it edits files you own:

Reads Claude Code’s OAuth token from the Keychain — read-only, always. It never writes or replaces that item.
Writes the bot token and webhook URL you paste for Telegram or Slack into your Keychain, as its own items, and deletes them when you remove the channel.
Edits ~/.claude/settings.json and ~/.codex/config.toml when you change a default from the menu — surgically, atomically, with a one-time .bak backup. See Safety and troubleshooting.