How to track, monitor, and control your Claude Code usage before it eats your budget.

The problem

You're in the middle of a coding session. Your Claude Code Max 5 limit just hit — right before a critical deadline. You have no idea when it happened, why, or how much you've spent this month.

That's the reality for thousands of developers using Claude Code. The tool is powerful, but it's a black box — you can't see token usage in real time, you're not warned before hitting limits, and there's no built-in way to control spending.

This guide covers everything you need to manage Claude Code quota effectively in 2026.

Understanding Claude Code quota

Claude Code offers three plans:

The tricky part: quota resets every 5 hours (for Pro/Max 5) or rolls over (Max 20). It's easy to lose track.

What counts toward quota

• Input tokens (everything you type)
• Output tokens (everything Claude generates)
• Cache read tokens (previously cached context)
• Cache write tokens (new context saved)

Key insight: Cache hits don't count fully toward your quota — they're discounted at 10%. This makes efficient context reuse valuable.

How to track your usage in real time

The solution is claudestat — an open-source monitoring tool that hooks directly into Claude Code:

npm install -g @statforge/claudestat
claudestat install
claudestat start
open http://localhost:7337

Now you see:

• Live tool trace — every call with duration and estimated cost
• Context percentage — see the context approaching the limit before it happens
• Burn rate — tokens per minute, projected weekly/monthly spend

This is the "htop for Claude Code" — you finally see what's happening.

Setting up alerts before you hit the wall

claudestat polls your quota every 60 seconds and sends alerts:

# Default: alerts at 70%, 85%, 95%
claudestat config --alerts true

# Or check manually anytime:
claudestat status

Output:

Quota 5h   45/50 prompts (90%)  |  reset in 22m
Plan        MAX5
Burn rate   1,240 tok/min

You'll see a warning before the quota hits — no more surprise "cycle exhausted" messages mid-session.

The kill switch: auto-blocking new sessions

For power users, claudestat has a kill switch — it automatically blocks new Claude Code sessions when you hit a threshold:

# Block new sessions at 95% quota
claudestat config --kill-switch true --threshold 95

This prevents the "I accidentally burned my whole cycle" scenario. No more losing a day's work because Claude kept running.

Analyzing which tools cost the most

You know overall cost. But what if you knew which specific tools are draining your quota?

claudestat top --days 30

Output:

🏆 claudestat top — by est. cost (last 30 days)

#  Tool              Calls    Duration   Est. Cost      %
──  ─────────────────  ────────  ────────────  ─────────  ────
1   Bash              1,240      18.3m      $1.24    38%
2   Read               890       4.1m      $0.87    27%
3   Edit               430       2.8m      $0.61    19%
4   Agent (haiku)      120       9.2m      $0.38    12%
5   Write              210       1.1m      $0.12     4%

Key insight: Bash is typically 35-45% of total cost. You can immediately optimize by batching shell commands.

Loop detection

claudestat also detects inefficiency patterns — like repeated tool calls (loops):

# In the dashboard, see "Loops detected" for each session
# Or in the trace, look for patterns like:
# Read → Edit → Edit → Edit → Read → Edit → Edit

This is often 15-25% of wasted quota — money you didn't need to spend.

Exporting data for reporting

Need to report Claude Code costs to your boss or for expense tracking?

# Export as JSON
claudestat export json --output ~/claude-costs.json

# Export as CSV for spreadsheets
claudestat export csv --output ~/claude-costs.csv

# Filter by date range
claudestat export json --from 2026-04-01 --to 2026-04-30

Each row includes:

• id, started_at, cwd, project_path
• total_cost_usd
• total_input_tokens, total_output_tokens
• efficiency_score
• loops_detected

Now you can build monthly reports, track trends, or justify Claude Code as a business expense.

Summary: your quota management stack

All data stays local — zero cloud dependencies. Your usage data never leaves your machine.

What's next

Claude Code quota management in 2026 is about visibility + control:

1. Install claudestat — takes 2 minutes
2. Set up alerts — sleep better knowing you'll be warned
3. Use the kill switch for critical sessions
4. Review your top tools weekly — optimize your expensive habits
5. Export monthly — track your actual spend

The black box era is over. You have the tools to see, control, and optimize your Claude Code usage.

Try it:

npm install -g @statforge/claudestat

Questions? Drop them in the comments or open an issue on GitHub.