get_usage_trends
Analyze usage patterns over time to identify trends and monitor activity in Claude Code sessions.
Instructions
Get usage trends over time to identify patterns
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days_back | No | Number of days to look back (default: 7) |
Implementation Reference
- src/telemetry-service.ts:103-129 (handler)Core handler function that executes the tool logic: queries Prometheus range data for tokens, cost, and sessions over the specified number of days and constructs UsageTrend array.
async getUsageTrends(daysBack: number = 7): Promise<UsageTrend[]> { const endTime = new Date(); const startTime = new Date(endTime.getTime() - (daysBack * 24 * 60 * 60 * 1000)); const [tokensResult, costResult, sessionsResult] = await Promise.all([ this.prometheus.queryRange('claude_code_token_usage_tokens_total', startTime, endTime, '1h'), this.prometheus.queryRange('claude_code_cost_usage_USD_total', startTime, endTime, '1h'), this.prometheus.queryRange('claude_code_session_count_total', startTime, endTime, '1h') ]); const tokensSeries = this.prometheus.getTimeSeries(tokensResult); const costSeries = this.prometheus.getTimeSeries(costResult); const sessionsSeries = this.prometheus.getTimeSeries(sessionsResult); // Combine the series data const trends: UsageTrend[] = []; for (let i = 0; i < tokensSeries.length; i++) { trends.push({ timestamp: tokensSeries[i].timestamp.toISOString(), tokens: tokensSeries[i].value, cost: costSeries[i]?.value || 0, sessions: sessionsSeries[i]?.value || 0 }); } return trends; } - src/index.ts:133-146 (registration)Tool registration in ListToolsRequest handler, defining name, description, and inputSchema with days_back parameter.
{ name: 'get_usage_trends', description: 'Get usage trends over time to identify patterns', inputSchema: { type: 'object', properties: { days_back: { type: 'number', description: 'Number of days to look back (default: 7)', default: 7, }, }, }, }, - src/types.ts:47-52 (schema)Type definition for the output structure UsageTrend used by getUsageTrends.
export interface UsageTrend { timestamp: string; tokens: number; cost: number; sessions: number; } - src/index.ts:320-331 (handler)MCP CallToolRequest dispatcher case that parses arguments, calls the core handler, formats response, and returns MCP content.
case 'get_usage_trends': { const daysBack = typeof args?.days_back === 'number' ? args.days_back : 7; const trends = await this.telemetryService.getUsageTrends(daysBack); return { content: [ { type: 'text', text: this.formatUsageTrends(trends, daysBack), }, ], }; } - src/index.ts:453-469 (helper)Helper function to format the UsageTrend data into a markdown table for the MCP response.
private formatUsageTrends(trends: UsageTrend[], daysBack: number): string { let result = `## Usage Trends (${daysBack} days)\n\n`; if (trends.length === 0) { return result + 'No trend data available.'; } result += '| Time | Tokens | Cost | Sessions |\n'; result += '|------|--------|------|---------|\n'; trends.slice(-10).forEach(trend => { const time = new Date(trend.timestamp).toLocaleString(); result += `| ${time} | ${trend.tokens.toLocaleString()} | $${trend.cost.toFixed(3)} | ${trend.sessions} |\n`; }); return result; }