Claude Code Usage

Comprehensive Claude Code Usage monitoring and analysis tools for tracking token consumption, costs, performance metrics, and usage optimization.

Overview

Claude Code Usage tools provide real-time monitoring, analysis, and optimization capabilities for Claude Code token consumption and API usage. These tools help developers track costs, monitor performance, analyze usage patterns, and optimize their Claude Code workflows through detailed metrics, alerts, and reporting features.

⚠️ Usage Notice: Usage monitoring tools require access to Claude Code session files and API logs. Ensure proper permissions and data privacy compliance when implementing monitoring solutions.

Core Tools

Claude Code Usage Monitor

# Install via npm
npm install -g claude-code-usage-monitor

# Install via pip
pip install claude-code-usage-monitor

# Clone from GitHub
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
npm install
npm start

ccusage CLI Tool

# Install ccusage
npm install -g ccusage

# Basic usage analysis
ccusage analyze

# Analyze specific session
ccusage analyze --session session-id

# Generate report
ccusage report --format json

# Real-time monitoring
ccusage monitor --live

Installation and Setup

Usage Monitor Setup

# Start usage monitor
claude-usage-monitor --port 3000

# With configuration file
claude-usage-monitor --config config.json

# Docker deployment
docker run -p 3000:3000 -v ~/.claude:/data claude-usage-monitor

VS Code Extension

# Install from marketplace
code --install-extension suzuki0430.ccusage-vscode

# Manual installation
git clone https://github.com/suzuki0430/ccusage-vscode.git
cd ccusage-vscode
npm install
npm run compile
code --install-extension ccusage-vscode-*.vsix

Raycast Extension

# Install Raycast extension
raycast://extensions/nyatinte/ccusage

# Configure API access
raycast://preferences/extensions/ccusage

Monitoring Commands

Real-time Monitoring

Command	Description
`ccusage monitor`	Start real-time monitoring
`ccusage dashboard`	Open web dashboard
`ccusage status`	Check current usage status
`ccusage alerts`	View active alerts
`ccusage live`	Live usage stream
`ccusage watch`	Watch specific metrics
`ccusage tail`	Tail usage logs

Analysis Commands

Command	Description
`ccusage analyze`	Analyze usage patterns
`ccusage report`	Generate usage report
`ccusage summary`	Usage summary
`ccusage trends`	Usage trend analysis
`ccusage compare`	Compare time periods
`ccusage breakdown`	Detailed breakdown
`ccusage optimize`	Optimization suggestions

Configuration

Monitor Configuration

{
  "monitor": {
    "port": 3000,
    "host": "localhost",
    "updateInterval": 1000,
    "retentionDays": 30,
    "enableAlerts": true
  },
  "claude": {
    "sessionPath": "~/.claude/sessions",
    "logPath": "~/.claude/logs",
    "apiEndpoint": "https://api.anthropic.com",
    "trackModels": ["claude-3-sonnet", "claude-3-haiku", "claude-3-opus"]
  },
  "metrics": {
    "trackTokens": true,
    "trackCosts": true,
    "trackPerformance": true,
    "trackErrors": true,
    "granularity": "minute"
  },
  "alerts": {
    "dailyLimit": 10000,
    "costThreshold": 50.00,
    "errorRate": 0.05,
    "responseTime": 5000
  }
}

Cost Tracking

{
  "costTracking": {
    "enabled": true,
    "currency": "USD",
    "models": {
      "claude-3-opus": {
        "inputCost": 0.000015,
        "outputCost": 0.000075
      },
      "claude-3-sonnet": {
        "inputCost": 0.000003,
        "outputCost": 0.000015
      },
      "claude-3-haiku": {
        "inputCost": 0.00000025,
        "outputCost": 0.00000125
      }
    },
    "budgets": {
      "daily": 25.00,
      "weekly": 150.00,
      "monthly": 500.00
    }
  }
}

Dashboard Features

Web Dashboard

# Access dashboard
http://localhost:3000

# Dashboard sections
- Real-time metrics
- Usage graphs
- Cost analysis
- Session history
- Performance metrics
- Alert management
- Export options

Dashboard Components

Component	Description
`Token Counter`	Real-time token usage
`Cost Tracker`	Current and projected costs
`Session Browser`	Browse session history
`Performance Graph`	Response time metrics
`Error Monitor`	Error rate tracking
`Usage Heatmap`	Usage pattern visualization
`Alert Panel`	Active alerts and notifications

Metrics Display

// Dashboard metrics configuration
const dashboardConfig = {
  widgets: [
    {
      type: "counter",
      metric: "tokens_today",
      title: "Today's Tokens",
      format: "number"
    },
    {
      type: "gauge",
      metric: "cost_today",
      title: "Today's Cost",
      format: "currency",
      max: 50
    },
    {
      type: "chart",
      metric: "tokens_hourly",
      title: "Hourly Usage",
      timeRange: "24h"
    },
    {
      type: "table",
      metric: "top_sessions",
      title: "Top Sessions",
      limit: 10
    }
  ],
  refreshInterval: 5000,
  theme: "dark"
};

Usage Analysis

Token Analysis

# Analyze token usage
ccusage tokens --period today
ccusage tokens --period week
ccusage tokens --period month

# Token breakdown by model
ccusage tokens --by-model

# Token efficiency analysis
ccusage tokens --efficiency

# Token usage trends
ccusage tokens --trends

Cost Analysis

# Cost breakdown
ccusage costs --breakdown

# Cost by time period
ccusage costs --period month

# Cost optimization suggestions
ccusage costs --optimize

# Budget tracking
ccusage costs --budget-status

# Cost projections
ccusage costs --forecast

Performance Analysis

# Response time analysis
ccusage performance --response-time

# Throughput analysis
ccusage performance --throughput

# Error rate analysis
ccusage performance --errors

# Performance trends
ccusage performance --trends

# Bottleneck identification
ccusage performance --bottlenecks

Reporting

Report Generation

# Generate daily report
ccusage report --period today --format pdf

# Weekly summary
ccusage report --period week --format html

# Monthly analysis
ccusage report --period month --format json

# Custom date range
ccusage report --from 2025-07-01 --to 2025-07-15

# Detailed breakdown
ccusage report --detailed --include-sessions

Report Formats

Format	Description
`JSON`	Machine-readable data
`CSV`	Spreadsheet compatible
`HTML`	Web-viewable report
`PDF`	Printable document
`Markdown`	Documentation format
`Excel`	Advanced spreadsheet

Automated Reporting

{
  "automation": {
    "reports": [
      {
        "name": "daily_summary",
        "schedule": "0 9 * * *",
        "format": "email",
        "recipients": ["team@company.com"],
        "template": "daily_template"
      },
      {
        "name": "weekly_analysis",
        "schedule": "0 9 * * 1",
        "format": "pdf",
        "storage": "s3://reports-bucket/weekly/",
        "template": "weekly_template"
      }
    ]
  }
}

Alerting System

Alert Configuration

{
  "alerts": {
    "rules": [
      {
        "name": "high_token_usage",
        "condition": "tokens_per_hour > 5000",
        "severity": "warning",
        "actions": ["email", "slack"]
      },
      {
        "name": "budget_exceeded",
        "condition": "daily_cost > budget.daily * 0.9",
        "severity": "critical",
        "actions": ["email", "sms", "webhook"]
      },
      {
        "name": "high_error_rate",
        "condition": "error_rate > 0.05",
        "severity": "warning",
        "actions": ["slack"]
      }
    ],
    "channels": {
      "email": {
        "smtp": "smtp.gmail.com",
        "from": "alerts@company.com",
        "to": ["admin@company.com"]
      },
      "slack": {
        "webhook": "https://hooks.slack.com/...",
        "channel": "#claude-alerts"
      },
      "webhook": {
        "url": "https://api.company.com/alerts",
        "method": "POST"
      }
    }
  }
}

Alert Types

Alert	Trigger	Action
`Token Limit`	Daily token threshold	Email notification
`Cost Threshold`	Budget percentage	Slack alert
`Error Rate`	High error percentage	Webhook call
`Performance`	Slow response time	Dashboard highlight
`Session Limit`	Max sessions reached	Auto-cleanup

Optimization Features

Usage Optimization

# Analyze optimization opportunities
ccusage optimize --analyze

# Token efficiency suggestions
ccusage optimize --tokens

# Cost reduction recommendations
ccusage optimize --costs

# Performance improvements
ccusage optimize --performance

# Model selection optimization
ccusage optimize --models

Optimization Strategies

{
  "optimization": {
    "strategies": [
      {
        "name": "model_selection",
        "description": "Choose optimal model for task",
        "rules": [
          {
            "condition": "task_complexity < 0.3",
            "recommendation": "claude-3-haiku"
          },
          {
            "condition": "task_complexity >= 0.7",
            "recommendation": "claude-3-opus"
          }
        ]
      },
      {
        "name": "context_optimization",
        "description": "Optimize context window usage",
        "techniques": [
          "context_compression",
          "selective_history",
          "smart_truncation"
        ]
      }
    ]
  }
}

Integration Examples

CI/CD Integration

# GitHub Actions workflow
name: Claude Usage Monitoring
on:
  schedule:
    - cron: '0 */6 * * *'
jobs:
  monitor:
    runs-on: ubuntu-latest
    steps:
      - name: Check Usage
        run: |
          ccusage analyze --format json > usage.json
          ccusage costs --budget-check
      - name: Upload Report
        uses: actions/upload-artifact@v2
        with:
          name: usage-report
          path: usage.json

Slack Integration

// Slack bot for usage monitoring
const { App } = require('@slack/bolt');

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET
});

app.command('/claude-usage', async ({ command, ack, respond }) => {
  await ack();

  const usage = await getClaudeUsage();
  await respond({
    text: `Claude Usage Today:
    Tokens: ${usage.tokens}
    Cost: $${usage.cost}
    Sessions: ${usage.sessions}`
  });
});

Prometheus Integration

# Prometheus configuration
global:
  scrape_interval: 15s
scrape_configs:
  - job_name: 'claude-usage'
    static_configs:
      - targets: ['localhost:3000']
    metrics_path: '/metrics'
    scrape_interval: 30s

API Reference

REST API Endpoints

# Get current usage
GET /api/usage/current

# Get usage history
GET /api/usage/history?period=7d

# Get cost breakdown
GET /api/costs/breakdown

# Get performance metrics
GET /api/performance/metrics

# Get alerts
GET /api/alerts

# Export data
GET /api/export?format=json&period=month

WebSocket API

// Real-time usage updates
const ws = new WebSocket('ws://localhost:3000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  switch(data.type) {
    case 'usage_update':
      updateUsageDisplay(data.usage);
      break;
    case 'alert':
      showAlert(data.alert);
      break;
    case 'cost_update':
      updateCostDisplay(data.cost);
      break;
  }
};

Troubleshooting

Common Issues

# Monitor not starting
- Check port availability
- Verify session file permissions
- Check configuration file syntax
- Review log files

# Missing data
- Verify Claude Code session path
- Check file permissions
- Ensure proper API access
- Review data retention settings

# Performance issues
- Reduce monitoring frequency
- Optimize database queries
- Clear old data
- Check system resources

Debug Commands

# Enable debug mode
DEBUG=ccusage:* ccusage monitor

# Verbose logging
ccusage --verbose analyze

# Test configuration
ccusage config --test

# Validate data sources
ccusage validate --sources