Token Budgeting for Claude Code Projects (2026)

Without a token budget, Claude Code costs creep upward week over week. Developers discover new capabilities, sessions get longer, and by month two the bill is 3x what you planned. Token budgeting puts a ceiling on spend before it starts. This guide covers per-task limits, monthly projections, team budgets, and a ready-to-use CLAUDE.md budget template. Use the Token Estimator to calculate your baseline before setting limits.

Step 1: Establish Your Baseline

Before setting budgets, measure current usage for one week:

# Track daily token usage from the Anthropic console
# https://console.anthropic.com/settings/usage
# Or calculate from session summaries:
# Average session tokens x sessions per day x 5 work days
# Example baseline measurement:
# Monday:    8 sessions x 42,000 avg = 336,000 tokens
# Tuesday:   6 sessions x 55,000 avg = 330,000 tokens
# Wednesday: 9 sessions x 38,000 avg = 342,000 tokens
# Thursday:  7 sessions x 48,000 avg = 336,000 tokens
# Friday:    5 sessions x 35,000 avg = 175,000 tokens
# Weekly total: 1,519,000 tokens
# Daily average: 303,800 tokens

Step 2: Set Per-Task Token Limits

Different task types warrant different budgets. These limits prevent any single task from consuming a disproportionate share:

Task Type Token Budget Alert At Hard Stop
Quick fix / typo 15,000 10,000 20,000
Bug investigation 50,000 35,000 60,000
Feature implementation 80,000 60,000 100,000
Refactoring 100,000 75,000 120,000
Code review 30,000 25,000 40,000
Documentation 25,000 20,000 30,000

When you hit the alert threshold, consider whether the task is scoped correctly or if it should be split into smaller pieces.

Step 3: CLAUDE.md Budget Template

Add budget rules directly to your CLAUDE.md so Claude Code respects them every session:

## Token Budget Rules
### Session Limits
- Quick fixes: complete within 3 exchanges. If not resolved,
  ask me to provide more specific context.
- Feature work: maximum 8 exchanges per session. Use /compact
  after exchange 5 if continuing.
- Refactoring: split into files. One session per file group.
  Never refactor more than 5 files in one session.
### Context Efficiency
- Read only files I explicitly reference unless the task
  requires understanding imports/dependencies.
- Prefer Grep over reading entire files when searching.
- Do not read test files unless the task involves testing.
- Do not read configuration files unless the task involves
  configuration changes.
### Output Efficiency
- Keep explanations under 100 words unless I ask for detail.
- Show only changed code, not entire files.
- Skip preamble. Start with the solution.

Generate a full CLAUDE.md with budget rules using the CLAUDE.md Generator.

Step 4: Monthly Budget Projections

Convert your weekly baseline into monthly projections with a buffer:

# Monthly budget calculator
weekly_tokens = 1_519_000  # from baseline measurement
monthly_tokens = weekly_tokens * 4.3  # avg weeks per month
buffer = 1.2  # 20% buffer for spikes

budget_tokens = monthly_tokens * buffer
# 1,519,000 * 4.3 * 1.2 = 7,838,040 tokens/month

# Cost by model (input-heavy, 75/25 split)
def monthly_cost(budget, input_rate, output_rate):
    input_cost = (budget * 0.75 / 1_000_000) * input_rate
    output_cost = (budget * 0.25 / 1_000_000) * output_rate
    return input_cost + output_cost
haiku_cost = monthly_cost(budget_tokens, 0.25, 1.25)   # $1.47 + $2.45 = $3.92
sonnet_cost = monthly_cost(budget_tokens, 3.0, 15.0)    # $17.63 + $29.38 = $47.01
opus_cost = monthly_cost(budget_tokens, 15.0, 75.0)     # $88.18 + $146.96 = $235.14

print(f"Monthly budget: {budget_tokens:,.0f} tokens")
print(f"Haiku:  ${haiku_cost:.2f}/mo")
print(f"Sonnet: ${sonnet_cost:.2f}/mo")
print(f"Opus:   ${opus_cost:.2f}/mo")

Step 5: Team Budgets

For teams, allocate budgets by role and project:

# team-token-budget.yaml
monthly_budget_tokens: 50_000_000  # 50M tokens
model: sonnet
estimated_cost: $300/month
allocations:
  senior_devs:          # 3 developers
    per_person: 12_000_000
    total: 36_000_000
    notes: "Higher allocation for architecture + reviews"
  junior_devs:          # 2 developers
    per_person: 5_000_000
    total: 10_000_000
    notes: "Focused on implementation tasks"
  ci_cd:
    total: 4_000_000
    model: haiku         # cheaper model for CI
    notes: "Automated code review + test generation"
alerts:
  - threshold: 70%
    action: "Slack notification to #eng-costs"
  - threshold: 90%
    action: "Slack notification + manager email"
  - threshold: 100%
    action: "Disable non-essential CI tasks"

Setting Anthropic API Spend Limits

# Set organization-level spend limits in the Anthropic console
# https://console.anthropic.com/settings/limits
# Per-workspace limits:
# - Development workspace: $200/month
# - CI/CD workspace: $50/month
# - Staging/QA workspace: $30/month
# Per-API-key limits:
# Create separate API keys per developer or team
# Set individual key limits to prevent any single
# user from exhausting the team budget

Step 6: Monitor and Adjust

Review token usage weekly and adjust budgets monthly:

# Weekly review checklist:
# 1. Check total tokens vs budget (console dashboard)
# 2. Identify sessions that exceeded per-task limits
# 3. Review which task types consumed the most
# 4. Check if any developer exceeded their allocation
# Monthly adjustment triggers:
# - Consistently under 60% of budget: reduce by 15%
# - Hitting 90%+ regularly: investigate causes first
#   (scope creep? new use cases? inefficient prompts?)
# - New team member: add their allocation explicitly

The Cost Calculator helps convert raw token data from your monitoring into dollar amounts for budget tracking.

Budget-Aware Workflow

Integrate budgeting into your daily workflow:

# Before starting a task:
# 1. Estimate tokens with the Token Estimator
# 2. Choose the appropriate model for the task complexity
# 3. Set a mental exchange limit (3 for fixes, 8 for features)
# During the session:
# 4. Watch the token counter in the session footer
# 5. Run /compact after completing sub-tasks
# 6. If approaching your task limit, scope down or split
# After the session:
# 7. Note actual tokens vs estimate
# 8. Update your baseline data

Try It Yourself

The Token Estimator takes your project parameters – codebase size, team size, task mix, and model preference – and outputs a complete monthly budget with per-task limits. Start there to get a data-driven budget instead of guessing.

Frequently Asked Questions

What is a reasonable monthly token budget for a solo developer? A solo developer doing 6-10 Claude Code sessions per day on Sonnet typically uses 5-10 million tokens per month, costing $30-60. Set your initial budget at 10 million tokens with a $60 cap, then adjust after the first month based on actual usage. The Token Estimator can give you a more precise number based on your specific task mix.
Should I use the same model for all tasks to simplify budgeting? No. Using Sonnet for everything is simpler to track but costs more than necessary. Documentation and simple fixes work equally well on Haiku at 1/12th the price. A mixed-model strategy typically saves 25-35% versus Sonnet-only. Track usage per model in your budget spreadsheet. See the Cost Calculator for model-specific projections.
How do I handle budget overruns mid-month? First, check if the overrun is from legitimate new work or from inefficient usage. If legitimate, borrow from next month's buffer or request a budget increase with justification. If inefficient, implement the optimization techniques from the Best Practices guide -- typically .claudeignore and /compact recover 30-40% immediately.
Can I set hard token limits in Claude Code itself? Claude Code does not enforce hard per-session token limits directly. You can set API-level spend limits in the Anthropic console to cap total spend. For per-session control, add budget rules to your CLAUDE.md and monitor the token counter during sessions. The API key usage dashboard provides daily and monthly tracking.

Which model? → Take the 5-question quiz in our Model Selector.