--- title: "How antiburn reads sessions" description: "How antiburn discovers coding-agent sessions on disk, resolves them to repositories, and keeps scanning in the background." url: "https://antiburn.ai/docs/concepts/how-antiburn-reads-sessions/" --- ## Reading what's already there antiburn never talks to a coding agent directly, and discovery itself opens no socket and calls no agent's local API. It reads the session files an agent has already written to disk - or, for a couple of agents, a local read-only store the agent's own process exposes - and builds everything else from that. See [Supported coding agents](/docs/agents/supported-agents/) for exactly where it looks for each one. Each agent has its own adapter that knows that agent's on-disk layout, so a Claude Code transcript, a Codex session, and a Cursor composer state file are all read on their own terms and normalized into the same session model. ## Where it looks antiburn 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 any other folder yourself from Settings → Sources (or during onboarding), and antiburn will search it the same way. ## Resolving sessions to repositories A session on its own is just a transcript. To show it as belonging to a project, antiburn resolves the working directory an agent session ran in back to a Git repository root, using your own local `git` - it runs no command that changes a repository or contacts its remote. Only sessions from repositories you've enabled show up in detail; you choose which repositories to track during onboarding or later in Settings → Sources. On macOS, resolving a working directory that sits inside `Documents`, `Desktop`, or `Downloads` needs the operating system's permission first. antiburn never reads one of those folders speculatively: a repository recorded there is skipped until you've explicitly granted access, and nothing about that ever happens from a background pass. See [First run and onboarding](/docs/getting-started/first-run/) for how that permission flow works, and [Common problems](/docs/troubleshooting/common-problems/) if a folder seems stuck. ## Keeping up to date A single background task keeps antiburn's view of your sessions current: once at launch, shortly after a watched transcript file changes, every five minutes as a fallback, and whenever you ask for a rescan. Passes never overlap, and a pass over sources that haven't changed costs only file-existence checks, not full transcript reads. Session analysis and the floating HUD (macOS) update live as a growing transcript changes, rather than waiting for the next full pass. ## What this doesn't touch antiburn's local store may copy content and derived facts from a transcript - messages, tool activity, token totals, and the evidence its checks need - into its own database, but it never modifies or deletes a coding agent's source files. Deleting a session from antiburn's own history never touches the agent's transcript; deleting a transcript belongs in the agent's own interface. ## Depth of analysis varies by agent Not every agent's logs carry the same level of detail. Where antiburn has a transcript format it understands in depth - the timeline, phases, context, token, and cost views - a session gets full analysis. Where it only has a generic parse, the session is still listed, but its analysis view says plainly that detailed analysis isn't available, rather than showing an empty chart that looks like nothing happened. This is also why some checks come back "not assessed" instead of pass or fail for a given session - see [Hygiene score and findings](/docs/concepts/hygiene-score-and-findings/) for what that means.
How antiburn reads sessions
How antiburn discovers coding-agent sessions on disk, resolves them to repositories, and keeps scanning in the background.
Reading what’s already there
antiburn never talks to a coding agent directly, and discovery itself opens no socket and calls no agent’s local API. It reads the session files an agent has already written to disk - or, for a couple of agents, a local read-only store the agent’s own process exposes - and builds everything else from that. See Supported coding agents for exactly where it looks for each one.
Each agent has its own adapter that knows that agent’s on-disk layout, so a Claude Code transcript, a Codex session, and a Cursor composer state file are all read on their own terms and normalized into the same session model.
Where it looks
antiburn 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 any other folder yourself from Settings → Sources (or during onboarding), and antiburn will search it the same way.
Resolving sessions to repositories
A session on its own is just a transcript. To show it as belonging to a project, antiburn resolves the working directory an agent session ran in back to a Git repository root, using your own local git - it runs no command that changes a repository or contacts its remote. Only sessions from repositories you’ve enabled show up in detail; you choose which repositories to track during onboarding or later in Settings → Sources.
On macOS, resolving a working directory that sits inside Documents, Desktop, or Downloads needs the operating system’s permission first. antiburn never reads one of those folders speculatively: a repository recorded there is skipped until you’ve explicitly granted access, and nothing about that ever happens from a background pass. See First run and onboarding for how that permission flow works, and Common problems if a folder seems stuck.
Keeping up to date
A single background task keeps antiburn’s view of your sessions current: once at launch, shortly after a watched transcript file changes, every five minutes as a fallback, and whenever you ask for a rescan. Passes never overlap, and a pass over sources that haven’t changed costs only file-existence checks, not full transcript reads. Session analysis and the floating HUD (macOS) update live as a growing transcript changes, rather than waiting for the next full pass.
What this doesn’t touch
antiburn’s local store may copy content and derived facts from a transcript - messages, tool activity, token totals, and the evidence its checks need - into its own database, but it never modifies or deletes a coding agent’s source files. Deleting a session from antiburn’s own history never touches the agent’s transcript; deleting a transcript belongs in the agent’s own interface.
Depth of analysis varies by agent
Not every agent’s logs carry the same level of detail. Where antiburn has a transcript format it understands in depth - the timeline, phases, context, token, and cost views - a session gets full analysis. Where it only has a generic parse, the session is still listed, but its analysis view says plainly that detailed analysis isn’t available, rather than showing an empty chart that looks like nothing happened.
This is also why some checks come back “not assessed” instead of pass or fail for a given session - see Hygiene score and findings for what that means.