usage

Usage - Complete API Reference

Track token usage, estimate costs, and analyze AI consumption across sessions and users.

---

Chat Commands

View Usage

/usage                                      Current session usage
/usage today                                Today's total usage
/usage week                                 This week's usage
/usage month                                This month's usage

Detailed Breakdown

/usage breakdown [today]                    Cost breakdown by model
/usage by-model                             Usage by AI model (alias)
/usage by-user                              Usage by user
/usage history [days]                       Historical usage (default 7 days)
/usage estimate <model> <in> <out>          Estimate cost for tokens
/usage user <id> [today]                    User-specific usage

Management

/usage reset                                Clear all usage data

---

TypeScript API Reference

Create Usage Service

import { createUsageService } from 'clodds/usage';

const usage = createUsageService({
  // Storage
  storage: 'sqlite',  // 'sqlite' | 'postgres' | 'memory'
  dbPath: './usage.db',

  // Pricing (per 1M tokens)
  pricing: {
    'claude-3-opus': { input: 15.00, output: 75.00 },
    'claude-3-sonnet': { input: 3.00, output: 15.00 },
    'claude-3-haiku': { input: 0.25, output: 1.25 },
    'gpt-4': { input: 30.00, output: 60.00 },
    'gpt-4o': { input: 5.00, output: 15.00 },
  },

  // Footer mode
  footerMode: 'tokens',  // 'off' | 'tokens' | 'full'
});

Record Usage

// Record a request
await usage.record({
  userId: 'user-123',
  sessionId: 'session-456',
  model: 'claude-3-sonnet',
  inputTokens: 1500,
  outputTokens: 800,
  durationMs: 2300,
  cached: false,
});

Get Session Usage

const session = await usage.getSessionUsage('session-456');

console.log(`Session: ${session.sessionId}`);
console.log(`Requests: ${session.requests}`);
console.log(`Input tokens: ${session.inputTokens.toLocaleString()}`);
console.log(`Output tokens: ${session.outputTokens.toLocaleString()}`);
console.log(`Total tokens: ${session.totalTokens.toLocaleString()}`);
console.log(`Est. cost: $${session.estimatedCost.toFixed(4)}`);
console.log(`Duration: ${session.totalDurationMs}ms`);