# AI Coding Agent Token Budget: How to Set One

> A token budget for a coding agent is three caps: per task, per session, per month. Each one has a different enforcer, and only the provider limit is hard.

Source: https://tokenade.net/en/articles/ai-coding-agent-token-budget · Updated: 2026-10-20

You set a token budget for an AI coding agent in three layers: a cap per task, a ceiling per session, and a hard limit per month at the provider. Each layer has its own enforcer. The agent can stop a task, a meter can warn you mid-session, and only the provider can refuse to bill you past a number.

Most people only set the last one, if any, and find out what a session cost at the end of the month. A budget you only see in arrears is a receipt, not a budget. The useful version tells you while the agent is still running.

Flags, commands and console settings below were read in the official Claude Code, Claude Platform, OpenAI and ccusage docs on 2026-10-15. Running an agent unattended overnight is its own problem, with its own failure modes: that one is covered in [stopping an overnight agent from burning your budget](https://tokenade.net/en/articles/overnight-agent-budget-safety). This guide is about the everyday task and session.

## What should a token budget for an AI coding agent cap?

A token budget should cap three things, because they fail in three different ways:

| Layer | What it protects against | Who enforces it |
| --- | --- | --- |
| Per task | One job looping or wandering | The agent: `--max-budget-usd`, `--max-turns` |
| Per session | A transcript growing until every turn is expensive | You, with a meter: `/usage`, a status line |
| Per month | Everything else, including your own mistakes | The provider: spend limits and alerts |

The per-task cap is the precise one. The per-session cap is the one that saves the most money day to day, because cost per turn grows with the transcript. The monthly cap is the blunt one, and the only one an agent bug can't get around.

I budget in dollars rather than raw tokens. A token of cache read and a token of fresh output differ in price by a wide margin, so "500k tokens" says little about the bill. Every tool below reports an estimated dollar figure anyway.

## How big should the budget be?

Size the budget from a week of your own measured usage, not from a number you'd like to spend. Run your normal work for a few days, read the per-session figures, and set the per-task cap a little above what a typical task of that kind costs.

If you need a starting point before you have data, Anthropic publishes one for teams.

Its cost guide says that across enterprise deployments Claude Code averages around $13 per developer per active day and $150 to $250 per month, with 90% of users below $30 per active day ([Claude Code docs, Manage costs](https://code.claude.com/docs/en/costs), read 2026-10-15). That is an average over enterprise seats, not a target for a solo developer.

A practical rule I use:

1. **Per task:** about 1.5 times the median cost of similar past tasks. Tight enough to catch a loop, loose enough not to kill normal work.
2. **Per session:** a figure where you'd rather start a fresh session than keep going. For me that's when the context is mostly old file reads.
3. **Per month:** your real ceiling, the number at which you'd want traffic to stop.

How to get those past figures is covered in [how to measure agent token usage](https://tokenade.net/en/articles/measure-agent-token-usage).

## How do you limit Claude Code token usage per session?

In Claude Code, you limit a session two ways: hard caps for headless runs, and a live meter for interactive ones. The hard caps are flags on `claude -p`; there is no equivalent hard stop for an interactive session, so there you rely on what's on screen.

### Hard caps for headless tasks

Two flags cap a non-interactive run ([CLI reference](https://code.claude.com/docs/en/cli-reference), read 2026-10-15):

- `--max-budget-usd` stops the run once estimated API spend reaches the amount. Subagent spend counts toward it.
- `--max-turns` limits the number of agentic turns and exits with an error when it's reached. There is no limit by default.

Both are print mode only. A scripted task looks like this:

```bash
claude -p --max-turns 30 --max-budget-usd 3.00 "Fix the failing tests in src/auth"
```

Read the fine print before trusting the number. The docs say the cap is checked against Claude Code's client-side cost estimate, which can differ from your bill, and that spend can pass the cap.

In the Agent SDK, where the same controls exist as `maxTurns` and `maxBudgetUsd`, the docs explain why: the response that reaches the cap still completes ([agent loop docs](https://code.claude.com/docs/en/agent-sdk/agent-loop), read 2026-10-15). Leave headroom.

### A live meter for interactive sessions

Interactively, `/usage` is the reading to check. It shows the session's cost, plan usage limits and activity stats, and `/cost` is an alias for it ([commands reference](https://code.claude.com/docs/en/commands), read 2026-10-15). The dollar figure is computed locally from token counts at list price, so treat it as an estimate.

On Pro and Max, the docs note that the session cost figure isn't what you're billed. I still watch it: it's the most direct proxy for how hard a session is hitting your plan limits. The [Claude Code token limit](https://tokenade.net/en/articles/claude-code-token-limit) guide covers the 5-hour and weekly windows behind those limits.

Typing a command every few turns doesn't last. A status line does, because it's always visible. Claude Code passes it a JSON object that includes `cost.total_cost_usd` and `context_window.used_percentage` ([status line docs](https://code.claude.com/docs/en/statusline), read 2026-10-15). This script prints the session cost against a budget:

```bash
#!/bin/bash
# ~/.claude/statusline.sh: session cost against a $5 budget
BUDGET=5
input=$(cat)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
ctx=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
flag=$(awk -v c="$cost" -v b="$BUDGET" 'BEGIN { print (c >= b) ? "OVER BUDGET" : "ok" }')
printf '$%.2f / $%s · %s%% context · %s\n' "$cost" "$BUDGET" "$ctx" "$flag"
```

Then point your settings at it:

```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}
```

When the line says OVER BUDGET, I wrap up the subtask and run `/clear`. Since v2.1.211, the session totals reset on `/clear`, so the next session's cost starts at $0 ([Manage costs](https://code.claude.com/docs/en/costs)).

### Where hooks fit

Hooks can block a tool call: a `PreToolUse` hook can return a `permissionDecision` of `"deny"` ([hooks reference](https://code.claude.com/docs/en/hooks), read 2026-10-15). They don't receive a cost figure, though, only fields such as `transcript_path`. A hook-based budget means parsing the transcript yourself, and the docs warn that file can lag the current turn.

I don't build budgets on hooks. I use them to make each call cheaper, which [Claude Code hooks that cut tokens](https://tokenade.net/en/articles/claude-code-hooks) covers in detail.

> A budget holds longer when each turn is smaller: Tokenade cuts session cost by 39% on long sessions by trimming the file reads and command output Claude Code re-reads every turn.
>
> Install: `npm install -g @tokenade/cli && tokenade install` — or let your agent do it: https://tokenade.net/install.md

## How do you budget Codex and other agents?

Codex gives you a meter but, in the docs I read, no per-run spend cap. Its `/status` command displays session configuration and token usage, including remaining context, and `/usage` shows daily, weekly or cumulative account token activity ([Codex developer commands](https://learn.chatgpt.com/docs/developer-commands?surface=cli), read 2026-10-15).

So for Codex, the per-session budget is the same habit as interactive Claude Code: check `/status`, run `/compact` after long exchanges, start fresh at your threshold. The hard stop moves to the provider, covered next.

For the other agents, I didn't find a documented per-session spend flag I could verify, so I won't list one. The pattern stays the same: meter in the session, cap at the provider. ccusage reads local logs from many of them, as shown below.

## Where do you set a hard spend limit at the provider?

The provider's spend limit is the only budget an agent can't overrun by much, so set it before any other layer. Where it lives depends on how you pay.

**Claude Console (API key).** Claude Code usage is managed through workspaces, and the first time you authenticate with a Console account a workspace called "Claude Code" is created for you ([Manage costs](https://code.claude.com/docs/en/costs)).

In the Console's Workspaces page, select the workspace and open Spend limits to cap monthly spending and add alerts at thresholds ([workspaces docs](https://platform.claude.com/docs/en/manage-claude/workspaces), read 2026-10-15). The Rate limits page can also cap input and output tokens per minute for a workspace.

**Claude Pro or Max.** The plan's usage limits are the default ceiling. If you turn on usage credits to keep working past them, you can set a monthly spend limit for those credits, and `/usage` shows your month's spend against it ([Manage costs](https://code.claude.com/docs/en/costs)).

**Claude Team or Enterprise.** Each seat's allowance is the default ceiling. Admins can turn on usage credits and set spend limits at the organization, group or member level ([Manage costs](https://code.claude.com/docs/en/costs)).

**OpenAI API.** You can set a hard spend limit for the organization or for a single project. When tracked spend reaches it, requests return a `429` error with `organization_spend_limit_exceeded` or `project_spend_limit_exceeded` ([OpenAI spend limits](https://developers.openai.com/api/docs/guides/spend-limits), read 2026-10-15). OpenAI notes enforcement isn't instantaneous, so recorded spend can slightly exceed the limit.

Two habits make these limits useful rather than merely present:

- **Alerts below the cap.** An alert at 50% and 80% tells you the month is going badly while you can still change something.
- **A separate workspace or project for experiments.** A new agent setup gets its own small limit, so a bad week doesn't eat the budget for your real work.

## How do you monitor spend against the budget?

You monitor spend with a meter that reads what the agent already logged. ccusage is the standard choice: it reads local agent logs and reports daily, weekly, monthly and per-session usage, with estimated costs from model pricing ([ccusage guide](https://ccusage.com/guide/), read 2026-10-15).

```bash
npx ccusage@latest daily          # all sources it finds
npx ccusage@latest claude session # Claude Code, per session
npx ccusage@latest codex daily    # Codex only
```

For Claude Code, it also has a blocks view for the 5-hour billing window and a compact statusline mode ([ccusage, Claude Code data source](https://ccusage.com/guide/claude/), read 2026-10-15). If ccusage doesn't fit how you work, [ccusage alternatives](https://tokenade.net/en/comparisons/alternatives/ccusage-alternatives) compares the other options.

Review it once a week against the three caps. If tasks keep landing near the per-task cap, the cap is too tight or the tasks are too big. If sessions keep hitting the session ceiling, the problem is usually what's piling up in the context.

## How do you make the budget hold?

A budget holds when each turn costs less, not when you prompt less. An agent re-reads the whole transcript on every turn, so a large file read early in a session is paid for again on every turn after it. The cheapest token is the one that never enters the context.

The levers, in the order I'd apply them:

1. **One task, one session.** `/clear` between unrelated tasks. A fresh context has nothing old to re-read.
2. **Compact between subtasks, not at the warning.** `/compact` summarises earlier turns, so the next subtask starts from a smaller context.
3. **Filter command output.** A test run that dumps thousands of lines only needs the failing assertion.
4. **Search, don't read whole files.** Ask for the function, not the module.
5. **Use a smaller model where it's enough.** Anthropic's cost guide suggests `model: haiku` in the configuration of simple subagents.
6. **Disconnect MCP servers the task doesn't need.** Their tool definitions take up context on every turn.

The full list, with the mechanics behind each one, is in [how to reduce Claude Code token usage](https://tokenade.net/en/articles/reduce-claude-code-token-usage).

Applying all of that by hand, every session, is the part people drop under deadline. Tokenade automates it inside the agent: semantic search instead of whole-file reads, filtered command output, skeleton reads of large files, MCP output compaction. On the [THOL benchmark](https://tokenade.net/en/thol), it cuts session cost by 39% on long sessions ([methodology](https://tokenade.net/en/thol)). Compaction runs on the computer where you work, and Tokenade itself is free and open source (MIT/Apache-2.0), so it adds no line to the budget.

## What goes wrong (anti-patterns)

The usual failure is a budget that exists on paper and enforces nothing. Watch for these:

- **Only a monthly number.** You learn about a bad week at the end of the month. Add the session meter.
- **Trusting the cap to the cent.** `--max-budget-usd` and provider limits can both be passed slightly. Set them below what you can actually afford.
- **Budgeting in raw tokens.** Cache reads and fresh output tokens cost very different amounts. Use the dollar estimate.
- **Raising the cap instead of reading the session.** A task that keeps hitting its cap is usually stuck re-reading the same context. Look at `/context` before giving it more money.
- **One workspace for everything.** An experiment and your daily work then share one limit. Split them.

## FAQ

### Can I set a hard token limit on an interactive Claude Code session?

Not with a documented flag. `--max-budget-usd` and `--max-turns` only apply in print mode (`claude -p`). For interactive sessions, use `/usage` or a status line that shows `cost.total_cost_usd`, and start a fresh session when you reach your threshold. The provider's spend limit stays the hard stop.

### Does `--max-budget-usd` match my actual bill?

Not exactly. Claude Code checks the cap against its own client-side estimate at list price, which can differ from what you're billed, and the response that crosses the cap still completes. Leave headroom, and treat the Console's usage page as the authoritative figure.

### What happens when an OpenAI hard spend limit is reached?

Affected API requests return a `429` error with the code `organization_spend_limit_exceeded` or `project_spend_limit_exceeded`. Traffic resumes when you raise or remove the limit, or at the next monthly cycle. Enforcement isn't instantaneous, so spend can slightly exceed the limit.

### Is a token budget different for Pro or Max subscribers?

Yes. On Pro and Max, the plan's usage limits are your ceiling and the session dollar figure isn't what you're billed. The budget is about how fast you burn through the 5-hour and weekly windows. A monthly spend limit only matters if you turn on usage credits.

### How do I stop an agent from overspending overnight?

That case needs more than a session meter, because nobody is watching. The guide on [stopping an overnight agent from burning your budget](https://tokenade.net/en/articles/overnight-agent-budget-safety) covers it.

---

**See also:**
- [Stop an overnight AI agent burning your budget](https://tokenade.net/en/articles/overnight-agent-budget-safety): the unattended case.
- [Claude Code limits: how to stay under them](https://tokenade.net/en/articles/claude-code-token-limit): the 5-hour and weekly windows.
- [How to measure agent token usage](https://tokenade.net/en/articles/measure-agent-token-usage): the numbers your budget starts from.
- [ccusage alternatives](https://tokenade.net/en/comparisons/alternatives/ccusage-alternatives): other meters, and tools that lower the number.
- [How to reduce Claude Code token usage](https://tokenade.net/en/articles/reduce-claude-code-token-usage): every lever that makes a budget last.