Project Budgets

Overview

Project budgets let you set spending limits for individual projects (by directory path) and get alerts when you approach or exceed them.

Why Project Budgets?

When you work on multiple projects with Claude Code, some projects consume significantly more tokens than others. Budgets help you:

• Control costs per project or client
• Identify expensive projects before they blow your budget
• Allocate resources by setting different limits for different projects
• Report to clients on AI-assisted development costs

Setting a Budget

Budgets are configured in the dashboard:

{
  "budgets": [
    {
      "project": "/home/user/work/project-alpha",
      "monthly_limit_usd": 50,
      "warn_at_percent": 80
    },
    {
      "project": "/home/user/personal/side-project",
      "monthly_limit_usd": 20,
      "warn_at_percent": 90
    }
  ]
}

Budget Dashboard

Progress Bars

Each project shows a progress bar with color coding:

project-alpha     ████████████████░░░░  $40 / $50  (80%)  ⚠️
side-project      ████░░░░░░░░░░░░░░░░   $4 / $20  (20%)
internal-tools    ██████████████████░░  $45 / $50  (90%)  🔴

Alerts

• Warning — triggered when usage reaches the warn_at_percent threshold
• Exceeded — triggered when usage exceeds the monthly limit
• Notifications — in-dashboard alerts, optional email notifications

Historical View

• Monthly budget utilization over time
• Which projects consistently exceed budgets
• Seasonal patterns in project spending

Cross-Machine Budgets

Budgets aggregate across all machines. If you work on project-alpha from both your work laptop and home desktop, all usage counts toward the same budget.

The project path is matched using the directory name (last component), not the full path. So /home/user/project-alpha and /Users/user/project-alpha are treated as the same project.