Hawkeye - LLM Token Tracker for VS Code
Track your Claude Code and Codex CLI usage in real time. See session limits, weekly budgets, and auto-switch between providers as you work.
Features
- Dual-provider tracking — Claude Code + OpenAI Codex side by side
- Auto-detect active tool — status bar swaps when you switch terminals
- Live session tracking — fixed 5-hour session windows with countdown timers
- Weekly budget gauges — with reset date/time countdowns
- Sync with usage pages — enter percentages from Claude or Codex and Hawkeye calibrates
- Fully customizable status bar — bar style, width, colors, separator, toggle every element
- Burn rate forecast — warns when approaching rate limits
- Multi-provider — also tracks Ollama and local LLMs
- 100% local — no data sent anywhere
Getting Started
1. Install
Install from the VS Code Marketplace or from a .vsix file.
2. Select Your Plans
On first launch, Hawkeye asks which plans you're on:
- Claude: Free / Pro ($20) / Max 5x ($100) / Max 20x ($200) / API
- Codex: Free / Go ($8) / Plus ($20) / Pro 10x ($100) / Pro 20x ($200) / API
You can change these anytime from the dashboard dropdown or VS Code Settings.
3. Start Coding
That's it. Hawkeye automatically reads:
- Claude Code logs from
~/.claude/projects/ (written by Claude Code on every API call)
- Codex CLI logs from
~/.codex/sessions/ (written by Codex CLI on every API call)
No configuration, no API keys, no manual logging needed.
4. Open the Dashboard
Click the pulse icon in the activity bar sidebar, or run Hawkeye: Open Token Dashboard from the command palette.
5. Sync for Accurate Budgets (Recommended)
Hawkeye estimates your session window automatically, but for exact accuracy:
- Go to your provider's usage page:
- Note the session % and "resets in" time
- Enter them in the Sync form in the Hawkeye dashboard
- Click Sync
After one sync, Hawkeye auto-chains to the next session — no need to sync again unless you want to recalibrate.
Status Bar
The status bar shows both providers at a glance:
* **** 4% CL Max 20x | ** 4% CX Plus
Auto-switches based on which terminal you're in — the active provider shows the full bar, the other shows a compact tag.
Customization
Everything in the status bar is customizable. Open Settings in the dashboard:
| Option |
What it controls |
| Style |
Bar characters (stars, blocks, circles, hearts, 25+ options) |
| Active width |
Number of bar characters for the active provider (0-15) |
| Standby width |
Number of bar characters for the standby provider (0-15) |
| Separator |
Character between providers (dash, pipe, dot, none) |
| Colors |
3-color gradient from low to high usage (with presets) |
| Bar |
Toggle the progress bar on/off |
| % |
Toggle the percentage |
| CL/CX |
Toggle the provider label |
| Plan |
Toggle the plan name |
| Tokens |
Toggle token count |
| Weekly |
Toggle weekly percentage |
| Standby |
Toggle the standby provider entirely |
Dashboard Sections
- Summary cards — Today, This Week, Local LLMs
- Provider cards — Claude and Codex side by side, each with session gauge, weekly gauge, plan selector, and sync form
- Activity (collapsed) — per-provider current session and previous session call logs
- Breakdowns (collapsed) — by provider, model, and project
- Daily Trend (collapsed) — 14-day bar chart
- Settings (collapsed) — status bar customization with live preview
How It Works
Data Collection (Zero Setup)
Hawkeye reads the local log files that Claude Code and Codex CLI already write:
- Claude Code writes JSONL to
~/.claude/projects/<hash>/sessions/*.jsonl
- Codex CLI writes JSONL to
~/.codex/sessions/<year>/<month>/<day>/*.jsonl
Hawkeye reads these incrementally (only new bytes since last check), deduplicates by request ID, and normalizes into a unified log.
Session Windows (Fixed, Not Rolling)
Claude and Codex both use fixed 5-hour session windows:
- Your session starts when you make your first API call
- All usage accumulates for 5 hours from that start time
- When the window expires, usage resets to 0%
- A new session begins on your next API call
Hawkeye detects session boundaries automatically by walking through your log entries. For exact accuracy, sync once using the "resets in" time from your usage page.
Terminal Detection
Hawkeye detects which provider you're using by watching VS Code's active terminal:
- Terminal named with a version number (e.g.,
2.1.104) = Claude Code
- Terminal named
node = Codex CLI
The status bar and dashboard automatically swap to show the active provider first.
Settings Reference
All settings are prefixed with hawkeye. and can be set in VS Code Settings or from the dashboard.
Plans
| Setting |
Default |
Options |
claudePlan |
max20x |
free, pro, max5x, max20x, api |
codexPlan |
plus |
free, go, plus, pro10x, pro20x, api |
Budget
| Setting |
Default |
Description |
subscriptionWindowHours |
5 |
Session window duration |
subscriptionWindowTokenBudget |
9000000 |
Session token budget |
subscriptionWeeklyTokenBudget |
80000000 |
Weekly token budget |
dailyBudgetUsd |
200 |
Daily budget for API plans |
Status Bar Display
| Setting |
Default |
Description |
barStyle |
▰▱ |
Progress bar characters |
statusBarActiveWidth |
5 |
Active bar width (0-15) |
statusBarStandbyWidth |
3 |
Standby bar width (0-15) |
statusBarSeparator |
dash |
Separator: dash, pipe, dot, none |
statusBarColorLow |
#4ec9b0 |
Color at 0% usage |
statusBarColorMid |
#dcdcaa |
Color at 75% usage |
statusBarColorHigh |
#f44747 |
Color at 100% usage |
statusBarShowBar |
true |
Show progress bar |
statusBarShowPercent |
true |
Show percentage |
statusBarShowLabel |
true |
Show CL/CX label |
statusBarShowPlan |
true |
Show plan name |
statusBarShowTokens |
false |
Show token count |
statusBarShowWeekly |
false |
Show weekly % |
statusBarShowInactive |
true |
Show standby provider |
Other
| Setting |
Default |
Description |
refreshIntervalSeconds |
5 |
Refresh interval |
claudeCodeLogsPath |
auto |
Custom Claude Code log path |
trackOllama |
true |
Enable Ollama tracking |
enableStatusBar |
true |
Show status bar widget |
Commands
- Hawkeye: Open Token Dashboard — full-page dashboard view
- Hawkeye: Refresh Metrics — force refresh
- Hawkeye: Calibrate Budget — sync from command palette
- Hawkeye: Log Rate Limit Hit — record when rate-limited
- Hawkeye: Export Usage Report — export as JSON
- Hawkeye: Add Project API Key — store API keys securely
Privacy
Hawkeye runs entirely locally. No data is sent anywhere. It reads local log files and stores metrics in VS Code's built-in storage. API keys are stored in the OS keychain via VS Code's SecretStorage.
License
MIT
Built by BlueJai
