AlexWrites
← Back to articles
Dev, AI

How I cut my Claude Code token usage in half

Alexandre
Alexandre
··
Reading time: 8 min
Claude Code token economy illustration — CLAUDE.md, hooks, proactive rules

Click to enlarge

In January, I compared two weeks of Claude Code sessions on the same Livate project, same task complexity. The only difference: in the second week, I had set up 5 rules before opening my first session.
Result: -52% tokens consumed.
Not thanks to /compact. Thanks to what I had configured before writing my first prompt.

Measure before you optimize: the /cost command

Before touching anything, you need to know where you stand. Claude Code has a built-in /cost command that shows real-time consumption for the current session:
Total cost:            $0.87
Total duration (API):  8m 42.3s
According to Anthropic's official documentation, the observed average is $6/dev/day, with 90% of users staying under $12/day. If you're consistently above that, the sections below are for you.

Why does Claude Code consume so many tokens?

Without rules, Claude Code is a curious intern with an unlimited credit card. It will open node_modules/ to understand a lib. Read package-lock.json (300,000 lines) to check a version. Explore .next/ because it's looking for a config file. Scan dist/ to understand the build output.
Every useless file read = burned tokens. On an intense 2-3 hour session on Livate, I measured gaps of 40 to 60% in consumption between an "unstructured" session and a disciplined one. The difference isn't the code produced. It's the amount of useless context Claude loaded into its head before coding.

The solution: a layer of proactive rules

Since I set up this approach, my average consumption per session has dropped by half. No magic. Just 5 elements that prevent context from bloating in the first place.

1. The CLAUDE.md: your project memory

CLAUDE.md is a Markdown file placed at the root of your project that Claude Code loads automatically at the start of every session. It acts as persistent memory: code conventions, architecture, commands, files to ignore.
The CLAUDE.md file at the project root is the most underrated thing in Claude Code. It's loaded automatically every session. Mine is about a hundred lines and contains everything Claude needs to know about the project: the stack, code conventions, Docker commands, folder architecture.
## Code conventions
- Backend: snake_case files, camelCase variables, PascalCase classes
- Frontend: PascalCase components, camelCase functions
- Indentation: 4 spaces (2 for JSON)
- Commits: feat:, fix:, refactor:, test:, docs:
Without it, Claude asks context questions every session. "What naming convention?", "Where's the config?", "What ORM do you use?". Each question = tokens to ask it AND to read the files that answer it. With a solid CLAUDE.md, you cut 20-30% of pure context tokens.
I covered this in detail in a previous article, but the key point here is the impact on consumption, not just code quality.

2. The token-economy.md rules file

In .claude/rules/, you can place Markdown files that are loaded automatically in every session and every agent. Unlike CLAUDE.md which describes the project, these files enforce behaviors — rules Claude must follow at all times, no matter what.
In .claude/rules/, you can place Markdown files that are loaded automatically in every session and every agent. My token-economy.md contains the token economy rules Claude must respect permanently:
# Token economy — mandatory rules

## File exploration
- Grep/Glob before Read: always target before opening a file.
- Never read: node_modules/, .next/, dist/, *.lock, DerivedData/
- Stop exploring as soon as you've found what you need.

## Context and responses
- Short answers. No recap of what was just done.
- Don't re-read a file already read in the same session.
- No introductory prose ("I'm now going to...", "Sure!").
The "Grep/Glob before Read" rule alone changes everything. Instead of opening 15 files to find a function, Claude does a targeted Grep, finds the file in one query, and reads only that one. The "no recap" rule also saves a lot: by default, Claude loves summarizing everything it just did before moving on. It's reassuring, but it costs tokens for nothing.

3. Hooks: automatic guardrails

A PreToolUse hook is a script (bash or JSON) that Claude Code runs automatically before every tool call. It can block the action, modify it, or let it through — without you needing to intervene.
Hooks are scripts that execute automatically at specific points in Claude Code's lifecycle. You can use them as guardrails to block greedy behaviors.
Concrete example: a PreToolUse hook that blocks any read inside build folders:
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "if": "Read(node_modules/*)",
            "command": "echo 'node_modules read blocked' >&2 && exit 2"
          }
        ]
      }
    ]
  }
}
Claude tries to read a file inside node_modules/? Blocked. It doesn't waste 2,000 tokens reading React's source code to understand a type. It uses the official docs or the exported type, full stop.

4. Ultra-targeted prompts

The way you phrase a request directly determines how many files Claude will explore. Vague prompt = broad exploration = wasted tokens. Targeted prompt = Claude reads what's needed, nothing more.
The way you phrase your request radically changes how many files Claude will explore. It sounds obvious, but it's the most immediate lever.
Instead of:
Look at my project and tell me if the Hero component is consistent.
Write:
Read only src/components/Landing/Hero.tsx and tell me if the pattern is consistent with the CLAUDE.md conventions.
In the first case, Claude explores the project structure, reads 5-10 files to "understand the context", then looks at Hero. In the second, it reads one file and responds. The difference: 3,000-5,000 tokens of exploration avoided.
Every file you reference explicitly is a file Claude doesn't need to search for.

5. The @ to point directly

In Claude Code, @file injects a file's content directly into the prompt context, without Claude needing to explore or search for it.
In Claude Code, you can use @file to inject a file into the prompt context. It's the ultimate shortcut: instead of letting Claude explore to find the right file, you hand it over directly.
@src/components/Landing/Hero.tsx refactor the useEffect to avoid the re-render
Claude receives the file content directly. No Glob, no Grep, no exploration. It codes immediately. Over a session of 20 iterations, that's hundreds of tokens saved per prompt.

Agentic mode: a factory, not a session

Interactive mode is a conversation. Agentic mode is an assembly line: multiple agents chaining together, delegating tasks, working in parallel. And a badly configured assembly line burns fuel continuously, even when it's producing nothing useful.
Three levers make all the difference here.

Limit the tools each agent can access

In .claude/agents/, each agent definition file exposes a permission field listing the tools it can access: read, write, bash, grep, glob, task...
An agent with access to everything will naturally explore more than a restricted one. A search agent doesn't need write. A writing agent doesn't need bash. The rule: give each agent the minimum viable set of tools for its task.
# .claude/agents/search.md
permission:
  read: allow
  grep: allow
  glob: allow
  # write: no. bash: no. task: no.
Fewer available tools = fewer possible exploration paths = fewer tokens consumed by default.

Skills: load business context on demand

Without Skills, business context (project conventions, writing guidelines, technical specs) is copy-pasted into each agent's system prompt — and loaded on every call, useful or not.
With a file in .claude/skills/, that context is only injected when the agent explicitly needs it. Over a workflow of 10 agentic calls, the difference is significant: you only pay for context when it actually serves a purpose.
Concrete example: my blog-writer.md skill contains 200 lines of writing guidelines. Without Skills, those 200 lines are in the context of every call. With them, they're only loaded when an agent is writing an article — not when it's doing a Tavily search or a code analysis.

Commands: pre-built prompts that avoid noise

A slash command in .claude/commands/ is an ultra-structured prompt with constraints already set, files already referenced, scope already defined. Versus a vague prompt typed by hand that will trigger 2-3 rounds of exploration before the agent understands what you want.
# .claude/commands/article-blog.md
Write an article following the blog-writer skill.
Read only: Blog-livate/content/Livate/Article de blog/en/[last article].mdx
Do not explore the rest of the folder.
The difference between /article-blog and "write me a blog article": the first starts with the right context and constraints already in place. The second explores, asks questions, reads files to understand the format. A few thousand tokens of difference, multiplied by every invocation.

The model for each agent: Haiku for simple tasks

Last lever, often forgotten: the model field in each agent. Haiku costs 25 times less than Opus for equivalent results on scan, grep, summary, or classification tasks. Reserve Sonnet and Opus for agents that actually do complex generation or architectural analysis.
# Tavily search agent → Haiku is more than enough
model: claude-haiku

# Technical implementation agent → Sonnet or Opus
model: claude-sonnet
It's one line in a YAML file. It's often the fastest optimization to put in place.
Have you ever measured your token consumption per session? Most devs don't — and that's exactly why the bill explodes without anyone knowing why. Drop a comment with your current setup, I'm curious to see what comes up most.

What I'm building

I'm packaging this entire setup: a CLAUDE.md template, the token-economy.md, base hooks, and targeted prompt examples. The idea is a public GitHub repo you can clone and adapt to your project in 10 minutes.
If that sounds useful, let me know in the comments or send me a signal on Twitter/X. If there's demand, I'll ship it next week.

FAQ — Optimizing Claude Code tokens

What's the difference between /compact and proactive rules?
/compact is reactive: it summarizes context once the window is full. Proactive rules (CLAUDE.md, hooks, rules files) prevent context from growing in the first place. One repairs, the other prevents.
Does CLAUDE.md have a size limit?
Yes. Anthropic recommends keeping it under ~500 lines. Beyond that, it weighs down the context of every session, including tasks that don't need it. The fix: move specialized instructions into Skills that load on demand.
Is Claude Haiku really 25x cheaper than Opus?
Yes, according to Anthropic's official pricing grid. For subagents doing simple tasks (grep, search, classification), Haiku is the right call. Save Sonnet or Opus for architecture decisions or complex code.
What's the real monthly cost of Claude Code?
According to Anthropic, the observed average is $100 to $200/dev/month with Claude Sonnet. 90% of users stay under $12/day. With the setup in this article, I've brought my consumption into the lower half of that range.
Do hooks slow down Claude Code?
Not perceptibly. A PreToolUse bash hook that filters a path executes in a few milliseconds. The token savings are incomparably larger than the added latency.

The real token economy is structural

I could have kept running /compact every 30 minutes. That's what I was doing. And it's what most devs do when they complain about their Claude Code bill. But /compact is just painkillers for your context. It relieves, it doesn't treat the cause.
The real optimization is preventing context from bloating in the first place. A CLAUDE.md that answers questions before they're asked. Rules that block useless reads. Hooks that intercept drift before it happens. Prompts that target exactly what needs to be read.
You set it up once, it runs on its own.
You don't fix a bloated context. You stop it from bloating.
Alex

Key takeaways

  • A CLAUDE.md loaded every session cuts 20-30% of tokens by eliminating repetitive context questions. It's the first investment to make.
  • A token-economy.md file in .claude/rules/ enforces automatic economy rules: Grep before Read, no recaps, no reading node_modules.
  • PreToolUse hooks automatically block reads in build folders (node_modules, .next, dist). Invisible guardrails.
  • A targeted prompt ('read only this file') saves 3,000-5,000 tokens compared to a vague one ('look at my project'). The @ injects the file directly.
  • In agentic mode: limit each agent's tools to the minimum viable set, load business context via on-demand Skills, and set Haiku for search agents. 25x cheaper than Opus on simple tasks.
  • /compact and /clear are reactive. The real token economy is structural: you stop context from bloating instead of fixing it after the fact.
← Back to articles

Related articles

Comments

Comments

Got a take on this article?

Create a free account in 10 seconds to comment, like, and get the next articles straight to your inbox.

Don't have an account yet?

This site uses cookies for analytics and advertising. No personal data is sold. Learn more