· cost monitoring · april 2026 ·

How to monitor Claude Code costs without surprises (2026 guide)

Published April 20, 2026 · by Septim Labs · 9 min read
TL;DR
  • The Anthropic console has a monthly spend ceiling but no real-time alerting — by the time you see the damage, a long agent session has already run its course.
  • Seven free tools can give you visibility into Claude Code spend; each has an honest trade-off worth knowing before you wire it in.
  • Three DIY cron patterns handle most solo-developer budgets. If you're running agents on a schedule or a team is sharing an API key, the manual approach has a ceiling.

1. The problem with Claude Code cost surprises

Claude Code bills by token, not by session or by time. That's fine when you're editing a single file or asking a contained question. It becomes a problem the moment you introduce an agentic loop — a task that spawns subagents, reads multiple files, calls tools repeatedly, and runs while you step away from the keyboard.

The core issue is the feedback loop. The Anthropic console (console.anthropic.com) shows your monthly spend in near-real-time, and you can set a monthly usage limit that hard-stops the API once your account crosses a dollar threshold. But the console doesn't push alerts mid-session. You have to check it. And by the time a monthly limit fires, you've already spent everything up to that ceiling.

What's missing is the gap between those two things: a signal that fires during a running session, before the damage compounds. The tools and patterns below are the community's current answers to that gap. None of them are perfect. The honest version of this guide says so.

2. Seven free tools, reviewed

These are the tools that show up consistently in r/ClaudeAI threads, GitHub issues, and the Anthropic community forum when developers ask "how do I see what I'm spending?" Ordered roughly by how much setup they require.

1. ccusage

Install: npm i -g ccusage · github.com/ryoppippi/ccusage

ccusage reads the JSONL session files Claude Code writes locally to ~/.claude/ and aggregates token counts by day, session, or project. Run ccusage daily to see today's spend. Run ccusage session --last 5 to inspect the last five sessions line by line. It's the closest thing to a first-party CLI dashboard that exists right now.

Limitation: reads local session files, not the Anthropic API — so it can diverge from your actual bill if there's server-side overhead (system prompt injection, tool definitions) that isn't reflected in your local JSONL. Use it as an estimate, not ground truth.

2. claudetokens

Install: pip install claudetokens · anthropic tokenizer

claudetokens (and the underlying Anthropic tokenizer library) lets you count tokens in a string before you send it. Useful for estimating prompt cost before committing a large context load, or for building a pre-flight check into your own scripts that blocks requests above a token threshold.

Limitation: pre-flight only — it tells you what a prompt will cost before you send it, but gives you nothing on running session totals or cumulative spend across the day.

3. Anthropic console (native)

No install · console.anthropic.com

The console shows your rolling monthly spend, per-model token breakdown, and lets you set a hard monthly limit. It's the authoritative source — everything else in this list is an approximation of what the console knows. Set your monthly limit the moment you add a payment method. Anthropic's API docs describe the limit mechanics in the billing section.

Limitation: monthly granularity only. There is no hourly alert, no webhook, no mid-session push notification. You can set an email alert at a dollar threshold, but it fires asynchronously — often 15–30 minutes after the threshold was crossed.

4. claude-code-usage-monitor (community)

Install: git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor · github.com/Maciek-roboblog/Claude-Code-Usage-Monitor

A Python script that reads the same local JSONL files as ccusage but surfaces them as a live terminal dashboard — a refreshing pane you can leave open in a tmux split while Claude Code runs in another. Shows token counts and a cost estimate per session. The project was active as of early 2026 with several community contributors.

Limitation: still reads local session files, same divergence risk as ccusage. Requires Python and a terminal pane you can keep visible. Not useful if you're running agents headless or on a remote machine.

5. claude-token-counter (bash wrapper)

Install: one-file bash script, no dependencies · anthropic Python SDK

Several developers have shared minimal bash wrappers that call the Anthropic API's /messages/count_tokens endpoint (docs) before sending a prompt. The endpoint returns input_tokens without actually executing the request — useful as a pre-send gate in shell scripts. Wire it to a threshold and abort if the count is over your limit.

Limitation: pre-send only, same as claudetokens. Adds one extra API round-trip per gated request, which costs a small number of tokens itself.

6. ccusage-web (dashboard fork)

Install: npx ccusage@latest web · github.com/ryoppippi/ccusage

A browser-based variant of ccusage that serves a local web dashboard on localhost:3000. Better for developers who prefer a GUI over a terminal output, or who want to share a read-only spend view with a teammate. Runs entirely local — no data leaves your machine.

Limitation: shares all of ccusage's underlying data source constraints. The web layer adds convenience, not accuracy. Still a local-file estimate, not a live API pull.

7. Anthropic Usage API (direct)

No install · docs.anthropic.com/en/api/usage

Anthropic exposes a /v1/usage endpoint on the API that returns your actual billed token counts per model per day — the same numbers the console shows. Querying it directly lets you build your own monitoring loop without parsing local session files. This is the authoritative source; use it if you want numbers that match your invoice.

Limitation: returns daily aggregates, not real-time per-request counts. A session that runs for 90 minutes and then gets queried will show the total when the API syncs — typically within a few minutes, but not instantaneous.

Running Claude Code agents on a schedule?

Septim Courier is a hands-off cost monitoring subscription. It polls the Anthropic Usage API on your behalf, sends a weekly digest, and alerts you when daily spend crosses a threshold you set. $19/mo, no setup required beyond your API key. Early access list is open now.

Join the Courier early access list →

3. Three DIY monitoring patterns

If you'd rather build than subscribe, these three patterns cover most solo-developer monitoring needs. All of them use tools that are either already on your machine or installable with a single command.

Pattern 1 · cron + ccusage diff

Daily spend diff via cron

Run ccusage daily on a cron schedule and write the output to a log file. A second cron job compares today's total against the previous day's. If the diff exceeds a threshold, it writes an alert to a file you can pick up on login.

# In crontab -e:
# Every hour, append today's token total to a log
0 * * * * /usr/local/bin/ccusage daily --date today >> ~/.claude-cost/daily.log 2>&1

# Every morning at 8am, diff yesterday vs two days ago and flag if >20% jump
0 8 * * * /usr/local/bin/node /home/you/scripts/cost-diff.js >> ~/.claude-cost/alerts.log

# cost-diff.js reads the last two lines of daily.log,
# parses the token counts, and writes "ALERT: spend up 32% vs yesterday"
# if the ratio exceeds 1.2

Good for: catching sessions that ran overnight or over a weekend and compounded without you noticing. Not good for: catching a single runaway session mid-flight — the hourly poll is too slow.

Pattern 2 · webhook + Slack alert

Real-time spend alert to Slack

Poll the Anthropic Usage API every five minutes via a cron job. When cumulative daily spend crosses a threshold, POST to a Slack webhook. This is the closest you can get to real-time without building a full monitoring service.

# cost-alert.sh
#!/bin/bash
THRESHOLD_USD=10   # alert when daily spend exceeds $10
SLACK_WEBHOOK="https://hooks.slack.com/services/YOUR/WEBHOOK/HERE"

# Pull today's usage from Anthropic API
TODAY=$(date +%Y-%m-%d)
RESPONSE=$(curl -s https://api.anthropic.com/v1/usage?date=$TODAY \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01")

# Parse total cost (requires jq)
COST=$(echo $RESPONSE | jq -r '.total_cost // 0')

# Alert if over threshold
if (( $(echo "$COST > $THRESHOLD_USD" | bc -l) )); then
  curl -s -X POST $SLACK_WEBHOOK \
    -H 'Content-type: application/json' \
    --data "{\"text\":\"Claude Code spend alert: \$$COST today (threshold: \$$THRESHOLD_USD)\"}"
fi

# In crontab:
# */5 * * * * /home/you/scripts/cost-alert.sh

Good for: getting a ping before a session goes too far. Requires a Slack workspace and a few minutes to create the incoming webhook. Swap the Slack POST for an email via sendmail or a Pushover notification if you prefer.

Pattern 3 · weekly digest via cron

Weekly spend digest to email

A Friday-afternoon cron job that pulls the week's token totals from ccusage, formats them into a plain-text summary, and sends it to your inbox. Lower-frequency, lower-noise — good for developers who run Claude Code sporadically and want a monthly mental model without checking the console daily.

# weekly-digest.sh
#!/bin/bash
RECIPIENT="you@example.com"
WEEK_DATA=$(ccusage daily --last 7)

echo "Subject: Claude Code weekly spend $(date +%Y-%m-%d)
From: alerts@localhost
To: $RECIPIENT

Weekly Claude Code usage summary:

$WEEK_DATA

-- Septim Labs cost-monitor script
" | sendmail $RECIPIENT

# In crontab (Friday at 4pm):
# 0 16 * * 5 /home/you/scripts/weekly-digest.sh

Good for: a zero-interruption summary you can scan in 30 seconds. Not good for: catching anything in real time. Treat it as a review tool, not an alert system.

4. When DIY stops scaling

The patterns above work. A senior developer can wire any of them in an afternoon. The trade-off is maintenance: cron jobs drift, Slack webhooks break when someone rotates the token, and ccusage version bumps occasionally change output formatting in ways that break shell parsers.

Three signals that the DIY approach is costing you more time than it's saving:

Those are the cases our tools are built for. They're not the only option, and the free tools above are genuinely good. But if you're past the point where cron and shell scripts feel like the right layer of infrastructure, here's what we offer:

Septim Courier ($19/mo) handles the polling and alerting layer for you. It connects to the Anthropic Usage API with your key, sends you a weekly digest, and pushes an email alert when your daily spend crosses a threshold you configure. No scripts to maintain, no cron jobs to debug. Early access list is open at septimlabs.vercel.app/septim-courier.

Septim Subagent Cost Guard ($29) operates at the agent layer rather than the reporting layer. It installs as a PreToolUse hook in your Claude Code configuration and hard-halts a running agent mid-session when cumulative spend crosses your threshold. The difference from a usage alert is the timing: Cost Guard fires before the next tool call goes out, not after the session completes. Useful for anyone running long agentic sessions who wants a circuit breaker, not just a notification. Details at septimlabs.vercel.app/subagent-cost-guard.

Septim Rescue ($299) is the in-crisis option: a one-session engagement where we audit your Claude Code billing logs, identify where the spend compounded, and give you a written plan for preventing recurrence. If you've already had a surprise bill and want a human to walk through your specific session files, this is the path. Details at septimlabs.vercel.app/septim-rescue.

To be direct: Courier and Cost Guard are not the only path to solving this. The seven free tools and three DIY patterns in this post will cover a solo developer running Claude Code in a normal workday workflow. The Septim tools are the paid, hands-off version of the same job. Use whichever fits where you are right now.

Already surprised by a bill this month?

Septim Rescue is a single focused session: we audit your billing logs, find where the spend compounded, and write a concrete plan to prevent it happening again. $299, completed within one business day.

Book Septim Rescue →

FAQ

Does Claude Code have a built-in cost monitor?
Not in real time. Claude Code writes session data locally that tools like ccusage can parse, and the Anthropic console shows your monthly total. But there is no built-in alert that fires mid-session. The /context command shows your current token window usage, not cumulative cost — those are different numbers. Real-time alerting requires either a third-party tool or the DIY patterns described above.
How accurate is ccusage compared to my actual Anthropic bill?
ccusage reads your local JSONL session files and estimates cost based on the token counts recorded there. The Anthropic console's numbers are authoritative — they include server-side overhead such as injected system prompts, tool definitions, and any caching that affects billing. In practice, ccusage tends to undercount relative to the dashboard, sometimes by 10–30% on sessions with heavy tool use. Use it to understand relative spend trends, and cross-check against the console for exact dollar amounts.
Can I set a hard spend limit on Claude Code?
Yes, but only at the monthly account level via the Anthropic console. Go to console.anthropic.com → Settings → Billing → Usage limits and set a monthly ceiling. The API will return errors once you cross that ceiling, which will stop Claude Code from making further requests. There is no native hourly or per-session limit. Septim Subagent Cost Guard replicates that behavior at the session layer using a PreToolUse hook.
What's the difference between a usage limit and a spend alert?
A usage limit hard-stops the API once a threshold is crossed — no more requests go through until the limit is raised or the period resets. A spend alert sends a notification but doesn't stop anything. Both are useful; they're not substitutes for each other. Set a monthly limit as a safety floor in the console, and layer an alert on top so you get warned before hitting the floor rather than discovering you've hit it.
Are there cost monitoring tools that work for teams sharing an API key?
The free tools in this post work at the account level, not the per-user or per-project level. If multiple developers are hitting the same API key, the Anthropic console shows a combined total with no per-user breakdown. Anthropic's Usage API returns the same aggregate. Per-user attribution requires routing requests through your own proxy layer that tags each call with a user identifier before forwarding to Anthropic — a non-trivial amount of infrastructure. That use case is one Septim Courier is designed to handle as a managed service.

Further reading