--- title: "Floating HUD" description: "The optional always-on-top usage readout: how it behaves, where it remembers its position, and its platform limits." url: "https://antiburn.ai/docs/app/floating-hud/" --- ## What it is The floating HUD is a small, always-on-top window that shows your provider usage bars outside the popover — useful if you want your limits visible without opening the menu bar every time. It's opt-in and hidden by default. ## Turning it on Enable it in **Settings → Usage → Show floating usage HUD**. It shows the same figures as the Usage pane, so it's only as current as your live-usage refresh is — turning that switch off elsewhere leaves the HUD with nothing to draw. ## What you see Collapsed, the HUD is just bars on a transparent background — no panel, no chrome. Each bar has 20 segments. Only the first bar blinks, and only while a session is actively live; the detail window never blinks. Rest the pointer on the HUD for about 400ms and a separate detail window appears next to it: the antiburn wordmark, and for each limit a label, a percentage, a bar, and its reset time. Move the pointer away and the detail window disappears immediately. Reset times refresh every 30 seconds, and the HUD polls the usage summary every 60 seconds (a settings change reaches it immediately, without waiting for the next poll). If no meter is selected in Settings → Usage → Show Meter, the HUD shows one empty track and the detail window says so plainly (`No meter selected.`) rather than looking broken. If a meter is on but no provider has reported yet, it says `No usage limits detected yet.` instead — a real absence of data is never presented as a setting problem, or the reverse. ## Moving it Drag the HUD anywhere on screen. It remembers where you left it, per display — each display is identified by its name, size, and scale factor, so two identical monitors are treated as the same identity. antiburn remembers up to 8 displays, most-recently-used first. If your preferred display isn't connected, the HUD falls back to the next remembered display that is, without forgetting your preferred one — reconnect it and the HUD returns there. Only dragging changes what's remembered; a display disconnecting and reconnecting does not. A small close button (✕) sits at the HUD's top right and fades in while the pointer rests on it — click it to hide the HUD. That also turns off the Settings → Usage switch, so the two stay in sync. ## Platform support The floating HUD is **macOS-only** in this version. On Windows and Linux, the Settings entry point for it doesn't appear at all. ## Under the hood, briefly The HUD sits above full-screen spaces and follows you between virtual desktops. A transcript write keeps a session "live" (and the first bar blinking) for 90 seconds; the HUD checks session liveness every 5 seconds independently of its 60-second usage poll.
Floating HUD
The optional always-on-top usage readout: how it behaves, where it remembers its position, and its platform limits.
What it is
The floating HUD is a small, always-on-top window that shows your provider usage bars outside the popover — useful if you want your limits visible without opening the menu bar every time. It’s opt-in and hidden by default.
Turning it on
Enable it in Settings → Usage → Show floating usage HUD. It shows the same figures as the Usage pane, so it’s only as current as your live-usage refresh is — turning that switch off elsewhere leaves the HUD with nothing to draw.
What you see
Collapsed, the HUD is just bars on a transparent background — no panel, no chrome. Each bar has 20 segments. Only the first bar blinks, and only while a session is actively live; the detail window never blinks.
Rest the pointer on the HUD for about 400ms and a separate detail window appears next to it: the antiburn wordmark, and for each limit a label, a percentage, a bar, and its reset time. Move the pointer away and the detail window disappears immediately. Reset times refresh every 30 seconds, and the HUD polls the usage summary every 60 seconds (a settings change reaches it immediately, without waiting for the next poll).
If no meter is selected in Settings → Usage → Show Meter, the HUD shows one empty track and the detail window says so plainly (No meter selected.) rather than looking broken. If a meter is on but no provider has reported yet, it says No usage limits detected yet. instead — a real absence of data is never presented as a setting problem, or the reverse.
Moving it
Drag the HUD anywhere on screen. It remembers where you left it, per display — each display is identified by its name, size, and scale factor, so two identical monitors are treated as the same identity. antiburn remembers up to 8 displays, most-recently-used first. If your preferred display isn’t connected, the HUD falls back to the next remembered display that is, without forgetting your preferred one — reconnect it and the HUD returns there. Only dragging changes what’s remembered; a display disconnecting and reconnecting does not.
A small close button (✕) sits at the HUD’s top right and fades in while the pointer rests on it — click it to hide the HUD. That also turns off the Settings → Usage switch, so the two stay in sync.
Platform support
The floating HUD is macOS-only in this version. On Windows and Linux, the Settings entry point for it doesn’t appear at all.
Under the hood, briefly
The HUD sits above full-screen spaces and follows you between virtual desktops. A transcript write keeps a session “live” (and the first bar blinking) for 90 seconds; the HUD checks session liveness every 5 seconds independently of its 60-second usage poll.