---
title: "Common problems"
description: "Fixes for missing sessions, macOS folder-access denials, live usage and HUD issues, suppressed notifications, and where to find logs and get help."
url: "https://antiburn.ai/docs/troubleshooting/common-problems/"
---
## No sessions found

Check these in order:

1. **Is the agent supported?** See [Supported coding agents](/docs/agents/supported-agents/) - a couple are only supported on some platforms, or not in WSL.
2. **Is the session's folder being scanned?** antiburn only searches a fixed set of common code directories under your home folder by default. Add others from Settings → Sources → Add Locations…
3. **(macOS) Is the folder waiting on permission?** See the next section.

If a supported agent still isn't discovered on a platform it should work on, that's worth reporting - see [Where to get help](#where-to-get-help).

## macOS: folder access denied

macOS guards `Documents`, `Desktop`, and `Downloads` behind explicit consent, and antiburn only asks for it when you click a button - never in the background. If a repository sits in one of those folders and you haven't granted access, antiburn shows a notice naming the folder rather than skipping it silently.

If you already declined once, macOS remembers that refusal and won't show the dialog again - asking gets an instant, silent "no." The way back:

1. Open System Settings → Privacy & Security → Files and Folders (the notice's **Open System Settings** button goes straight there).
2. Turn antiburn on for that folder.
3. Back in antiburn, click **Check again** - no relaunch needed.

Revoking access the same way is picked up automatically on the next scan.

## Live usage isn't loading

Live plan-limit figures come from asking your provider directly, using the credential your own coding CLI already holds. If a provider's percentage isn't showing:

- Check **Keep my plan limits current** is on in Settings → Usage - off means no requests and no plan limits at all.
- Check that provider's meter is shown in Settings → Usage → Show Meter - a hidden provider is never asked.
- Confirm you're actually signed in to that provider's own CLI or app; antiburn reuses that credential, so an expired CLI session leaves nothing for antiburn to read.
- A reading over an hour old is marked stale, not hidden - a stale badge means the last request didn't succeed, not that nothing is configured.

## The floating HUD isn't showing up

The floating usage HUD is **macOS-only** - there's no equivalent on Windows or Linux. On macOS, check Settings → Usage → Floating HUD → **Show floating usage HUD**. It mirrors the Usage pane's own figures, so if it's on but empty, the live-usage steps above are the fix.

## Notifications aren't appearing

antiburn checks whether interruptions are welcome immediately before showing an automated notification - Focus and Do Not Disturb on macOS, fullscreen/presentation state on Windows, Do Not Disturb on GNOME and KDE Plasma. A suppressed notification is dropped, not queued, so turning Focus off afterwards won't produce a backlog.

On macOS this needs a one-time permission grant, asked for right after setup. Decline it and antiburn just stops trying to respect Focus, so notifications keep being delivered. **Test notification** in Settings → Notifications always fires regardless, since you triggered it directly.

## Logs and resetting onboarding

| Platform | Log directory                                     |
| -------- | ------------------------------------------------- |
| macOS    | `~/Library/Logs/antiburn`                         |
| Windows  | `%LOCALAPPDATA%\antiburn\logs`                    |
| Linux    | `${XDG_STATE_HOME:-~/.local/state}/antiburn/logs` |

Logs are written hourly and removed automatically after seven days. For a bundle you can attach to a bug report, use Settings → Privacy → Diagnostics → **Export…** - it leaves out transcript content, titles, file paths, repository names, and account identifiers.

**Resetting onboarding:** Settings → General → **Run setup again…** reopens setup from Welcome without losing anything - your indexed sessions, scan folders, repository choices, and preferences are all kept.

## Where to get help

For bugs and feature requests, use the GitHub issue forms on `antiburn/antiburn`:

- [Report a bug](https://github.com/antiburn/antiburn/issues/new?template=bug.yml)
- [Request a feature](https://github.com/antiburn/antiburn/issues/new?template=feature.yml)

Search existing issues first, and include only synthetic examples - never real credentials, transcripts, repository names, or private file paths. There's no guaranteed response time or private support channel.

You can also reach the team at [support@antiburn.ai](mailto:support@antiburn.ai). Security vulnerabilities should never go through a public issue or email - report them privately through [GitHub security advisories](https://github.com/antiburn/antiburn/security/advisories/new).