Safety model & troubleshooting

BlackFlare edits config files you wrote by hand. This page explains exactly what it guarantees about those edits, and how to get a diagnostic bundle when something goes wrong.

How your config files are treated

Applies to both files — ~/.claude/settings.json through the JSON editor, ~/.codex/config.toml through the TOML editor.

Surgical writes. Only the bytes of the value being changed are rewritten. Key order, comments, indentation, trailing whitespace — every other byte of your file survives untouched. This is enforced by golden-diff tests that assert the edit span and nothing else moved. The TOML editor additionally never descends into [tables]; it manages top-level keys only.

Atomic. Writes go to a temporary file on the same volume and are renamed over the original. You can never end up with a half-written config. Symlinks are resolved first, so a dotfiles setup gets its target updated rather than the link replaced.

Backed up. The first write ever made to a file copies the pristine original to settings.json.bak or config.toml.bak. Once. It is not overwritten by later edits, so it stays a true snapshot of the file as BlackFlare first found it.

Refuses malformed files. If your config doesn’t parse, BlackFlare alerts you and writes nothing. It will not “fix” a broken file.

Post-write validation. The result is re-parsed and the expected value verified before the rename commits. A write that would produce something unexpected never lands.

If a file was edited externally — by you, an editor, or another tool — the menu state updates on its own, through a file watcher that survives atomic renames.

The Debug tab

Hidden by default. Enable it at Settings… → General → Advanced → Show Debug tab.

The tab streams the app’s own logs live (refreshed every 5 seconds while visible) with a level filter, search, and a pause button.

• Copy puts the displayed lines on your clipboard.
• Export… saves a diagnostic bundle: app and OS versions, a curated preferences snapshot, permission states, and the full log for the current run.

Two things to know about those logs. They are privacy-redacted at the source — no tokens, no credentials, and no settings.json content ever reaches them. And only the current run is available: BlackFlare writes no log files to disk, so quitting the app discards them. Export before you quit.

Common situations

The usage section shows a hint instead of numbers. Keychain access is off, which is the default. Turn it on at Settings… → General → Permissions → Keychain. See Usage limits.

Usage asks you to sign in to Claude Code. The refresh token itself has expired or been revoked — the claude CLI can’t refresh silently either. Open Claude Code and sign in.

Codex usage looks stale. It is a local snapshot from Codex’s rollout files, so it only updates while Codex is running. The “Updated Xm ago” line tells you how stale.

A Codex model or effort change had no effect. If you were using the ChatGPT desktop app, that is expected: it sends model and effort per thread from its own picker and ignores config.toml entirely. The full matrix is in Switching models.

Terminal notifications stopped after you moved the app. The hook in settings.json pointed at the old path. BlackFlare repairs it on the next launch — restart the app.

A keyboard shortcut won’t record. It needs at least one of ⌘ / ⌥ / ⌃, and it can’t already be claimed system-wide. The field warns you and keeps the previous shortcut.

Reporting a bug

Enable the Debug tab, reproduce the problem, hit Export…, and attach the bundle to a GitHub issue — or get in touch. The bundle is redacted, but skim it before sending; it is your machine.