Back to Blog

How to Monitor Claude Code Usage and Costs (Without Squinting at a Terminal)

Operations··10 min read·
Claude Codecostsmonitoringtutorial

You're paying $200 a month for Claude Pro/Max. You have six agents running across three projects. Last Tuesday one of them burned through your 5-hour window in 40 minutes doing an overly ambitious refactor, and you didn't notice until Claude started refusing requests.

You open your terminal. You type /cost. You see the token count for this session. Helpful, but that agent ran across four sessions last week. Where did the other 80% of your budget go?

This is the core problem: Anthropic gives you powerful usage-based tooling with almost no visibility into aggregate spending. The Max plan is worth it — the throughput is genuinely transformative — but flying blind at $100-200/mo is a bad feeling. Let's fix that.

The Three Cost Dimensions You Need to Track

Before picking a monitoring tool, you need to understand what you're actually tracking. Claude Code costs aren't a single number — they're three overlapping constraints.

1. The 5-Hour Rolling Window

Max plan users get a 5-hour rolling usage window. This isn't clock time — it's model compute time. A complex reasoning task that takes Claude 45 seconds of thinking counts more than a quick file edit. When you exhaust the window, you're throttled until older usage rolls off.

The tricky part: you can't see how much of the window you've consumed unless you're actively in a session. There's no "you're at 73% of your 5-hour window" indicator outside the CLI.

2. The Weekly Cap

Anthropic enforces a weekly usage cap that resets on a rolling basis. Hit it, and you're downgraded to slower throughput for the remainder of the period. The exact cap varies by plan tier and isn't published as a fixed number, which makes it harder to plan around.

3. Per-Run Token Costs

Every Claude Code invocation has a token footprint: input tokens (your code context, CLAUDE.md files, tool results), output tokens (Claude's responses and tool calls), and — if you're using extended thinking — reasoning tokens. These vary wildly depending on the task. A simple "rename this variable" might cost 2K tokens. A "refactor this module and write tests" can easily hit 100K+.

When you're running multiple agents on cron schedules, these per-run costs compound fast.

The Current Monitoring Landscape

Let's be honest about what exists today and where each option falls short.

The /cost Command (Built-in)

Every Claude Code user has this. Type /cost in any session and you'll see:

Session cost: $1.24
  Input tokens:  45,230
  Output tokens: 12,891
  Cache reads:    8,420
  Cache writes:   3,100

Strengths: Zero setup, always available, accurate per-session breakdown.

Limitations: It's per-session only. When the session ends, that data is gone. There's no aggregation across sessions, no historical view, and no way to compare agents or projects. If you need to answer "how much did my test-runner agent cost this week?" — you can't.

The Admin Analytics Dashboard

Anthropic provides an organization-level analytics dashboard at console.anthropic.com. It shows API usage, costs over time, and per-model breakdowns.

Strengths: Real data from the source, historical charts, model-level granularity.

Limitations: It's owner/admin-only. If you're an individual developer on a Max plan (not an org admin), you may not have access. It also doesn't break costs down by agent, project, or cron job — it's aggregate billing data, not operational insight.

ccusage (Open Source CLI)

ccusage is a community-built CLI tool that parses your local Claude Code session logs to reconstruct cost history. It reads from ~/.claude/projects/ and aggregates token usage across sessions.

npm install -g ccusage
ccusage

Strengths: Works offline, reads real session data, no API keys needed, open source. It can show per-project and per-session breakdowns with cost estimates.

Limitations: It's a CLI tool — you get a terminal table, not a dashboard. There's no real-time monitoring, no 5-hour window tracking, and no way to visualize trends over time without piping output to another tool. It also can't track cron-scheduled agent runs unless you manually correlate timestamps.

Claude-Code-Usage-Monitor

Another community project that wraps Claude Code session data into a more structured format. It focuses on tracking individual session costs and providing alerts when spending exceeds thresholds.

Strengths: Threshold-based alerts, structured output, lightweight.

Limitations: Similar to ccusage in that it's terminal-based. The alert system is useful, but you still lack a visual overview of where your budget is going across agents and time periods.

A Web Dashboard for Claude Code Costs

This is where ClawPort's cost dashboard comes in. Instead of parsing terminal output or running CLI commands, you get a persistent web UI that tracks all three cost dimensions in real time.

Here's what the dashboard surfaces:

Real-Time Utilization Bars

Two horizontal bars at the top of the cost view show your 5-hour rolling window and weekly cap utilization as percentages. These update as your agents run. When you're at 85% of your 5-hour window, you see it immediately — not after your next agent gets throttled.

5-Hour Window:  ||||||||||||||||||||------  78%
Weekly Cap:     ||||||||||----------------  42%

The bars shift from green to amber to red as you approach limits, so the status registers at a glance.

Daily Cost Chart

A time-series chart showing your daily spending over the past 7, 14, or 30 days. Each bar breaks down into model tiers (Opus, Sonnet, Haiku) so you can see if a spike came from an expensive Opus reasoning task or a high volume of Sonnet completions.

This is where patterns emerge. You'll notice things like "every Wednesday my costs spike 3x" — and then realize that's when your weekly dependency-update cron runs with Opus.

Per-Cron Cost Breakdown

If you're using ClawPort's cron pipelines to schedule agent work, each cron job gets its own cost line item:

| Cron Job | Last Run | Avg Cost | Model | |----------|----------|----------|-------| | test-runner/nightly | 2h ago | $0.84 | Sonnet | | docs-sync/daily | 6h ago | $0.31 | Haiku | | deps-update/weekly | 3d ago | $2.17 | Opus | | memory-consolidate/6h | 1h ago | $0.12 | Haiku |

This is the breakdown that ccusage and the admin dashboard can't give you. You see exactly which automated tasks are eating your budget and can make targeted optimizations.

Token Donut Chart (Model Split)

A donut chart showing your token distribution across model tiers. If 70% of your tokens are going to Opus when most of your tasks are routine, that's an immediate optimization target.

Optimization Score with AI Insights

ClawPort calculates an optimization score based on your usage patterns — model selection efficiency, cache hit rates, output token ratios, and peak-hour scheduling. The score comes with AI-generated insights:

"Your test-runner agent is using Opus for all runs. Switching to Sonnet for standard test execution could reduce costs by ~40% with minimal quality impact. Reserve Opus for complex debugging sessions."

These aren't generic tips. They're derived from your actual usage data.

Inline AI Chat for Cost Questions

A chat interface embedded in the cost dashboard where you can ask natural-language questions about your spending:

  • "Which agent cost the most this week?"
  • "What's my average daily spend trend?"
  • "Am I likely to hit my weekly cap at this rate?"

The chat has full context of your cost history and can answer questions that would otherwise require manual calculation.

The Sidebar Usage Widget

Beyond the dedicated cost dashboard, ClawPort renders a compact usage widget in the sidebar that's visible on every page. It shows:

  • Current 5-hour window utilization (percentage + visual bar)
  • Weekly cap status
  • Today's running cost total

This means you don't have to navigate to the cost page to check your status. Whether you're on the org map, the kanban board, or reviewing agent activity — your utilization is always one glance away.

Practical Tips for Reducing Claude Code Costs

Regardless of which monitoring tool you use, these patterns will stretch your budget further.

1. Use Model Tiering Aggressively

Not every task needs Opus. A rough rule of thumb:

  • Opus: Complex architectural decisions, multi-file refactors, debugging subtle issues, code review with nuanced feedback
  • Sonnet: Standard feature development, test writing, straightforward bug fixes, documentation
  • Haiku: Linting, formatting, simple file operations, memory consolidation, boilerplate generation

If you configure your agents with explicit model preferences in their CLAUDE.md or agent config, you can cut costs 30-50% without meaningful quality loss on routine tasks.

2. Maximize Cache Utilization

Claude Code caches file contents and tool results within a session. Cache reads are significantly cheaper than fresh input tokens. To take advantage of this:

  • Keep sessions alive for related tasks instead of starting fresh each time
  • Front-load context by reading key files early in the session so they're cached for subsequent operations
  • Group related tasks in the same session rather than spreading them across many short sessions

3. Trim Output Where Possible

Output tokens cost more than input tokens. A few patterns to reduce output bloat:

  • Ask agents to be concise in their responses when you don't need verbose explanations
  • Use structured output formats (JSON, tables) instead of prose for data-heavy responses
  • Skip "let me explain my reasoning" preambles for routine tasks by configuring your agent's system prompt accordingly

4. Schedule Crons to Spread Load

If you have multiple cron jobs, stagger them so they don't all fire at the same time and burn through your 5-hour window in parallel. Spread resource-intensive jobs across the day:

# Bad: everything at midnight
0 0 * * * test-runner
0 0 * * * docs-sync
0 0 * * * memory-consolidate

# Better: staggered across the day
0 2 * * * test-runner        # 2 AM
0 8 * * * docs-sync          # 8 AM
0 14 * * * memory-consolidate # 2 PM

This keeps your rolling window from spiking and reduces the chance of hitting throttling during your active working hours.

5. Audit Idle Agents

Agents that run on schedule but produce minimal value are pure cost. Review your cron job history monthly. If a scheduled task consistently costs $0.50+ per run but hasn't surfaced a useful result in weeks, kill it or reduce its frequency.

The Bigger Picture

Cost monitoring isn't about penny-pinching — it's about informed allocation. When you can see that your test-runner agent costs $18/week on Opus but could cost $7/week on Sonnet with the same pass rate, that's not a cost cut. It's a reallocation. You take that $11 and put it toward the complex architectural work where Opus actually matters.

The developers getting the most value from their Max plans aren't the ones spending the least. They're the ones who know exactly where every dollar goes and can make deliberate tradeoffs.

Want real-time cost visibility for your Claude Code agents? ClawPort gives you the dashboard, the utilization tracking, and the AI-powered optimization insights. Free and open source — npm install clawport-ui to get started.