Try free

Last updated 13 October 2026

Set a budget for Claude Code sessions

The unexpected cost of agentic loops

When you start a session with the claude command, you initiate a series of API calls that can quickly escalate in cost. This happens because Claude Code is an agent that uses tools to interact with your local file system rather than just a simple chatbot. If you ask the agent to fix a complex bug, it might use the Glob tool to find relevant files, the Read tool to understand the code, and the Edit tool to apply changes. Each of these steps involves sending a prompt to the model and receiving a response. Because the model must see the context of your previous messages and the contents of the files it has read, every subsequent turn in the conversation becomes more expensive than the last.

A common scenario for high usage occurs when the agent enters a loop. This happens if the agent tries to fix a failing test but the fix introduces a new error. The agent then uses the Bash tool to run the test again, sees the failure, and attempts another Edit. Without a budget or manual intervention, this cycle can repeat many times. Every single one of those turns carries the weight of all the files currently in the context window. If you are not watching the terminal, you might only find out about the cost when you check your billing dashboard at the end of the day. Setting a budget is about preventing these runaway loops from draining your credits while you are focused on other tasks.

Monitoring live spend with internal commands

The first step in managing your budget is knowing exactly what you are spending in real time. Inside any active Claude Code session, you can use the /cost command to see the financial impact of the current conversation. This command provides a breakdown of the tokens used and the total dollar amount spent since you opened the terminal. It is a good habit to run this command after the agent completes a major task or if you notice the agent has been reading a large number of files. It gives you an immediate reality check on the price of the automation you are currently using.

For a broader view of your account, the /usage command shows your total consumption over time across all sessions. This is helpful if you are working on multiple features or projects and want to see how they add up. These commands do not require you to log into a web dashboard or leave your development environment. By keeping these figures in mind, you can decide when to use the /clear command to start fresh or when to use /compact to reduce the context window. Visibility is the most effective tool for preventing financial surprises in your development workflow.

Defining tool permissions in settings files

You can control costs by restricting which tools the agent can use without your explicit permission. Claude Code looks for settings in several places, including the .claude/settings.json file in your project root and the ~/.claude/settings.json file for global user preferences. Within these files, you can define the permissions for specific tools. For example, you might want to allow the Read and Glob tools to run automatically but require a manual check for the Edit or Bash tools. This ensures that the agent cannot make changes or run scripts that might lead to expensive recursive loops without you hitting a key to approve the action.

The permission modes can be toggled inside a session by pressing Shift plus Tab. This allows you to move between the default mode, the plan mode, and the bypassPermissions mode. In plan mode, the agent will describe what it intends to do and which tools it wants to use but will not actually execute them. This is a powerful budgeting technique because it lets you see if the agent is about to do something expensive, like reading an entire directory of data files, before the tokens are spent. By configuring your settings to default to a more restrictive permission level, you create a natural pause where you can evaluate the cost versus the benefit of the next step.

Managing context volume with compaction

The context window is the primary driver of cost in any Claude Code session. Every time the agent uses the Read tool on a source file, that file stays in the context for all future turns in that session. As the conversation grows longer, the input cost for every new prompt increases. To manage this, you can use the /compact command. This command summarizes the conversation so far, keeps the essential information, and removes the bulk of the previous exchanges and file contents from the active window. This significantly lowers the token count for the next prompt you send.

You can also use hook events to manage compaction automatically. For example, you can set up a PreCompact hook to trigger specific logic before the summary happens. If you find that a session has become too cluttered and expensive to continue, the /clear command is a more drastic option. It wipes the current conversation history while keeping you in the same directory. This is often better than continuing an old session if you have finished one task and are starting another. It ensures that you are not paying for the context of a bug fix that was completed an hour ago while you are now working on a new feature.

Centralizing control with adhdTerminal

When you are managing multiple projects, keeping track of every terminal window becomes a chore. adhdTerminal is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and is not affiliated with Anthropic. It runs many Claude Code sessions side by side, where each one is a tile on a wall. Each tile shows you at a glance whether the agent is working, waiting for your permission, or idle. This visual layout makes it much easier to spot a session that is stuck in a long running process or one that is consuming a lot of resources.

The app also includes a free iPhone app that mirrors your wall over an end to end encrypted link. This allows you to monitor your sessions even when you step away from your desk. If you notice a session is running longer than expected or is asking for permission for an expensive task, you can respond directly from your phone. This level of oversight is helpful for budgeting because it prevents sessions from sitting in an active state or performing tasks without your knowledge. It provides a high level view of your entire coding agent infrastructure in one place.

Restricting file access through project instructions

The agent consumes tokens every time it searches your directory. You can limit the scope of these searches by using the CLAUDE.md file. This file sits in your repo root and holds project instructions that the agent reads at the start of a session. By providing clear guidance on which directories are relevant and which should be ignored, you prevent the agent from using the Glob or Grep tools on irrelevant data. Even though the agent respects your .gitignore file, explicit instructions in CLAUDE.md provide a stronger guardrail against unnecessary file reads.

If you have a subdirectory that contains large logs, build artifacts, or documentation that the agent does not need to modify, you can place a separate CLAUDE.md file in that specific folder. This local file can contain instructions that apply only to that part of the tree. By narrowing the focus of the agent, you ensure that it only processes the files that are strictly necessary for the task at hand. Smaller search results and fewer file reads directly translate to a lower API bill and a faster response time from the agent.

Implementing custom alerts with hook events

Claude Code supports several hook events that allow you to run custom scripts at specific points in a session. These include SessionStart, PreToolUse, PostToolUse, and SessionEnd. While the command line tool does not have a native dollar limit flag, you can use these hooks to build your own monitoring system. For example, you could write a script that runs at the PostToolUse event to log the current cost to a local file. If the cost exceeds a certain amount, your script could trigger a notification or even stop the session.

The UserPromptSubmit hook is another useful point for budget control. You can use it to check the length of your prompt or the current state of the context before the data is sent to the API. This gives you a programmatic way to enforce rules that go beyond what is available in the standard settings.json file. Since these hooks are just shell commands or scripts that you define, they can be as simple or as complex as you need. This flexibility allows you to integrate Claude Code into your existing financial monitoring or time tracking tools.

Personal overrides and local settings

In a team environment, you might have a shared .claude/settings.json file that everyone uses. However, your individual budget or risk tolerance might be different from your colleagues. You can use the .claude/settings.local.json file to set your own untracked overrides. This file is ignored by git, so you can set more restrictive permissions or different hook scripts without affecting the rest of the team. This is the ideal place to put strict tool permissions if you are paying for your own API usage.

If you want to apply the same budget minded settings to every project you work on, use the ~/.claude/settings.json file in your home directory. Settings defined here serve as the baseline for every time you run the claude command. By setting up a global configuration that favors manual approval and frequent compaction, you protect yourself from accidental spend across all your repositories. You do not have to remember to configure a new project every time you start one. The global settings ensure that your preferred balance between automation and cost is always in place.

Questions people ask

How can I quickly stop a session that is spending too much?

You can press the Escape key once to interrupt whatever the agent is currently doing. If you need to exit the session entirely and return to your standard shell, press Ctrl plus C. To go back to a specific point in the conversation before the expensive operations started, you can press Escape twice to see a list of earlier messages and resume from one of them.

What is the difference between /clear and /compact for saving money?

/clear is more aggressive because it deletes the entire conversation history in the current folder, effectively starting your budget from zero for that session. /compact is a summary tool that reduces the size of the conversation but keeps the context of what has been done so far. Use /compact when you want to continue the current task with fewer tokens, and use /clear when you are finished with one task and starting something unrelated.

Does the agent cost money when it is just waiting for my input?

No, Claude Code only incurs costs when it sends data to the Anthropic API. This happens when you submit a prompt or when the agent uses a tool that requires a model response. While the session is idle and waiting for you to type, no tokens are being consumed. You can leave the terminal open without worrying about your budget until you hit Enter or approve a tool use.

Read next

More on claude code basics·All posts