The valuable part of claude-usage-dashboard is not that it draws colored bars in a terminal. The value is that it gives a Claude Code user a fast answer to a practical question: how close is this session to the five-hour or seven-day cap window?
That makes the seed worth saving. Long Codex and Claude Code runs fail in boring ways when a plan window is almost exhausted. A local meter can prevent bad timing. The caveat is just as important: this tool reads OAuth credentials and polls an undocumented Anthropic usage endpoint. It should be treated as a small local cap meter, not as billing truth, team reporting, or a stable public API integration.
Why this one should not be dropped
The original draft failed because it sounded like another productivity dashboard. The source is better than that. The README, single Python file, tests, CI workflow, and lint config are enough to rebuild a real article around operational fit.
A Claude Code user does not need vague praise here. They need to know what the script reads, what endpoint it calls, what the two windows mean, how often it refreshes, and when the signal is too fragile to trust. That is magazine material because it helps a practitioner decide whether to run the tool next to an agent session.
What the script actually does
The project is intentionally small. Clone it, enter the directory, and run one Python file:
git clone https://github.com/wcruz-br/claude-usage-dashboard.git
cd claude-usage-dashboard
python claude_usage.pyThere are no runtime dependencies outside the Python standard library, but Python 3.11 is a real requirement. The source uses newer datetime behavior, and a local validation run showed the tests fail under the system Python 3.9 while passing 23 tests with /opt/homebrew/bin/python3.11.
For a reader, the practical command is explicit:
/opt/homebrew/bin/python3.11 claude_usage.pyPass the first run only if the script starts, shows at least one usage window, and exits cleanly with Ctrl+C. If the default python is older than 3.11, pin the interpreter path instead of editing the script.
Know the credential boundary first
The script does not ask for a new API key. It looks for the OAuth credential that Claude Code already stores. On macOS it calls the built-in security CLI against the Claude Code-credentials Keychain service. On Windows it attempts Credential Manager access through PowerShell. If those do not return data, it falls back to ~/.claude/.credentials.json.
Verify the credential path before running it next to real work:
grep -n "KEYCHAIN_SERVICE_NAME\|CREDENTIALS_PATH\|claudeAiOauth" claude_usage.pyThat check matters because a local meter that reads Claude Code credentials is still credential-reading software. Run it from a source checkout you inspected. Do not paste credentials into a fork. Do not add credentials to shell history, screenshots, or logs. If the script cannot find claudeAiOauth, it exits because the stored credential format may have changed.
The API is not a contract
claude_usage.py sends a GET request to https://api.anthropic.com/api/oauth/usage with a bearer token and the beta header anthropic-beta: oauth-2025-04-20. The README says the endpoint is undocumented and may change without notice.
Audit the request surface directly:
grep -n "USAGE_ENDPOINT\|ANTHROPIC_BETA_HEADER\|Authorization\|User-Agent" claude_usage.pyThat warning should sit near the top of any serious article. This is not the right tool for compliance reporting or a team dashboard. It is a field meter. If the endpoint returns 401, the script tells the user to run claude once to renew credentials and restart. Other HTTP errors print a short response body and retry after the refresh interval. That behavior is useful for troubleshooting, but it does not turn the endpoint into a supported API.
Read the two windows correctly
The response shape has two optional windows: five_hour and seven_day. Each window can include utilization and resets_at, and either window can be null. The code divides utilization by 100 before rendering, so a raw 4.0 value becomes 4% on the display.
Use this reading rule: start a large agent task only after checking both the percent and the reset time. If the five-hour window is high but the seven-day window is low, defer the expensive prompt until reset. If the seven-day window is also high, switch to smaller read-only work or stop. The tool does not tell you which repository, prompt, MCP server, or tool call consumed the usage; it only tells you current plan-window pressure.
Use color as a prompt, not a policy
The color logic is simple and test-covered. Green is below 60%, yellow starts at 60%, and red starts at 85%. The default bar width is 30 characters. The dashboard refreshes every 300 seconds, and SPACE can trigger an immediate refresh while the script is sleeping.
Turn that into a working rule. Green means normal work can continue. Yellow means finish the current edit and avoid opening a broad new task. Red means run only small read-only checks unless a reset is close. That rule is intentionally conservative; the tool gives a cap signal, not a workload guarantee.
Where it beats log-based tools
A log parser like Token-Dashboard is better when the question is historical: which prompts, repeated tools, or project patterns created waste? claude-usage-dashboard is better when the question is immediate: how close is the current Claude Code account to the five-hour or seven-day cap?
That distinction is why this candidate should be saved. It does not need to become a full cost platform. Its value is being narrow. Keep it running in a side terminal during a long Codex or Claude Code task, glance at the cap window before starting a heavy edit, and move deep analysis to a log tool later.
Where it is weaker than manual checking
Manual plan-page checking has one advantage: it depends on the product surface rather than an undocumented endpoint. The terminal script wins on proximity and speed, but it adds local credential access and endpoint fragility.
Use the script when the tradeoff is acceptable: personal workstation, already-authenticated Claude Code, long agent session, and a need for a nearby signal. Skip it for shared machines, locked-down corporate environments, team reporting, or any workflow where credential-reading tools need formal review.
A safe first-run checklist
The first run should be small and reviewable:
git clone https://github.com/wcruz-br/claude-usage-dashboard.git
cd claude-usage-dashboard
grep -n "USAGE_ENDPOINT\|ANTHROPIC_BETA_HEADER\|KEYCHAIN_SERVICE_NAME" claude_usage.py
/opt/homebrew/bin/python3.11 claude_usage.pyPass means the script starts, finds the expected credential source, renders the five-hour or seven-day window, refreshes when SPACE is pressed, and exits cleanly with Ctrl+C. Fail means stop and read the error. If it says the token is expired, run claude once to refresh the login. If the endpoint body says the API shape changed, use a fallback rather than patching guesses into the script.
What the tests prove
The upstream tests are useful but limited in the right way. They cover color thresholds, bar width, reset-time formatting, missing or malformed credential files, platform fallback, OAuth key extraction, token-expiry checks, and sleep behavior. The CI workflow runs Ruff and pytest on Python 3.11.
They do not test the live Anthropic usage endpoint. The test file says fetch_usage is excluded because it requires the live API, and run is excluded because it is an infinite loop. That means a green test suite proves local logic, not endpoint stability. The article should make that distinction clear.
Adoption boundary for agent work
The right place for this tool is next to a long personal Claude Code session. Keep it open while running a refactor, a multi-file review, or a Codex-assisted investigation. Check it before starting work that will consume a large context window or trigger many model calls.
The wrong place is a decision system that claims exact cost, team attribution, or guaranteed reset behavior. For those questions, use billing exports, official account surfaces, or local JSONL analysis. This script is a cap-window meter. That narrow promise is why it is useful.
Save claude-usage-dashboard as a narrow Claude Code cap meter. It is useful for personal Pro and Max users who need a quick terminal signal before launching expensive agent work; it is risky if readers treat an undocumented endpoint and local OAuth credential access as a stable billing or governance layer.
Practical takeaway
Use it only after inspecting the source. Run /opt/homebrew/bin/python3.11 claude_usage.py, confirm it reads the expected Claude Code credential source, verify that five-hour or seven-day utilization renders, and keep a fallback such as manual checking or ccusage ready because the endpoint is not public API.