Documentation
Everything you need to set up and use Usage traker.
Quick startServicesUnderstanding limitsNotificationsLook & feelCompanion programTokens & timeTroubleshooting
Quick start
- Tap the round + button on the Limits screen and choose Claude, ChatGPT or Gemini. Where a service splits chat and agent limits (ChatGPT/Codex, Gemini/Gemini CLI/Antigravity) you then choose which one.
- Give the block a name if you like and sign in. Your limits appear as soon as the sign-in finishes.
- Pull the list down to refresh. Touch and hold a block to drag it to another place.
- Use the ⋮ menu on a block to rename it, turn reset notifications on or off, refresh or delete it. The small arrow at the bottom right of a block shows your plan and subscription date.
Services
| Block | What you see | Sign-in |
|---|---|---|
| Claude | 5-hour and weekly limits (and weekly Opus/Sonnet limits where your plan has them). Chat and Claude Code share one limit. | Via the browser (copy the code the page shows back into the app), or by signing in to claude.ai inside the app (e-mail). The second way also lets the app read your subscription date. |
| ChatGPT (chat) | Per-feature counters such as Deep research or image generation, as “left of the most seen”. ChatGPT chat has no 5-hour or weekly meter. | OpenAI sign-in in your browser (Google, Apple or e-mail). |
| Codex (agent) | 5-hour and weekly limits. | Same OpenAI sign-in as the Codex CLI. |
| Gemini (chat) | Your plan only. Google does not share the limits of the Gemini chat app. | Google sign-in. |
| Gemini CLI (agent) | Per-model quotas from Gemini Code Assist. | Google sign-in. The account needs Gemini Code Assist / Gemini CLI access. |
| Antigravity (agent) | 5-hour and weekly limits for Gemini models and for Claude/GPT models, read from the Antigravity desktop app on your computer. | No separate sign-in — pair your computer (see Companion program) and keep the Antigravity app open. Currently Linux only. |
Understanding limits
- 5-hour limit — a rolling window that starts when you begin using the service. The app shows the percent used and the time until it resets.
- Weekly limit — a separate, longer limit. When it is used up, the 5-hour limit does not help you until the weekly one resets.
- Colours — a block is shown in its AI’s colour. From 80% the number turns amber, at 100% the block turns red.
- Refreshing — the app refreshes in the background every 15, 30 or 60 minutes (Settings), when you open it, and when you pull the list down. Each account is asked at most once every 30 seconds. If a service answers “too many requests”, the app waits and shows when it will try again.
Notifications
Settings → Notifications.
- Notifications — the master switch for all notifications.
- Resets of all limits — on: every block notifies you. Off: only the blocks you ticked in their ⋮ menu.
- Only after exhaustion — notify about a reset only if the limit had been used up completely.
- When a limit runs out — an extra notification the moment a limit reaches 100%.
- No “5-hour limit is back” notification is sent while your weekly limit is still used up.
- The notification title names the AI, for example “Claude · Work”.
- For notifications on the exact second, allow Alarms & reminders for the app (Android asks you, and Settings shows a shortcut).
Look & feel
- Limit style — bar, ring or reservoir (a tank that fills with waves). Settings → Limit display.
- Theme — system, dark or light, plus your own accent colour and your own colour for each AI.
- Language — English, Ukrainian, German, Spanish, French, Polish or Portuguese. On Android 13+ choose it in system settings → Apps → Usage traker → Language.
Companion program (optional)
Your phone cannot see what happens on your computer. The companion program runs there, reads the local logs of Claude Code, Codex and Gemini CLI, and sends a small summary to your phone. It also lets the app show Antigravity limits.
What it sends: token counts per day and per model, active working time per day, model names, the computer’s name, and Antigravity limit percentages. Never prompts, code, file names or file contents. The summary is encrypted with AES-256-GCM using a key that only your computer and phone have (it travels once, inside the QR code) and goes through the public relay ntfy.sh, which only sees encrypted data. It uses about 14 MB of memory.
Linux
- In the app: Settings → Tokens from computer → Connect computer → Send for Linux. Send the file to your computer (Telegram, e-mail, cloud drive…).
- In the folder with the file, run:
chmod +x usagetraker-sync && ./usagetraker-sync --install - A QR code appears in the terminal. In the app tap Scan QR code (or paste the
ut1:…code printed below it).
The program starts with your session as a systemd user service. Stop it with systemctl --user disable --now usagetraker-sync.service. Forget the pairing with ./usagetraker-sync --reset.
Windows
- In the app choose Send for Windows and send
usagetraker-sync.exeto your computer. - Open Windows Terminal or PowerShell in that folder and run:
.\usagetraker-sync.exe --install - Scan the QR code. If it looks garbled, run
.\usagetraker-sync.exe --pairand paste theut1:…code into the app.
It starts at login without a window. Windows SmartScreen may warn that the file is from an unknown publisher — the program is not code-signed yet. To stop it, end usagetraker-sync.exe in Task Manager and delete usagetraker-sync.vbs from %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup. Forget the pairing with .\usagetraker-sync.exe --reset.
You can pair several computers. To remove one, tap the bin next to it in Settings.
No Google Play services on your phone (for example GrapheneOS)? Scan the QR code with the phone’s camera app — it opens Usage traker and pairs — or paste the ut1:… code.
Tokens & time
Usage → Tokens and Time show today, the last 7 days, the last 30 days and a 14-day chart per agent. Tap a bar to see that day. Tokens are split into input, output and cache.
How working time is counted: from the moment you send a prompt until the agent’s answer (for Codex, from the start to the end of a task). A single step counts for at most 30 minutes, so time spent waiting for your approval or for an exhausted limit to reset is not counted as work. The figure is an estimate from timestamps in the logs; if two agents work at once their time adds up.
Only agents on your computer are counted. Usage in the claude.ai or chatgpt.com web apps is not in any log.
Troubleshooting
| You see | What to do |
|---|---|
| “The service temporarily limited requests” | Wait — the app retries by itself and shows the time. Refreshing again only delays it. |
| “Sign-in expired” | Delete the block and connect the account again. |
| Gemini CLI: “no licence” | This Google account has no Gemini Code Assist / Gemini CLI access (often a Workspace or paid account without it). Use an account that has. |
| Antigravity block is empty | Open the Antigravity desktop app with a project on the paired Linux computer, and check that the companion program is running. |
| Reset notification arrives late | Allow Alarms & reminders and exclude the app from battery optimisation. |
| Tokens or Time are empty | Check that the companion program is running (systemctl --user status usagetraker-sync.service on Linux). The first sync can take a few minutes. |
Still stuck? Use Settings → Report a problem in the app — it opens an e-mail with technical details (no names, e-mail addresses or tokens) that you can read and edit before sending.
See also the privacy policy.