How to run Claude Code cheaply on a big codebase
The bill on a busy AI coding setup is mostly search and checking, most of it the expensive model doing work a cheaper one could do. This is the structure that fixes it, with every file ready to copy. Cheap models for the bulk, the top model only where it is needed, wired once.
Open a usage report on a busy AI coding setup and the spend is spread across dozens of sessions. Almost all of it is the expensive model running search and checks a cheaper model does just as well. The fix is structure, cheap models for the bulk and the top model only where it is needed. This post has the exact files to copy.
Where the money actually goes
Open the usage report on a busy AI coding setup and the bill is a surprise. It comes from dozens of sessions. Most of it is the AI running lots of small helper tasks, called agents, all on the most expensive model, because no one told them to use a cheaper one. Long sessions and background jobs make up the rest.
Almost all of that spend is searching and checking, done on the most expensive model. The truly hard work is only a small part of the bill.
The setup below fixes it. Cheap models for the everyday work, the top model kept for the parts that need it, set up once so it stays that way. Here is the exact layout, with every file to copy.
Cost is structural
The bill comes down to how you set the tool up, not how carefully you use it from day to day. Fix the setup once and it stays cheap on its own.
There are three layers. Most people only use the first one.
| Layer | What it decides | Where it lives |
|---|---|---|
| Agents | Who does the work, meaning the model, the role, and the rules | One file per agent type |
| Workflows | How the work is ordered, the scout, generate, and check stages | A workflow script |
| Skills | The trigger and the recipe together, one command per job | A file behind a slash command |
Your main chat stays on the top model and does the thinking. Any task it can pass to a helper becomes an agent, and you pick which model that agent uses. If you don't pick, the agent just uses the same top model your chat is on. When a job spins up lots of agents, your most expensive model runs over and over for work a cheaper one could do just as well.
What it looks like on disk
On disk it is a handful of small files in a folder called .claude, plus one file (CLAUDE.md) in the top folder of your repo. That is the whole setup.
Each file has one job. The agents set who runs the work and on which model. The workflow sets the order. The skill is the command you type. CLAUDE.md holds the rules the tool must not break. The rest of this post is those files, ready to copy.
Every file below is set up in a real full-stack project you can clone and read. See it on GitHub, in the .claude/ folder and CLAUDE.md at the project root.
The biggest lever is model tiering
Start with the agents, because picking the right model for each job saves the most. The rule is simple. Use a cheap model for searching and checking. Use the top model only for writing new code.
Match the model to the job.
| Model tier | Use it for | Why |
|---|---|---|
| Cheapest | File search, finding where something is defined, pattern sweeps across the repo | Finding a line of code needs no reasoning, so do not pay for reasoning |
| Mid | Research, mechanical rollouts, verification, code review | Strong enough for structured work that follows a checklist |
| Top | Novel generation, hard architecture, the subtle bugs | The extra capability only shows up on open-ended work |
You set this for each agent, in one small file. The few lines at the top, called the frontmatter, pick the model. Here is the search agent. It uses a small model and only reads code, it never changes it.
And here is the agent for the hard work of writing code, set to the top model. This is the one you call by name every time, so your important work never runs on a weaker model by accident.
This is the trap to watch for. Each agent has a name. The one above is called author, and it uses the top model. When you hand off a task, you pick the agent by that name. If you don't name one, Claude Code uses a default agent, which may be set to a cheaper model. So if you give it your hardest task and forget to ask for author, the work quietly runs on the cheaper model. Nothing warns you. The answer is just weaker than it should be, and you won't see why.
Set a fixed model for each agent, and get in the habit of naming the agent when you hand off work. Cheap model for searching, top model for writing code. That is the rule.
Generate, then verify
Instead of one big prompt, break the work into three small steps.
- Scout: Finds the right files and the code to copy from. The scout uses a cheap model and only reads.
- Generate: Writes the change. Generate is the only step that runs on the top model.
- Verify: One or more cheaper agents check the work at once. Verify runs on a cheap model too.
So the whole job is mostly cheap. Only the middle step uses the pricey model. The steps before and after are cheap. Write these steps down in a workflow file, so the tool runs them in the same order and on the same models every time, instead of deciding again on each run.
The check works best when the second agent's job is to prove the first one wrong. Tell it to hunt for the mistake, not to approve the work. Left alone, the tool will happily ship code that looks fine and is broken. An agent that is trying to break it finds that. For anything going live, it often catches a real bug on the first try, and it barely costs anything.
Make the right lane the default
Rules you have to remember are rules you skip when you're tired. So don't remember them. Put them in a command.
A skill is a small file that saves a set of steps behind one command. When you run it, it opens the right notes, starts the right agent or workflow, and follows your steps. Now the model choices happen on their own. Instead of remembering to open the doc, start the right agent, and run the check, you type one command and the skill does all of it.
Keep skills short. Have them point to your real notes instead of copying the rules inside. When you update a note, the skill uses the new version right away. The skill runs the steps. The notes hold the details.
You run a skill by typing its name with a slash. The file above runs as /preship. Claude Code ships built-in ones too, like /code-review and /security-review.
If you do something the same way more than a few times a week, make it a skill. A pre-ship review is a skill. A make-a-new-thing recipe is a skill.
The rules the tool must not break
On a live codebase, you want the risky commands blocked. Write the rules in a file called CLAUDE.md in the top folder of your repo. The tool reads it at the start of every session and follows it.
On an existing project you do not have to start from a blank file. Run /init and Claude Code reads your codebase and writes a starter CLAUDE.md for you. Then add your hard rules, like the ones below, and change them for your project.
Those four questions matter the most. They stop the tool from making extra changes you never asked for, like tidying up code while it is in there for something else.
Back the rules with permissions
CLAUDE.md is written rules the model reads and tries to follow. On a real app you want a stronger guard, one the tool enforces even if it skips the written rules. That is what permissions in settings.json give you.
A deny rule blocks a command completely. An allow rule lets a safe command run without asking you first, so you stop approving the same harmless git status check over and over. If a command is in both lists, deny wins, so you can make the deny list as broad as you like.
Commit this file so everyone on the team gets the same rules. Your own personal tweaks go in a second file next to it, settings.local.json, which git ignores so it is never shared. Now you have two layers of safety, the written rules in CLAUDE.md and the enforced rules here.
Automate the checks with hooks
A hook is a command the tool runs automatically when something happens, so a check runs every time even if you forget it. Two hooks are worth adding to almost any project.
- Format on edit: Runs your code formatter on a file right after it is edited, so the spacing and style stay tidy without you doing it by hand.
- Block protected files: Stops changes to files the tool should never touch, like your secrets and your local database.
Hooks go in the same settings.json file, grouped by when they run. A PostToolUse hook runs just after an edit. A PreToolUse hook runs just before one, and it can stop the edit.
The tool sends the details of the edit to your script as JSON. The script reads the file path and decides what to do. If a PreToolUse hook exits with code 2, the tool cancels the edit, and whatever the script prints is shown to the model as the reason.
The model can skip a written rule. It cannot skip a denied permission or a blocking hook. For the rules that really matter, use all three, the written rule, the permission, and a hook.
Keep CLAUDE.md small
CLAUDE.md loads at the start of every session, so every line in it costs you a little on every message. On a big app it is tempting to put everything in it, the testing guide, the deploy steps, the style rules. All of that makes each session bigger and slower.
Keep CLAUDE.md to the rules that are always true. Move the rest into small notes in a docs folder, and link to them. Then the tool opens a note only when the task needs it.
The task decides what gets loaded. A change to the tests opens the testing note and nothing else. The rules that load every time stay short, so every session stays cheap.
Memory, so clearing context is safe
Long sessions cost more than short ones, because every message sends the whole conversation again. So the cheap habit is to clear the chat often. That only works if clearing it loses nothing, and that is what a memory folder is for.
Keep a memory folder of small files, one fact in each file. Add an index file that the tool reads at the start of every session. Each fact is a short note with a one-line summary the tool can skim to see if it matters right now. Save the things the code itself cannot tell you later.
- Decisions: Why the setup is the way it is. Why search runs on a cheap model, why one endpoint is not cached.
- Gotchas: The trap you already hit once. The file that breaks if you rename it, the migration you must not reuse.
- State: What is shipped and what is only staged, so a fresh session knows where the work stands.
Skip anything the repo already records. The code layout, the git history, and the CLAUDE.md rules are already saved, so a memory file that repeats them just adds clutter. One fact per file looks like this.
The index is one line per fact, so the tool starts each session knowing what exists without loading every file.
With the memory in place, clear the chat every time you switch tasks. The important notes are saved in files, so a fresh start reads the index and picks up where you left off. You stop paying to carry an old task around, and you lose nothing.
Keep sessions short
Once the setup is in place, a few habits keep the day-to-day cost down. They all come down to one thing. A shorter conversation is a cheaper one.
- Clear when you switch tasks: A new task deserves a fresh start, so type /clear. Carrying the old chat along keeps paying for words you no longer need. With the memory folder, clearing loses nothing.
- Compact a long task: When one task gets very long, type /compact. The tool sums up what has happened so far and carries on with a shorter version.
- Watch background and loop sessions: Anything running in the background or on a loop keeps billing the whole time it runs. They are useful, so check each one is still meant to be on.
One thing does not save money, fast mode. It only makes the answers appear quicker. It uses the same model, so the price is the same. Use it if you like the speed, and rely on the habits above for the real saving.
How a change ships
With the pieces in place, every change follows the same five steps. This is what turns the setup into a habit.
- Plan first: For anything bigger than a quick fix, plan before changing files. In plan mode the tool reads and looks around, but does not edit until you approve the plan. A wrong turn then costs a paragraph, not a rewrite.
- Build with the right agent: Write the change with your top-model agent, or run the scout-generate-verify workflow. Name the agent so the work does not slip onto a cheaper model.
- Check that it runs: Open the feature and watch it work. A passing test does not prove the change does what you meant. Run the real thing.
- Review the change: Run a code review over it, and a security review for anything that touches logins, user input, or data. A cheap reviewer here catches what a tired author misses.
- Ship through the gate: Run the pre-ship check, then commit. It is the last cheap check before the change goes out.
None of these steps costs much. Plan, check, and review all run on cheap or mid models. Only the build uses the top model, and that is exactly where it belongs.
Running it on a real task
Those five steps look like this on a real change, adding a small /health endpoint that returns ok. Each line starting with an arrow is what you type in Claude Code. The line under it is what happens.
The shape stays the same every time. You plan on a cheap model, build once on the top model, then check and ship with cheap ones. When the task is done, type /clear and start the next one fresh.
The proof
Run the pre-ship check on a real change and it holds up. Two mid-model reviewers pull up the change on their own, each look at it separately, and come back with a clear yes or no on shipping. It costs about a tenth of the same review on the top model.
A cheap search and a cheap check wrapped around one expensive build step, behind a command that makes the cheap path the default. The work did not get worse. The bill did.
The commands you will type
A handful of these come up all day. You run any skill by typing its name with a slash, so your own pre-ship gate is just /preship. The rest are built in.
- /clear: Start a fresh chat when you switch tasks.
- /compact: Shrink a long chat and keep going.
- /preship: Run your own pre-ship skill. Any skill runs as a slash command with its name.
- /code-review: A built-in review of the changes you have made.
- /security-review: A built-in security check of your changes.
- /cost: See what the current session has cost so far.
- /init: Scan an existing project and write a starter CLAUDE.md. A one-time setup step.
Type a slash in Claude Code and it lists every command and skill available, so you can see what your project has without leaving the chat.
Set it up once
Every session after runs cheaper. Here is the whole setup in two short lists.
Do these once
- One agent file per type, model pinned by the job.
- A cheap search agent, a mid general-purpose agent, and top-model agents for your hardest work.
- A CLAUDE.md with your hard rules, kept small and pointing to docs for the rest.
- A settings.json with deny rules for the dangerous operations and allow rules for the safe ones.
- A format hook and a hook that blocks writes to secrets and local data.
- A scout-generate-verify workflow for your main authoring task.
- Skills for your top few recipes and your pre-ship gate.
- A memory folder and index so clearing context is safe.
- settings.local.json in your gitignore, settings.json committed.
Do these every session
- Clear on a task switch, compact once a single task gets large.
- Name the agent type when you delegate real work, never a bare general-purpose.
- Plan first for anything non-trivial, then build.
- Fire independent searches and reads in parallel.
- Verify the change runs, review the diff, then run the pre-ship gate before you ship.
- Check that any background or loop session is still meant to be running.
The habits take a day to learn. The setup takes an hour. After that the cost drops on every session, and you do not think about it again.