claude-code-usage

Cross-platform Claude Code status line with real-time usage tracking via Anthropic OAuth API.

project │ ⎇ main │ Usage: 7% ▓░░░░░░░░░ → Reset: 10:00 PM

Why this one?

Most Claude usage trackers rely on session keys scraped from your browser — you have to manually copy cookies from claude.ai, paste them into config files, and refresh them when they expire. Some require a separate macOS app just to inject credentials. Others only track Claude Code CLI usage and miss activity from claude.ai, the API, or other clients.

This package does none of that.

It uses the Anthropic OAuth API — the same official API that Claude Code itself uses. Your OAuth credentials are already stored securely in your system's credential store when you log into Claude Code. No session keys, no browser cookies, no manual token management, no extra apps.

| | Session key trackers | This package | |---|---|---| | Auth method | Browser cookie (manual copy) | OAuth token (automatic) | | Token refresh | Manual — breaks when expired | Handled by Claude Code | | Tracks all usage | Only claude.ai OR only CLI | All platforms combined | | Extra apps needed | Often yes | No | | Cross-platform | Usually macOS only | macOS, Linux, Windows | | Dependencies | Varies | Zero |

The usage percentage you see reflects your total account utilization across Claude Code CLI, claude.ai, and API — not just one client.

Install

npm i -g @nathanmdj/claude-code-usage

Setup

Add to your Claude Code settings file (~/.claude/settings.json):

{
  "statusLine": {
    "type": "command",
    "command": "claude-code-usage"
  }
}

Restart Claude Code. Done.

What it shows

• Directory name — current working directory
• Git branch — current branch (if in a git repo)
• Usage % — your 5-hour utilization across all Claude platforms
• Progress bar — 10-block visual with color gradient (green → red)
• Reset time — when your usage window resets (local time)

How it works

1. Reads your Claude Code OAuth credentials from the platform credential store (already there from claude login)
2. Calls the Anthropic OAuth usage API (/api/oauth/usage)
3. Caches the result for 30 seconds to stay fast
4. Outputs a formatted, color-coded status line

No session keys. No browser cookies. No manual configuration.

Platform support

| Platform | Credential Store | |----------|-----------------| | macOS | Keychain (security CLI) | | Linux | libsecret (secret-tool CLI) | | Windows | Windows Credential Manager |

Requirements

• Node.js >= 18
• Claude Code CLI installed and authenticated (credentials are created automatically when you log in)

Zero dependencies

Uses only Node.js built-ins — no native modules, no compilation, no supply chain risk.

License

MIT