Key Takeaways
- Claude Code costs $20 to $200 a month on a Claude plan. Pro, Max and Ultra include it with usage limits. On an API key you pay for what you use instead.
- Most of the bill is the conversation Claude carries. Every file it reads and every command it runs is stored, then sent again with each later request, so a big file read early keeps costing you.
- On a plan, watch the limit bars in
/usage. They show how close you are to your five-hour and weekly limits. The dollar figure on the same screen is only an estimate at API prices. - A script that stops Claude reading long files whole saves a little. Opus 5.5 already searches first and reads long files in pieces, so the script mostly works as insurance against the odd whole-file read.
- Don’t hand code reviews to a cheaper model. When we ran a review on Sonnet, or had a Haiku helper read the file for Opus, the cost dropped sharply, but neither caught a real bug that Opus found by reading the file itself. Use the cheaper models for routine changes.
- Put a hard cap on anything that runs without you. Claude Code’s non-interactive mode,
claude -p, takes a--max-budget-usdflag that stops a script or scheduled job at a dollar amount. Background sessions have no documented cap.
Claude Code comes with every paid Claude plan, from $20 to $200 a month, or you can run it on an API key and pay for each token, the short chunks of text a model reads and writes. Either way, most of what you spend pays for the conversation Claude carries: everything said and read so far is stored and sent again with every request, so the longer a session runs, the more each new step costs to send.
We added up our own Claude Code sessions to see where the tokens go, then tested two fixes on a real open-source codebase. The first is a hook, a script Claude Code runs before Claude acts, that stops Claude from reading long files whole. The second is a reader subagent, a helper Claude hands work to, that runs on Haiku, Anthropic’s cheapest model. This guide covers what each plan costs, how to check your usage, what the fixes saved, and the caps that stop an unattended agent from running up a bill.
How we tested
Claude Code 2.1.317, the current version on November 6, 2026, with Opus 5.5 at its default effort setting, which controls how much it reasons before answering. Our own numbers come from the session files Claude Code keeps on disk: 23 active days since late July, about $829 at Anthropic’s list API rates. The fixes ran on Documenso, an open-source DocuSign alternative, at commit fdd0337, in fresh sessions started with claude -p, Claude Code’s non-interactive mode: five setups of four runs each for a review task, and three runs each for a narrower one. Dollar figures are Claude Code’s own estimates at list prices. One repo and a handful of runs per setup is a small sample, so read the numbers as a direction.
What Claude Code Costs in 2026
Claude Code is included in every paid Claude plan, and it draws on the same usage allowance as the Claude chat apps (Anthropic pricing). The Free plan doesn’t include it.
| Plan | Price a month | Usage |
|---|---|---|
| Pro | $20, or $17 billed yearly | The base allowance |
| Max | $100 | 5 times Pro |
| Ultra | $200 | 10 times Pro each week, no five-hour limit for verified accounts |
| Team Standard | $25 a seat, or $20 yearly | More than Pro |
| Team Premium | $125 a seat, or $100 yearly | 5 times Standard |
| Enterprise | $20 a seat plus API rates | Pay for what you use |
| API key | Per token | Pay for what you use |
Plans limit usage over two windows: a five-hour session that starts with your first message, and a week that resets at a fixed time. When you hit a limit, you wait, or you buy usage credits, which Anthropic used to call extra usage and bills at API rates. The old Max 20x plan is now called Ultra, at the same price, and Anthropic now describes its allowance as 10 times Pro’s weekly usage.
On an API key, the price depends on the model, and every request is billed by the million tokens it sends and receives:
| Model | Input | Output | Write | Re-read |
|---|---|---|---|---|
| Opus 5.5 | $4 | $20 | $8 | $0.20 |
| Sonnet 5.5 | $2 | $10 | $4 | $0.10 |
| Haiku 5.5 | $0.10 | $0.50 | $0.20 | $0.01 |
Prices are in dollars per million tokens, from Anthropic’s API pricing on November 6. Write and re-read are prices for Anthropic’s prompt cache, explained below; the write price is for the one-hour cache Claude Code uses on a plan. Haiku 5.5 costs five times as much once a prompt passes 100,000 tokens.
Anthropic’s own figure for Claude Code on an API key is about $13 per developer per active day (Claude Code docs). That average comes from company deployments and dates from the spring, before the cheaper 5.5 models arrived. For anyone who uses Claude Code most days, a plan is the better deal, because a month of active days at that average costs more than Ultra. The API makes sense for occasional use and for automated jobs you want billed separately.
How to See What You’re Spending
Type /usage in a session. On Pro, Max and Ultra, it shows how much of your five-hour and weekly limits you’ve used, and what used it. That’s the number to watch on a plan, because your price is fixed and the limit is what stops you. The dollar figure in its Session block is an estimate at list API prices and only matters on an API key. /cost and /stats now open the same screen. Since October it also flags waste, such as very long command output, and pressing f applies the fix it suggests.
To see it without asking, add a status line, a script whose output Claude Code shows under the prompt. Claude Code passes it the session’s estimated cost in cost.total_cost_usd and, on a plan, the share of each limit used in rate_limits.five_hour.used_percentage and rate_limits.seven_day.used_percentage.
Two more checks are worth a minute. If ANTHROPIC_API_KEY is set in your shell, Claude Code bills that key instead of using your plan, and Anthropic’s help center warns about exactly this. And Claude Code deletes session files older than 30 days by default, which is also the history that usage trackers read. Raise cleanupPeriodDays in ~/.claude/settings.json if you want months of data. We found out too late, and most of our summer was already gone.
Where the Tokens Actually Go
Every request Claude Code sends contains the whole conversation so far: its instructions, your CLAUDE.md (the instructions file Claude Code loads in every session), every message, and every file and command output. Anthropic caches that history, so it isn’t charged at full price each time. A cache write is the first time something enters the cache, and a cache read is every later request that sends it again. Re-reading is cheap, but on a plan writing costs twice the normal input price, as the Write column above shows, because Claude Code keeps the main conversation cached for an hour.
| Token type | Share of our cost |
|---|---|
| Cache writes | 50% |
| Cache reads | 38% |
| Output | 12% |
| New input | Under 1% |
That is our own work since late July, priced at list API rates. The output, everything Claude actually wrote, was the smallest real share. The rest paid for putting things into the conversation and reading them again. So the way to spend less is to put less into each conversation and to keep it shorter.
What fills the conversation? In our sessions, the output of shell commands Claude ran was the biggest source, more than half of the text its tools brought in, ahead of the files it read. Each one sits in the conversation until you clear it.
What one big file read really costs
To see what one read costs, take Documenso’s implementation.ts, a long file of API handlers. When Opus read it whole, the file added about 21,700 tokens to the conversation, and every later request in that session paid to read them again:
| Requests later | What that one read has cost |
|---|---|
| 0 | $0.17 |
| 40 | $0.35 |
| 150 | $0.82 |
These are Opus 5.5 list prices with the one-hour cache a plan uses. After about 40 more requests, the re-reads have cost as much as the read itself, and a long working session keeps going well past that, so a file read once at the start keeps charging you until you clear the conversation. On a plan, the same tokens come out of your five-hour and weekly allowance instead.
Spotify’s Shunt Plugin and Its 90% Claim
In September, Spotify’s engineering blog published “Portal by Spotify cut my Claude Code token usage by 90%” (Spotify Engineering), about a Claude Code plugin called shunt. Its hooks stop Claude from reading whole files over 350 lines, and from printing large files with cat, head or tail. Claude is told to use a reader skill (a saved set of instructions Claude can call up) instead, which sends the files to a cheaper worker model through Portal, Spotify’s paid developer portal, and returns a short answer.
Blocking big reads makes sense, but the figure needs a careful read, because it comes from Spotify’s own test on one large Java codebase. The plugin’s benchmark script estimates tokens as characters divided by four, and it counts only what lands in Claude’s own conversation, so the worker model’s tokens aren’t in the total (shunt’s benchmark script).
Characters divided by four also undercounts for Claude. The file above came to close to twice that estimate in our test, because the Read tool adds line numbers and Claude’s current tokenizer, the part that splits text into tokens, makes more of them from the same text. And shunt only runs if you have a Portal instance. The next two sections build the same idea from parts that come with Claude Code.
Limit How Much of a Long File Claude Reads
A hook is a script Claude Code runs at a set point, whether or not Claude agrees (how hooks differ from skills). A PreToolUse hook runs before each tool call and can refuse it, with a reason that Claude reads. This one watches the Read tool. On a file over 400 lines, it allows up to 200 lines at a time and refuses anything bigger, telling Claude to search first or hand the file to a reader. It’s a bash script and needs jq, a small command-line tool for reading JSON, which recent versions of macOS include and every Linux package manager carries.
#!/usr/bin/env bash
# PreToolUse hook: stop Claude from reading long files whole.
input=$(cat)
file=$(jq -r '.tool_input.file_path // empty' <<<"$input")
limit=$(jq -r '.tool_input.limit // 0' <<<"$input")
agent=$(jq -r '.agent_type // empty' <<<"$input")
[ "$agent" = "bulk-reader" ] && exit 0
case "$file" in *.png|*.jpg|*.jpeg|*.gif|*.webp|*.pdf) exit 0 ;; esac
[ -f "$file" ] || exit 0
lines=$(wc -l < "$file" | tr -d ' ')
[ "$lines" -le 400 ] && exit 0
[ "$limit" -gt 0 ] && [ "$limit" -le 200 ] && exit 0
reason="$file has $lines lines. Grep for what you need and read at most \
200 lines at a time, or ask the bulk-reader agent to read it."
jq -n --arg r "$reason" '{hookSpecificOutput: {hookEventName: "PreToolUse",
permissionDecision: "deny", permissionDecisionReason: $r}}' Save it as .claude/hooks/read-guard.sh, make it executable with chmod +x, and register it in .claude/settings.json, merged with any hooks you already have:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Read",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/read-guard.sh"
}
]
}
]
}
} Our first version copied shunt’s rule, which lets any read through once it names a line range. Opus walked straight past it: in both of our first review runs, it read the whole file in a few big ranged chunks, and the session cost slightly more than with no hook at all. Capping the size of each slice fixed that.
Two limits to know. A hook script that crashes lets the call through rather than blocking it, so test yours before you trust it (one of the reasons rules get ignored). And files you attach with @ never pass through the Read tool, so no Read hook sees them.
Hand Long Files to a Haiku Subagent
A subagent is a helper Claude starts with its own empty conversation, and only its final answer comes back to yours (how subagents work). Pin one to Haiku 5.5, and the reading happens at a fortieth of Opus 5.5’s input price. Save this as .claude/agents/bulk-reader.md:
---
name: bulk-reader
description: Reads long files, logs and test suites and answers one
question about them. Use it when the user asks for the bulk-reader.
tools: Read, Grep, Glob
model: haiku
---
Read the files you're given, in full if you need to, and answer only
the question you were asked. Quote file:line for every claim. If the
question asks for a list, give the complete list. If the files don't
answer it, say so instead of guessing. The hook lets this agent read whole files, because Claude Code tells a hook which agent made the call. One recent change matters here too. Since July, the built-in Explore subagent runs on your main model instead of Haiku, and every plan now defaults to Opus 5.5. A project agent named Explore with model: haiku puts that searching back on the cheap model.
Call it by name, as in “have the bulk-reader agent read this log”. In our measured runs, its description told Claude to use it proactively, and Opus still never called it on its own, so the version above says to wait to be asked. The next section shows what the reader saved, and what it missed.
What the Hook and the Reader Saved
We gave Claude Code the same two-step session in five setups. First, review Documenso’s implementation.ts and say which API handlers limit their database queries to the API token’s team. Second, add a field to the database schema. The review needs the whole 1,662-line file, which is the case the hook is for. As a quality check, we noted whether each run caught a real bug in the file: one update looks up a record by the wrong kind of ID.
| Setup | Session cost | Caught the bug |
|---|---|---|
| No hook | $0.68 | 3 of 4 |
| Read hook | $0.61 | 3 of 4 |
| Hook and reader | $0.65 | 3 of 4 |
| Reader requested | $0.38 | 0 of 4 |
| Sonnet 5.5 | $0.15 | 0 of 4 |
Each row is the average of four runs on Opus 5.5, except the last, which ran on Sonnet 5.5 with no hook. Every run listed all the handlers and made the schema change correctly.
The hook alone made the session a little cheaper, and Claude caught the bug just as often. It searched for the handlers first, then read the parts it needed in 200-line slices. Runs of the same setup varied by more than that saving, though, so count on a small one.
Opus never called the Haiku reader on its own, even with the hook’s message pointing to it. When the prompt asked for the reader, the session was much cheaper, and no run caught the bug. Haiku read the file, its summary left the bug out, and Opus never saw the code. Spotify’s author saw the same thing: “The worker model found surface-level patterns but missed a subtle thread-safety bug in my testing.”
The reader also cost more than Haiku’s price list suggests, about two fifths of each session it ran in. Its prompt grew past the size where Haiku’s higher price starts, and most of what it wrote was thinking, the reasoning a model writes before it answers, which is billed as output.
Switching the whole session to Sonnet 5.5 saved the most of any setup. Sonnet listed every handler and made the schema change correctly every time, but it didn’t catch the bug in any run.
On narrower tasks, the hook did nothing at all. In a second session, Claude found which endpoints lacked a test, wrote one of the missing tests and changed the schema. Opus searched first and read only short slices of a long test file, so the hook never fired, and the session cost about the same with it as without.
So on Opus 5.5, the read hook is cheap insurance against the occasional whole-file read, and the saving it brings is small. Keep the reader for logs and long files where a summary is all you need, and ask for it by name. Choosing the model makes the biggest difference: Sonnet for routine changes, Opus when you need Claude to notice something you didn’t ask about.
Whatever loads at the start of a session is sent again with every request, so short instruction files help on every step. The VibeReady AI Framework sets up a short AGENTS.md, the instructions file coding agents read first, and scoped rules that load only what each task needs. See editions from $99 →
Hard Spend Caps for Unattended Agents
An agent that runs while you’re away keeps spending the whole time. One user on Amazon Bedrock (Claude through AWS) reported background test processes that ran for 17 hours, most of it after their session had hit its usage limit, for roughly $2,000 of usage (GitHub issue, October 2026). That’s the user’s own report, and it shows that work started in the background can outlive the session that started it.
For anything you run with claude -p, set a cap. That’s the non-interactive mode used by scripts, scheduled jobs and CI pipelines, the checks that run on every push. Here is a stop we triggered on purpose with a five-cent budget; in a real job, set the budget to what the job is worth to you:
claude -p "Summarize what each file in the envelope router does" \
--max-budget-usd 0.05 --max-turns 30 Error: Exceeded USD budget (0.05) The run stops once its estimated spend passes the cap, and the step that crosses it still finishes, so a run can end slightly over budget. --max-turns stops a run the same way, with Error: Reached max turns, even though claude --help doesn’t list the flag. Both work only with -p. Either stop exits with status 1, so a CI step fails and its log says why. The budget also halts any background subagents the run started.
Sessions you start in the background with claude --bg have no documented budget option, so put unattended work through claude -p with a cap instead. Our guide to agent loops covers turn limits and stop conditions for loops that run on a schedule.
Then cap the account itself. On a plan, set a monthly spend limit on usage credits in your claude.ai settings rather than choosing unlimited. On an API key, set a workspace spend limit in the Claude Console. Simon Willison made the case for hard limits in October: “I expect that most businesses and individuals would prefer errors to a surprise $10,000+ bill” (Simon Willison).
Habits That Cut Tokens With No Setup
Clear between tasks. /clear starts a new conversation and costs nothing, and Anthropic’s cost guide says an old conversation wastes tokens on every later message. /compact, which shrinks the conversation into a summary, is itself a large request, so save it for when you need to keep the thread. Our memory guide covers what each one keeps.
Stay on one model per task. Each model keeps its own cache, so after /model the next request writes the whole conversation to the cache again. Pick the model before you start.
Use Sonnet for routine work. Every plan now defaults to Opus 5.5, and Sonnet 5.5 costs half as much per token. It also used fewer steps in our tests, so switch to it at the start of a batch of small changes, and keep Opus for reviews.
Mind long breaks. On a plan, the main conversation stays cached for an hour, and on an API key or usage credits for only five minutes. After a longer break, the next request writes the whole conversation to the cache again. Claude Code now compacts a big conversation left idle for nearly an hour, but /clear before a new task is cheaper still.
Keep always-loaded files short. CLAUDE.md, rule files that aren’t limited to certain folders, and the descriptions of your skills ride along on every request. Our memory guide shows what loads in every session.
Frequently Asked Questions
How much does Claude Code cost per month?
Claude Code is included in every paid Claude plan: Pro at $20 a month ($17 billed yearly), Max at $100 and Ultra at $200. Team seats cost $25 or $125 a month. On an API key you pay per token instead, and Anthropic's docs put the average at about $13 per developer per active day.
Is Claude Code free?
No. The Free plan doesn't include Claude Code. You need Pro or a higher plan, a Team or Enterprise seat, or an API key with credit in the Claude Console.
Does /cost show what I pay on a Max plan?
No. /cost now opens /usage, and its dollar figure is an estimate at API list prices, meant for API users. On Pro, Max and Ultra you pay the flat plan price, so watch the bars for your five-hour and weekly limits instead.
Is Claude Code cheaper on the API or on a plan?
For daily use, a plan. At Anthropic's average of about $13 per active day, a month of API use costs more than the $200 Ultra plan. The API makes sense for occasional use and for automated jobs you want billed separately.
Why did my Claude Code usage jump after a break?
The cache expired. On a plan, Claude Code keeps the main conversation cached for an hour; on an API key or usage credits, for five minutes. After a longer break, the next request writes the whole conversation to the cache again, which costs more than re-reading it. Running /clear before a new task avoids paying that for an old conversation.
How do I stop a background agent from running up a bill?
Run unattended work with claude -p and set --max-budget-usd and --max-turns, so the run stops with an error once it passes the cap. Sessions started with claude --bg have no documented budget option. On a plan, also set a monthly spend limit on usage credits; on an API key, set a workspace spend limit in the Claude Console.
Have more questions? See our full FAQ →