---
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 [[email protected]](mailto:[email protected]). 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).
Common problems
Fixes for missing sessions, macOS folder-access denials, live usage and HUD issues, suppressed notifications, and where to find logs and get help.
No sessions found
Check these in order:
- Is the agent supported? See Supported coding agents - a couple are only supported on some platforms, or not in WSL.
- 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…
- (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.
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:
- Open System Settings → Privacy & Security → Files and Folders (the notice’s Open System Settings button goes straight there).
- Turn antiburn on for that folder.
- 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:
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 [email protected]. Security vulnerabilities should never go through a public issue or email - report them privately through GitHub security advisories.