feat: Add cost tracking and budget management for AI API usage

[mensfeld]

Overview

Add cost tracking and budget management for AI API usage. Monitor spending per session, project, and time period. Set budgets and alerts to prevent unexpected costs. Useful for both pay-per-token APIs (Anthropic, OpenAI) and understanding usage patterns on subscription plans.

Motivation

Current Problem:

• No visibility into AI API costs
• Can't track which projects/sessions are expensive
• Risk of runaway costs if AI goes rogue
• Can't set spending limits
• Difficult to budget for AI coding assistance

With Cost Tracking:

coi cost report

# Output:
Total this month: $127.50
  - project-a: $82.50 (65%)
  - project-b: $45.00 (35%)

Most expensive sessions:
  - session-abc: $12.50 (850K tokens)
  - session-def: $8.75 (620K tokens)

Current budget: $200/month
Remaining: $72.50 (36%)

Use Cases

1. Monthly Cost Reporting

# See total spending
coi cost report

# By project
coi cost report --by-project

# By date range
coi cost report --from 2024-02-01 --to 2024-02-28

# Export for accounting
coi cost report --format csv > february-ai-costs.csv

2. Budget Management

# Set monthly budget
coi cost budget --monthly 200.00

# Set daily budget
coi cost budget --daily 10.00

# Set per-project budget
coi cost budget --project backend-api --monthly 50.00

# Alert at threshold
coi cost alert --threshold 80%  # Alert at 80% of budget

3. Real-Time Monitoring

# Monitor costs during session
coi shell --show-cost

# In the session:
[Session cost: $0.45 | 32K tokens | Budget: 85% remaining]

4. Cost Optimization

# Find expensive sessions
coi cost top --limit 10

# See cost trends
coi cost trends --last-30-days

# Compare projects
coi cost compare project-a project-b

Proposed Implementation

Data Storage

Store cost data in SQLite database:

-- ~/.coi/costs.db

CREATE TABLE sessions (
    session_id TEXT PRIMARY KEY,
    workspace TEXT,
    start_time TIMESTAMP,
    end_time TIMESTAMP,
    total_tokens INTEGER,
    prompt_tokens INTEGER,
    completion_tokens INTEGER,
    estimated_cost REAL,
    model TEXT
);

CREATE TABLE api_calls (
    id INTEGER PRIMARY KEY,
    session_id TEXT,
    timestamp TIMESTAMP,
    tokens INTEGER,
    estimated_cost REAL,
    model TEXT,
    FOREIGN KEY(session_id) REFERENCES sessions(session_id)
);

CREATE TABLE budgets (
    id INTEGER PRIMARY KEY,
    scope TEXT,  -- 'global', 'daily', 'monthly', 'project'
    scope_value TEXT,  -- project name if scope='project'
    limit_amount REAL,
    alert_threshold REAL  -- Alert at X% of limit
);

Cost Calculation

Different pricing models:

// Pricing models
var pricingModels = map[string]PricingModel{
    "claude-opus-4": {
        PromptTokenPrice:      0.000015,  // $15 per 1M tokens
        CompletionTokenPrice:  0.000075,  // $75 per 1M tokens
    },
    "claude-sonnet-4": {
        PromptTokenPrice:      0.000003,  // $3 per 1M tokens
        CompletionTokenPrice:  0.000015,  // $15 per 1M tokens
    },
    "claude-haiku-4": {
        PromptTokenPrice:      0.0000008, // $0.80 per 1M tokens
        CompletionTokenPrice:  0.000004,  // $4 per 1M tokens
    },
}

func calculateCost(model string, promptTokens, completionTokens int) float64 {
    pricing := pricingModels[model]
    
    promptCost := float64(promptTokens) * pricing.PromptTokenPrice
    completionCost := float64(completionTokens) * pricing.CompletionTokenPrice
    
    return promptCost + completionCost
}

Token Tracking

Integrate with AI tool to track token usage:

// Hook into Claude Code's usage tracking
func trackUsage(sessionID string) {
    // Read Claude's usage stats
    stats := readClaudeUsageStats()
    
    // Calculate cost
    cost := calculateCost(
        stats.Model,
        stats.PromptTokens,
        stats.CompletionTokens,
    )
    
    // Store in database
    storeSessionCost(sessionID, cost, stats)
}

For Subscription Plans

# Track quota usage instead of cost
coi quota report

# Output:
Daily quota (Claude Pro): 850K tokens used / unlimited
Usage breakdown:
  - project-a: 620K tokens (73%)
  - project-b: 230K tokens (27%)

Message limit: 45 / 300 messages used today

Command-Line Interface

Cost Reporting

# Basic cost report
coi cost report

# Detailed report
coi cost report --detailed

# By time period
coi cost report --today
coi cost report --yesterday
coi cost report --this-week
coi cost report --this-month
coi cost report --last-30-days
coi cost report --from 2024-02-01 --to 2024-02-28

# By scope
coi cost report --by-project
coi cost report --by-session
coi cost report --by-model

# Output formats
coi cost report --format table    # Default
coi cost report --format json
coi cost report --format csv
coi cost report --format summary  # Just totals

Budget Management

# Set budgets
coi cost budget set --daily 10.00
coi cost budget set --monthly 200.00
coi cost budget set --project backend-api --monthly 50.00

# View budgets
coi cost budget list

# Remove budget
coi cost budget remove --monthly

# Set alerts
coi cost alert set --threshold 80%     # Alert at 80%
coi cost alert set --amount 150.00     # Alert at $150
coi cost alert set --webhook https://hooks.slack.com/...

Top Sessions/Projects

# Most expensive sessions
coi cost top --sessions --limit 10

# Most expensive projects
coi cost top --projects --limit 5

# Show details
coi cost top --sessions --limit 10 --show-details

Trends & Analysis

# Cost trends
coi cost trends --last-30-days

# Usage patterns
coi cost analyze --by-hour    # Peak usage hours
coi cost analyze --by-day     # Peak usage days
coi cost analyze --by-model   # Model usage breakdown

# Projections
coi cost forecast --next-month

Example Output

Basic Report

Cost Report - February 2024
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

SUMMARY
  Total Cost:        $127.50
  Total Tokens:      8,500,000
  Sessions:          24
  Average per session: $5.31

BY PROJECT
  backend-api        $82.50 (65%)  5.5M tokens
  frontend           $45.00 (35%)  3.0M tokens

BY MODEL
  claude-sonnet-4    $95.25 (75%)  6.8M tokens
  claude-opus-4      $32.25 (25%)  1.7M tokens

BUDGET STATUS
  Monthly Budget:    $200.00
  Used:              $127.50 (64%)
  Remaining:         $72.50 (36%)
  Days Remaining:    8
  Projected Total:   $169.17 (within budget)

TOP SESSIONS
  1. session-abc123  $12.50  850K tokens  backend-api
  2. session-def456  $8.75   620K tokens  frontend
  3. session-ghi789  $7.25   485K tokens  backend-api

Detailed Session Report

coi cost report --session session-abc123

Session: session-abc123
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Project:    backend-api
Started:    2024-02-15 14:32:15
Duration:   1h 23m
Model:      claude-sonnet-4

TOKEN USAGE
  Input:     620,000 tokens  ($1.86)
  Output:    230,000 tokens  ($3.45)
  Total:     850,000 tokens  ($5.31)

API CALLS
  Total calls: 42
  Average tokens/call: 20,238
  Average cost/call: $0.13

COST BREAKDOWN
  Prompt tokens:      $1.86 (35%)
  Completion tokens:  $3.45 (65%)
  Total:              $5.31

EFFICIENCY
  Tokens per minute:  10,241
  Cost per minute:    $0.06

Budget Alert

⚠️  BUDGET ALERT

You have used 80% of your monthly budget.

Budget:      $200.00
Used:        $160.00 (80%)
Remaining:   $40.00
Days left:   12

At current rate: $6.67/day
Projected total: $200.04 (budget exceeded by $0.04)

Recommendations:
  - Reduce usage by 10% to stay within budget
  - Consider using claude-haiku-4 for simple tasks
  - Review expensive sessions: coi cost top --sessions

Implementation Phases

Phase 1: Basic Cost Tracking

• SQLite database for cost storage
• Token usage tracking from Claude Code
• Cost calculation for Anthropic models
• coi cost report command (basic)
• Store session costs in metadata

Phase 2: Budget Management

• Budget configuration (daily, monthly, per-project)
• Budget checking before session start
• coi cost budget commands
• Alert when approaching budget limit
• Budget enforcement (block if exceeded)

Phase 3: Enhanced Reporting

• Detailed session reports
• Cost breakdown by project, model, time period
• Top sessions/projects
• Export to CSV/JSON
• Cost trends and charts (terminal graphs)

Phase 4: Real-Time Monitoring

• Show current session cost in prompt
• Live cost updates during session
• Integration with coi monitor (feat: Add container monitoring and observability (coi monitor) #112)
• Cost-per-minute tracking

Phase 5: Advanced Features

• Cost forecasting
• Usage pattern analysis
• Recommendations for cost optimization
• Multi-user cost attribution
• Integration with accounting systems
• Webhook notifications (Slack, email)

Integration Points

Claude Code Integration

Track usage from Claude's settings/logs:

// Read from ~/.claude/usage.json (if it exists)
func readClaudeUsage() (*UsageStats, error) {
    // Or parse from Claude logs
    // Or use Claude API usage endpoint
}

Session Metadata

Store cost in session metadata:

{
  "session_id": "abc123",
  "workspace": "/path/to/project",
  "cost": {
    "total": 5.31,
    "tokens": 850000,
    "model": "claude-sonnet-4",
    "api_calls": 42
  }
}

Budget Enforcement

coi shell

# Before starting:
Checking budget...
Monthly budget: $200.00
Used: $185.00 (93%)
Remaining: $15.00

⚠️  WARNING: Only $15.00 remaining in monthly budget
Continue? [y/N]

Configuration

# ~/.config/coi/config.toml

[cost]
enabled = true
database = "~/.coi/costs.db"

[cost.budget]
daily = 10.00
monthly = 200.00

[cost.budget.projects.backend-api]
monthly = 50.00

[cost.alert]
threshold = 80  # Alert at 80% of budget
webhook = "https://hooks.slack.com/..."
email = "team@company.com"

[cost.pricing]
# Override default pricing if needed
claude-sonnet-4-input = 0.000003
claude-sonnet-4-output = 0.000015

Subscription Plan Support

For Claude Pro/Max (subscription plans):

# Track quota usage instead of cost
coi quota report

# Output:
Claude Pro Subscription
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Daily Usage:
  Messages: 45 / 300 (15%)
  Time until reset: 8h 23m

Projects:
  backend-api: 28 messages (62%)
  frontend:    17 messages (38%)

Top Sessions Today:
  1. session-abc: 8 messages
  2. session-def: 6 messages
  3. session-ghi: 5 messages

Recommendation: You have 255 messages remaining today

Benefits

Cost Control:

• Set and enforce budgets
• Prevent surprise bills
• Alert before exceeding limits

Visibility:

• Know exactly what you're spending
• Identify expensive projects/sessions
• Understand usage patterns

Optimization:

• Find opportunities to reduce costs
• Choose appropriate models for tasks
• Optimize prompts and workflows

Accountability:

• Track costs per project
• Bill clients/departments accurately
• Justify AI tooling investments

Technical Considerations

Token Counting

Different approaches:

1. Parse from Claude Code logs/output
2. Hook into Claude API responses
3. Use tiktoken library for estimation
4. Read from Claude's usage tracking (if available)

Pricing Updates

Prices change over time:

• Store pricing in configuration
• Allow manual overrides
• Fetch pricing from API (if available)
• Version pricing data

Multi-User Environments

For teams:

• Track costs per user
• Aggregate team costs
• User-specific budgets
• Cost center attribution

Accuracy

Cost tracking is estimated:

• API may round or batch requests
• Caching affects actual costs
• Actual bills may differ slightly

Add disclaimer:

Note: Costs are estimated based on token usage.
Actual charges may vary. Verify with your API provider.

Related Issues

• Monitoring (feat: Add container monitoring and observability (coi monitor) #112) - Real-time session monitoring
• Profiles (feat: Add AI agent profiles for pre-configured environments #114) - Different profiles may have different cost characteristics
• Session management - Track costs per session

Open Questions

1. Should we block sessions if budget exceeded?

   • Proposal: Warning by default, configurable blocking

2. How to handle multiple AI providers (OpenAI, Anthropic, etc.)?

   • Proposal: Pluggable pricing models, auto-detect from API key

3. Should we track non-API costs (compute, storage)?

   • Proposal: Phase 2 feature, optional

4. How to handle free tier / credits?

   • Proposal: Track usage separately, mark as "free tier"

References

• Anthropic Pricing
• OpenAI Pricing
• Token counting with tiktoken

[mensfeld]

Yeah please do. The more info the marrier. I should revisit cost trakcing in the upcoming weeks once the monitoring/security capabilities are stable.

[m13v]

we implemented per-session cost tracking for our AI agent and the key insight was tracking the delta per query rather than cumulative totals. the Claude API returns cumulative session costs but you want per-prompt costs for budgeting. subtract the previous cumulative from the current one after each API call. for budget alerts, we check after each query and stop the agent if it exceeds the session budget - better to stop mid-task than blow through a budget on a runaway agent loop.

[m13v]

here's our cost tracking implementation in the Claude API provider: https://github.com/m13v/fazm/blob/main/Desktop/Sources/Providers/ChatProvider.swift - the delta calculation that gives per-prompt costs from cumulative API responses. and the scheduled agent system where budget limits prevent runaway costs: https://github.com/m13v/tmux-background-agents/blob/main/SKILL.md