Claude Usage Monitor

Quickstart

Windows PowerShell

irm https://raw.githubusercontent.com/aiedwardyi/claude-usage-monitor/v0.1.6/install.ps1 | iex

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/aiedwardyi/claude-usage-monitor/v0.1.6/install.sh | bash

What you get

After install, restart Claude Code. Your statusline now shows:

◆ Opus │ my-project/main
▰▰▰▰▱ 75% │ ↑50k ↓12k │ 5h: ▰▰▰▰▱ 80% (1h) │ 7d: ▰▰▱▱▱ 34% │ 2m0s

• 5h / 7d quota - see how much is left before you hit limits
• Context % - see when you're running low before Claude tells you
• Token counts - input and output for the current session
• Reset countdown - know when your quota replenishes

Uses your existing Claude Code OAuth session. No extra API key or Python packages needed. Windows launches Python directly - no Git Bash requirement.

Prefer to audit first

git clone https://github.com/aiedwardyi/claude-usage-monitor.git
cd claude-usage-monitor
git switch --detach v0.1.6
python install.py

On Windows, py -3 install.py works too.

The installer:

• copies launcher files into ~/.claude/plugins/claude-usage-monitor
• updates ~/.claude/settings.json (backs up to settings.json.bak first)
• runs a launcher smoke check and prints the verify command

Verify manually

If you want to verify the launcher yourself before restarting Claude Code:

• Windows: type nul | "C:\Users\you\.claude\plugins\claude-usage-monitor\statusline.cmd"
• macOS / Linux: printf '' | bash ~/.claude/plugins/claude-usage-monitor/statusline.sh

What it shows

All three bars show remaining % by default - they start full (green) and drain toward empty (red) as you use quota, like a fuel gauge. Prefer the fill-up style Claude Code uses? Set CQB_REMAINING=0.

Color coding

Trust and security

At runtime, the tool:

• reads Claude Code session JSON from stdin
• reads ~/.claude/.credentials.json for claudeAiOauth.accessToken (unless CLAUDE_CODE_OAUTH_TOKEN is set)
• runs git rev-parse --abbrev-ref HEAD for the branch name
• writes claude-sl-usage.json and claude-sl-usage.lock in your system temp directory
• makes one HTTPS request to https://api.anthropic.com/api/oauth/usage

It does not install dependencies, collect telemetry, or send any local data besides the usage API call.

The installer writes only to:

• ~/.claude/plugins/claude-usage-monitor/
• ~/.claude/settings.json (with .bak backup)

More detail in SECURITY.md.

Requirements

• Claude Code CLI with an active subscription
• Python 3.10+ (python3, python, or py -3)
• macOS / Linux: bash
• Windows: no Git Bash requirement

How it works

1. Claude Code pipes session JSON into the launcher on every refresh.
2. statusline.py parses the payload and reads your Claude Code OAuth token.
3. It calls Anthropic's usage endpoint to fetch 5-hour and 7-day utilization.
4. Results are cached in your system temp directory for 5 minutes.
5. The script prints a two-line ANSI statusline.

The first render may show 5h: -- and 7d: -- until the background fetch completes.

Compatibility

Customization

Every segment is toggleable via environment variables. Set them in your shell profile or in ~/.claude/settings.json:

{
  "env": {
    "CQB_PACE": "1",
    "CQB_CONTEXT_SIZE": "1",
    "CQB_COST": "1"
  }
}

Quota credentials are read from CLAUDE_CONFIG_DIR when set (as used by account-swap tools), falling back to ~/.claude.

Presets

Maximal

{ "env": { "CQB_PACE": "1", "CQB_CONTEXT_SIZE": "1", "CQB_COST": "1" } }

Minimal

{ "env": { "CQB_TOKENS": "0", "CQB_RESET": "0", "CQB_DURATION": "0" } }

Heavy context

Critical usage

Manual install

git clone https://github.com/aiedwardyi/claude-usage-monitor.git
cd claude-usage-monitor
git switch --detach v0.1.6
python install.py

On Windows, py -3 install.py works too.

Or update ~/.claude/settings.json yourself:

{
  "statusLine": {
    "type": "command",
    "command": "bash /path/to/statusline.sh",
    "padding": 0
  }
}

On Windows, prefer bash with forward-slash paths when Git Bash is on PATH. When it isn't, point directly at python.exe and statusline.py. Claude Code on Windows parses this field bash-style, so backslashes are eaten, .cmd files don't spawn, and unquoted paths split on the first space. Both python.exe and the install directory must therefore be space-free (%LOCALAPPDATA%\Programs\Python\Python313, not the all-users C:\Program Files\Python313). The -X utf8 flag keeps Python decoding the input as UTF-8 so non-ASCII workspace paths render correctly:

{
  "statusLine": {
    "type": "command",
    "command": "C:/Users/you/AppData/Local/Programs/Python/Python313/python.exe -X utf8 C:/Users/you/.claude/plugins/claude-usage-monitor/statusline.py",
    "padding": 0
  }
}

Uninstall

1. Remove ~/.claude/plugins/claude-usage-monitor/
2. Edit ~/.claude/settings.json and remove the statusLine entry (restore .bak if needed)
3. Restart Claude Code

Troubleshooting

The launcher check fails Make sure python3, python, or py -3 works from your shell.

The statusline shows 5h: -- | 7d: -- The first API call runs in the background. Wait a few seconds and let Claude Code refresh.

The statusline shows 5h: no token | 7d: no token The usage API requires an OAuth login. If you logged in with an API key, run claude login to authenticate via browser instead. The OAuth token is stored in ~/.claude/.credentials.json.

Unicode characters look wrong Use a UTF-8 terminal font. On older Windows terminals, run chcp 65001.

I want to inspect the network behavior Read statusline.py and SECURITY.md. The only network call is to https://api.anthropic.com/api/oauth/usage.

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md.

If this is useful to you, a star helps others find it.

License

MIT