AI Code Usage Tray

A local-first Windows tray monitor for the usage, quotas, accounts and session activity of Claude Code / Desktop, Codex CLI / Desktop, and Grok CLI.

English | 简体中文

Download the latest Windows portable build · Quick start · Development

Note

For Claude and Codex, the cost shown is an API-equivalent value computed from official standard API prices — a way to compare burn rates. Subscriptions are not billed by this amount. Grok's cost comes from the official billed value recorded by Grok CLI; within your subscription quota it does not cost extra either.

Regular Claude Desktop Home chats only leave session metadata and quota percentages on disk, with no token detail, so no cost can be computed for them. Cost only covers Claude Code / Cowork sessions that have a local transcript. Connecting a Claude account improves quota and reset accuracy but cannot fill in Home-chat tokens.

Highlights


Claude + Codex + Grok in one place	Claude Code, Claude Desktop, Codex CLI/Desktop and Grok CLI share one panel.
Independent date ranges	Each provider gets its own 1–90 day range.
Quota windows	5h / 7d usage percentages, reset times and data freshness. With a Claude account connected, the Fable window appears when available.
Per-account usage	Once enabled on this machine, tokens accumulate under the current account; older records stay out. The ledger is encrypted locally by Windows.
Session states	Working, needs attention, and idle. Desktop sessions open straight from the panel.
Edge-docked floating bar	Docks to the top or right edge, expands on hover; auto-hides over fullscreen apps (exclusive or borderless-fullscreen games, videos, presentations), and the tray menu can turn that off.
Local-first	By default it only reads data the clients already wrote on this machine. No prompts or session content are uploaded.
Zero API keys	Local mode needs no API key. Claude OAuth is optional, for more accurate quotas.

Quick start

Open GitHub Releases.
Download AI-Code-Usage-Tray-*-win-x64.exe.
Double-click to run — no install needed. Click the floating bar or tray icon to open the full panel.
Right-click the floating bar or tray icon to refresh, toggle launch-at-login, switch top/right docking, hide the floating bar, toggle fullscreen auto-hide, or quit.

Warning

The portable build is not code-signed yet, so SmartScreen may warn you. Download only from this repository's Releases and verify the SHA-256 published with each release. Signed builds will follow the Code signing policy below.

Where the data comes from

Client	Local source	Data provided
Claude Code	`~/.claude/projects/*/.jsonl`	tokens, models, projects, session activity
Claude Desktop	`%APPDATA%/Claude/plan-usage-history.json`	5h / 7d percentages
Claude Desktop	`%APPDATA%/Claude/claude-code-sessions/*/.json`	Claude Code / Cowork titles, client type, recent activity
Claude Desktop Home	`%APPDATA%/Claude/IndexedDB/`	regular-chat titles, model, message counts, recent activity (no token detail)
Claude account (optional)	Anthropic OAuth usage endpoint	official percentages and exact reset times
Codex CLI / Desktop	`~/.codex/sessions/*/.jsonl`	tokens, quota windows, models, session activity
Grok CLI	`~/.grok/sessions/**/updates.jsonl` + `~/.grok/logs/unified.jsonl`	per-turn tokens, official billed cost, subscription weekly quota, session activity

The Microsoft Store build of Claude Desktop is detected automatically under %LOCALAPPDATA%/Packages/Claude_*/LocalCache/Roaming/Claude/.

Reset times and refresh cadence

The app re-reads local data every 30 seconds.
Claude Desktop samples its quota roughly every 5 minutes, so the UI shows "sampled N minutes ago by Desktop".
Claude Desktop's local history has no resets_at. The app infers reset times from the last reset-to-zero and the next sample, marks them with ≈, and they are typically within about 5 minutes.
With a Claude account connected, official exact reset times take over. Credentials are encrypted with Windows safeStorage in the app's data directory and deleted when you disconnect.

Session states

Color	State	Meaning
🟢	Working	recently producing output, or the session file is still being written
🔴	Needs attention	waiting for a permission prompt or your action in the client
⚫	Idle	no recent activity

With the optional Claude CLI hooks installed, working / attention / idle become precise; without them the state falls back to transcript write times. A freshly written transcript overrides a stale hook so a running session never shows an old state. A hook silent for more than 30 minutes falls back to idle.

Enabling hooks (optional)

The portable build does not include the hook scripts — get the hooks/ directory from this repository (clone it, or download the two files). Then wire them into ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "node C:/path/to/ai-code-usage-tray/hooks/report-status.js" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "node C:/path/to/ai-code-usage-tray/hooks/report-status.js" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "node C:/path/to/ai-code-usage-tray/hooks/report-status.js" }] }],
    "Notification": [{ "hooks": [{ "type": "command", "command": "node C:/path/to/ai-code-usage-tray/hooks/report-status.js" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "node C:/path/to/ai-code-usage-tray/hooks/report-status.js" }] }]
  },
  "statusLine": { "type": "command", "command": "node C:/path/to/ai-code-usage-tray/hooks/report-rate-limits.js" }
}

report-status.js writes per-session states to ~/.claude/usage-tray-status/ and always exits fast, so it never slows Claude Code down. report-rate-limits.js uses the statusLine slot to capture official rate limits and prints nothing. Claude Code has a single statusLine slot — if you already use one, keep yours and skip that part; session states work without it. New sessions pick the hooks up automatically.

Privacy and security

No transcripts, prompts, project paths or session titles are uploaded.
No browser cookies are read, and no Anthropic / OpenAI / xAI API key is needed.
If a local file is corrupt, locked or unreadable, the last snapshot is kept and marked stale.
OAuth login is optional. Local monitoring keeps working offline or when Anthropic rate-limits.
Full details in the Privacy Policy.

Code signing policy

Free code signing provided by SignPath.io, certificate by SignPath Foundation.
SignPath-signed releases will be built from this repository by GitHub Actions and manually approved before signing. All releases to date remain unsigned; signing starts once the SignPath Foundation approval completes.
Committer, reviewer, and approver: @saime428.
Privacy policy: PRIVACY.md.

Development

Requires Windows 10/11, Node.js 22+ and npm:

git clone https://github.com/saime428/ai-code-usage-tray.git
cd ai-code-usage-tray
npm ci
npm test
npm start
npm run usage   # print today's usage in the terminal, no Electron needed

Build the Windows x64 portable executable:

npm run dist

The artifact lands in dist/AI-Code-Usage-Tray-<version>-win-x64.exe.

Project layout

main.js                 Electron main process, tray, windows, refresh scheduling
preload.js              restricted IPC bridge
lib/usage.js            Claude local usage and session parsing
lib/codex-usage.js      Codex local usage and quota parsing
lib/grok-usage.js       Grok local usage, official cost and weekly quota
lib/claude-oauth.js     optional Claude OAuth / PKCE
renderer/index.html     full panel
renderer/floating.html  edge-docked floating bar
hooks/                  optional Claude Code state hooks

Release checklist

npm test
npm run dist
git status --short

Bump the version in package.json, launch the portable build on a clean Windows machine, then create a GitHub Release with the .exe and its SHA-256.

Current limitations

Windows x64 only.
No auto-update yet.
The app UI is currently Chinese-only.
The portable build is not code-signed yet. The SignPath Foundation application and signing automation are in progress.
Claude OAuth may be rate-limited by Anthropic or affected by your network egress. Local inference is unaffected.
Regular Claude Desktop Home chats expose no token detail, so only session state and quota percentages can be shown — no cost.
Grok sessions are CLI-only: no per-account tracking (no identity detection yet) and no click-to-open deep link.

Contributing

Issues and pull requests are welcome. Before submitting, run:

npm test

If you add parsing logic that is not obvious at a glance, include a small test covering the real format. Never commit transcripts, credentials or personal project paths.

License

Not affiliated with or endorsed by Anthropic, OpenAI, or xAI.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
build		build
docs		docs
hooks		hooks
lib		lib
renderer		renderer
scripts		scripts
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
PRIVACY.md		PRIVACY.md
README.md		README.md
README.zh-CN.md		README.zh-CN.md
main.js		main.js
package-lock.json		package-lock.json
package.json		package.json
preload.js		preload.js

Navigation Menu

Repository files navigation

AI Code Usage Tray

Highlights

Quick start

Where the data comes from

Reset times and refresh cadence

Session states

Enabling hooks (optional)

Privacy and security

Code signing policy

Development

Project layout

Release checklist

Current limitations

Contributing

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

AI Code Usage Tray

Highlights

Quick start

Where the data comes from

Reset times and refresh cadence

Session states

Enabling hooks (optional)

Privacy and security

Code signing policy

Development

Project layout

Release checklist

Current limitations

Contributing

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages