Cost Tracking - Mission Control

Overview

The Token & Cost Dashboard provides comprehensive visibility into LLM usage across your agent fleet. Track token consumption, calculate costs, identify optimization opportunities, and export data for analysis.

Cost tracking requires agents to report token usage via the heartbeat API or gateway WebSocket events.

Accessing the Dashboard

Navigate to Tokens

Click Tokens in the left navigation rail.

Select Timeframe

Choose Hour, Day (default), Week, or Month in the header.

View Statistics

Dashboard loads usage stats, trends, and cost breakdowns for the selected period.

Timeframe Selection

Four timeframes available:

Hour
Day
Week
Month

Last 60 minutes of usage. Best for real-time monitoring during active development.

Overview Statistics

Four primary metrics displayed in the header cards:

Total Tokens

Aggregate token count (input + output) for the selected timeframe. Formatted with K/M suffixes (e.g., “2.5M”).

Total Cost

Estimated cost in USD based on model pricing. Precision to 4 decimal places (e.g., “$12.3456”).

API Requests

Number of LLM API calls made during the period.

Avg Tokens/Request

Mean tokens per request. Useful for identifying verbose prompts.

Usage Trends Chart

A 24-hour line chart showing:

Tokens (blue line) — Token consumption over time
Requests (green line) — Request volume over time

Chart Features

Responsive design (resizes with window)
Hover tooltips with exact values
Cartesian grid for easy reading
Time-based X-axis (2-minute intervals)
Formatted Y-axis (K/M suffixes)

Empty State

If no trend data exists for the timeframe, the chart shows: “No trend data for this timeframe”

Model Usage Breakdown

Token Usage by Model (Bar Chart)

Bar chart ranking models by total token consumption:

X-axis — Model names (rotated 45° for readability)
Y-axis — Total tokens (formatted)
Sorted — Descending by cost (most expensive first)

Cost Distribution (Pie Chart)

Donut chart showing cost share by model:

Top 6 models displayed (others grouped if > 6)
Color-coded segments
Hover tooltips with exact cost
Legend with model names

Model names are normalized for display. For example, anthropic/claude-sonnet-4-20250514 becomes sonnet-4.

Performance Insights

The insights panel highlights optimization opportunities:

Metrics Cards

Most Efficient Model

Model with the lowest cost per 1K tokens. Displays rate in dollars per thousand tokens.

Most Used Model

Model with the highest request count. Shows total requests.

Optimization Potential

Potential savings if all requests used the most efficient model. Shows amount and percentage.

Model Efficiency Comparison

Horizontal bar chart comparing efficiency across all models:

Bar width — Relative efficiency (longer = more efficient)
Cost rate — Dollars per 1K tokens (displayed on right)
Green bars — All models use green for consistency

Efficiency Calculation

efficiency = 1 / (cost_per_token * 1000)
bar_width = (efficiency / max_efficiency) * 100%

Higher values mean lower cost per token (better efficiency).

Alerts & Suggestions

Automated alerts appear when thresholds are exceeded:

Alert Types

High Usage Cost
Optimization Opportunity
High Request Volume

Triggered when total cost > $100 in the selected timeframe.Message: “Total cost of

XXX exceeds

100 threshold”Suggestion: “Consider using more cost-effective models for routine tasks”

Alert Styling

⚠️ Warning — Yellow border and background
ℹ️ Info — Blue border and background

Detailed Statistics

Model Performance Table

Scrollable list of all models with:

Model name (normalized)
Total cost (USD)
Total tokens
Request count
Avg cost per request
Avg tokens per request

Top Sessions by Cost

Scrollable list of top 10 sessions with:

Session ID or key
Active status (Active/Inactive)
Total cost
Total tokens
Request count
Avg cost per request

Sessions linked to agents show the agent name. Orphaned sessions show the raw session ID.

Data Export

Export usage data for external analysis:

Export Formats

CSV
JSON

Comma-separated values for spreadsheet analysis.Includes:

Timestamp
Model
Session ID
Input tokens
Output tokens
Total tokens
Cost

Exporting Data

Select Timeframe

Choose the time period to export (Hour/Day/Week/Month).

Click Export

Click Export CSV or Export JSON in the Export Data panel.

Download File

File downloads automatically with filename format: token-usage-{timeframe}-{date}.{format}

Example Export Filenames

token-usage-day-2026-03-04.csv
token-usage-week-2026-03-04.json
token-usage-month-2026-03-04.csv

Token Usage API

Query token data programmatically:

Get Usage Stats

curl "http://localhost:3000/api/tokens?action=stats&timeframe=day" \
  -H "x-api-key: your-api-key"

Response:

{
  "summary": {
    "totalTokens": 2500000,
    "totalCost": 12.3456,
    "requestCount": 847,
    "avgTokensPerRequest": 2951,
    "avgCostPerRequest": 0.0146
  },
  "models": {
    "claude-sonnet-4": {
      "totalTokens": 1800000,
      "totalCost": 9.0000,
      "requestCount": 650
    },
    "gpt-4o": {
      "totalTokens": 700000,
      "totalCost": 3.3456,
      "requestCount": 197
    }
  },
  "sessions": { ... },
  "timeframe": "day",
  "recordCount": 847
}

Get Trend Data

curl "http://localhost:3000/api/tokens?action=trends&timeframe=day" \
  -H "x-api-key: your-api-key"

Response:

{
  "trends": [
    {
      "timestamp": "2026-03-04T10:00:00Z",
      "tokens": 125000,
      "cost": 0.625,
      "requests": 42
    },
    {
      "timestamp": "2026-03-04T10:02:00Z",
      "tokens": 132000,
      "cost": 0.660,
      "requests": 45
    }
  ],
  "timeframe": "day"
}

Export Data

curl "http://localhost:3000/api/tokens?action=export&timeframe=week&format=csv" \
  -H "x-api-key: your-api-key" \
  --output token-usage.csv

Reporting Token Usage

Agents report token usage via:

Heartbeat API

curl -X POST http://localhost:3000/api/agents/{id}/heartbeat \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "status": "idle",
    "tokens": {
      "model": "claude-sonnet-4-20250514",
      "input": 1500,
      "output": 800,
      "cost": 0.0115
    }
  }'

Gateway Events

Gateway-connected agents automatically report token usage via WebSocket token_usage events:

{
  "type": "event",
  "event": "token_usage",
  "payload": {
    "model": "claude-sonnet-4-20250514",
    "sessionId": "clawd-researcher-01",
    "inputTokens": 1500,
    "outputTokens": 800,
    "totalTokens": 2300,
    "cost": 0.0115
  }
}

Model Pricing

Mission Control includes a pricing catalog for common models:

Anthropic Models

claude-4.5-sonnet — $3/M input,$ 15/M output
claude-sonnet-4 — $3/M input,$ 15/M output
claude-3.5-haiku — $1/M input,$ 5/M output

OpenAI Models

gpt-4o — $2.50/M input,$ 10/M output
gpt-4o-mini — $0.15/M input,$ 0.60/M output
o1 — $15/M input,$ 60/M output

Custom Models

For unlisted models, cost is estimated at $0 unless provided explicitly in token reports.

Pricing is managed in src/lib/models.ts. Add custom models by updating the catalog.

Claude Code Session Tracking

Mission Control auto-discovers local Claude Code sessions:

Automatic Scanning

The scheduler scans ~/.claude/projects/ every 60 seconds:

Reads JSONL transcript files
Extracts token usage from API responses
Calculates costs using Claude pricing
Stores in database with source = 'claude-code'

Viewing Claude Sessions

curl "http://localhost:3000/api/claude/sessions?active=1" \
  -H "x-api-key: your-api-key"

Response:

{
  "sessions": [
    {
      "project": "mission-control",
      "model": "claude-sonnet-4",
      "messageCount": 23,
      "totalTokens": 45000,
      "cost": 0.225,
      "active": true,
      "lastActivity": 1735696800000
    }
  ]
}

Claude Code session tracking requires MC_CLAUDE_HOME to be set in .env. Default: ~/.claude

Optimization Strategies

Model Selection

Choose models based on task complexity:

Routine tasks — Use Haiku or GPT-4o-mini for simple operations
Complex reasoning — Use Sonnet-4 or GPT-4o for difficult problems
Code generation — Use Sonnet-4 for high-quality code output
Research — Use Sonnet-4 or o1 for deep analysis

Prompt Engineering

Reduce token usage:

Concise prompts — Remove unnecessary context
Structured output — Request JSON instead of prose
Few-shot examples — Use 1-2 examples instead of 5+
Streaming — Stop generation early when answer is sufficient

Caching

Implement caching for repeated requests:

Cache embeddings for semantic search
Cache API responses for identical prompts
Use model caching features (e.g., Claude prompt caching)

Troubleshooting

No Usage Data Showing

Verify agents are reporting token usage via heartbeat API
Check tokens.json file exists in .data/ directory
Confirm selected timeframe includes activity
Try clicking Refresh in the dashboard

Costs Seem Incorrect

Check model pricing in src/lib/models.ts
Verify token counts in raw data (export JSON)
Confirm model names are normalized correctly
Review agent heartbeat payloads for cost field

Charts Not Loading

Check browser console for errors
Verify Recharts library is installed: pnpm list recharts
Try clearing browser cache
Test API endpoint directly: curl /api/tokens?action=trends

Next Steps

Background Automation

Configure automated cleanup and retention policies

Agent Management

Monitor which agents are consuming the most resources

Get Started

Core Features

Integrations

Deployment

Advanced

​Overview

​Accessing the Dashboard

​Timeframe Selection

​Overview Statistics

Total Tokens

Total Cost

API Requests

Avg Tokens/Request

​Usage Trends Chart

​Chart Features

​Model Usage Breakdown

​Token Usage by Model (Bar Chart)

​Cost Distribution (Pie Chart)

​Performance Insights

​Metrics Cards

Most Efficient Model

Most Used Model

Optimization Potential

​Model Efficiency Comparison

​Alerts & Suggestions

​Alert Types

​Alert Styling

​Detailed Statistics

​Model Performance Table

​Top Sessions by Cost

​Data Export

​Export Formats

​Exporting Data

​Example Export Filenames

​Token Usage API

​Get Usage Stats

​Get Trend Data

​Export Data

​Reporting Token Usage

​Heartbeat API

​Gateway Events

​Model Pricing

​Claude Code Session Tracking

​Automatic Scanning

​Viewing Claude Sessions

​Optimization Strategies

​Model Selection

​Prompt Engineering

​Caching

​Troubleshooting

​Next Steps

Background Automation

Agent Management

Overview

Accessing the Dashboard

Timeframe Selection

Overview Statistics

Usage Trends Chart

Chart Features

Model Usage Breakdown

Token Usage by Model (Bar Chart)

Cost Distribution (Pie Chart)

Performance Insights

Metrics Cards

Model Efficiency Comparison

Alerts & Suggestions

Alert Types

Alert Styling

Detailed Statistics

Model Performance Table

Top Sessions by Cost

Data Export

Export Formats

Exporting Data

Example Export Filenames

Token Usage API

Get Usage Stats

Get Trend Data

Export Data

Reporting Token Usage

Heartbeat API

Gateway Events

Model Pricing

Claude Code Session Tracking

Automatic Scanning

Viewing Claude Sessions

Optimization Strategies

Model Selection

Prompt Engineering

Caching

Troubleshooting

Next Steps