---
title: "First run and onboarding"
description: "What antiburn's setup asks for, why macOS prompts for folder access, and what the tray icon shows once you're done."
url: "https://antiburn.ai/docs/getting-started/first-run/"
---
## The setup window

The first time you launch antiburn, it opens a small window and walks you through four steps: Welcome, the agents it detected, the folders and repositories it'll scan, and a Ready screen. Until you finish, clicking the tray icon reopens this window rather than the usual popover, and antiburn briefly behaves like an ordinary app (it shows in the Dock on macOS) so you don't have to go looking for a menu-bar glyph before you've been told anything.

## Agents detected

antiburn scans for the coding agents it supports and shows which ones it found sessions from, with a count of sessions per agent. Each agent has a toggle - turning one off hides its sessions from the activity list and Insights, but doesn't stop antiburn from indexing them, so nothing is lost if you turn it back on later. Agents it didn't find any sessions for are listed separately so you can still enable them in case sessions show up later.

## Choosing sources

This step has two halves:

- **Folders to scan** - antiburn already searches a fixed set of common code directories under your home folder without being asked (things like `dev`, `code`, `Projects`, plus a few platform-specific spots such as `Developer` on macOS or `source/repos` on Windows). You can add more with **Add Locations…**, and remove any you've added.
- **Repos found** - the repositories antiburn discovered inside those folders, each with its own on/off switch. Only sessions from enabled repositories are scanned in detail. A "Scan all repos" control turns every discovered repository on at once; turning it off opens the list so you can choose individually.

## Why macOS asks for folder access

On macOS, `Documents`, `Desktop`, and `Downloads` are protected by the operating system - any app has to ask your explicit permission before it can read inside them. antiburn treats this deliberately: it never triggers that system permission dialog on its own, in the background, or at launch. The dialog only ever appears because you clicked a button asking for it.

If one of your repositories sits inside a protected folder, the setup screen shows a notice naming that folder rather than silently skipping it or surprising you with a system dialog. From there you have three options:

- **Grant access** - click through the notice and answer the standard macOS permission dialog.
- **Decline** - the folder is simply left alone, and antiburn tells you it's skipped rather than working around it.
- **Change your mind later** - open the folder from Settings → Sources, or grant it directly in System Settings → Privacy & Security → Files and Folders; antiburn notices the change the next time it scans.

If macOS previously remembers a refusal for a folder, asking again won't show a dialog at all - System Settings is the only way back in that case. See [Common problems](/docs/troubleshooting/common-problems/) if you're stuck on this.

## The Ready screen

Once your sources are set, antiburn analyzes what it found and shows a short summary: how many sessions it analyzed, what share of them pass antiburn's session checks, and the most common failure among the ones that don't. This step also has switches for launching antiburn at login and for having its notifications respect Focus and Do Not Disturb.

Finishing setup closes the window, drops antiburn's Dock icon on macOS, and shows one notification pointing at the menu-bar location it now lives in.

## What the tray icon shows

Once setup is done, antiburn lives permanently in your menu bar (macOS) or system tray (Windows/Linux):

- **Left-click / primary click** toggles the popover with your session activity, cost, and usage.
- **Right-click / secondary click** opens a small menu: Pin Window (keep the popover open while you work), Settings, and Quit.
- The tray icon's dot reflects your lowest remaining provider allowance across the plan limits antiburn can read - it starts full at launch, then updates from the last cached reading, and dims as any tracked allowance runs low.

See [Tray popover](/docs/app/tray-popover/) for the full popover reference.