Usage guide
Install
Download Tokfuel-x.y.z.dmg from the download page or GitHub Releases.
Open it and drag Tokfuel.app onto Applications.
Launch it — releases are signed with a Developer ID and notarized by Apple, so it opens with no Gatekeeper warning.
Requires macOS 14 or later, plus python3 for the cost analysis (already included with the Xcode Command Line Tools). Without python3, cost analysis degrades gracefully — everything else keeps working.
Reading the menu bar
The ⛽️ icon shows today's or this month's cost, a percent, or a ring gauge — pick which in Settings. It turns orange near a budget limit and red once you're over it. Click it to open the popover: current cost, a daily chart for today / this week / this month / this year, a per-model breakdown, top sessions, and saving tips (from retok's Claude analysis plus Cursor-derived ones).
Budgets
Set independent monthly and daily limits in Settings. Near a limit you get a heads-up — a notification, a floating alert window, or both — fired once when the level rises.
Cursor and Codex
If Cursor is installed and you're signed in, today's Cursor usage folds into the same total and chart via Cursor's own dashboard API. Signed out or offline, it falls back to local token snapshots and says so, so a $0 figure is never mistaken for "no usage". If Codex CLI has local session logs, its cost shows as its own color in the daily chart — never merged into the Claude total. In Settings, choose combined / Claude only / Cursor only / Codex only / side-by-side.
Exporting usage
The popover's ⋯ menu has daily and monthly CSV export for the currently shown period, each with period totals and a per-model cost breakdown — useful for an admin collecting a team's spend by hand. Nothing is sent anywhere on its own.
Settings you’ll touch most
Menu bar — today’s / this month’s amount, a percent, or a ring gauge.
Budgets — monthly and daily caps, plus notification / floating alert style.
Sources — combined / Claude only / Cursor only / Codex only / side-by-side.
JPY display — fetches FX once a day when enabled (no usage data on the wire).
Analytics — distribution builds only; off until you consent. Events go through AnalyticsService.
Updates
When a newer version exists, an Update button appears in the popover footer. Detection polls GitHub Releases at launch and every 24 hours after; the asset downloads only when you click the button.