gemistat

gemini + statistics — Comprehensive Gemini CLI usage analytics that track your token consumption and costs with precision!

⚠️ Under Development: This project is currently in active development. Features and APIs may change. Please report any issues or feedback!

A powerful wrapper for gemini-cli that provides detailed token usage tracking and cost analysis using OpenTelemetry data.

⚠️ Important: Replace your regular gemini commands with bunx gemistat to ensure logs are saved!

Regular gemini commands don't save any logs or usage data. You must use bunx gemistat instead to:

• Automatically capture conversation logs and detailed telemetry
• Enable token usage tracking and cost analytics
• Store data with OpenTelemetry for analysis

# ❌ Don't use regular gemini (no logs saved)
# gemini chat
# gemini --model gemini-2.0-flash-exp

# ✅ Use gemistat instead (logs automatically saved)
bunx gemistat chat
bunx gemistat --model gemini-2.0-flash-exp

Features

• 🎯 Accurate Token Tracking - Uses gemini-cli's native OpenTelemetry system for 100% precision
• 💰 Real-time Cost Analysis - Fetches latest pricing from LiteLLM's comprehensive model database
• 📊 Multiple Report Types - Daily, monthly aggregations with detailed breakdowns
• 🔍 Date Range Filtering - Analyze usage for specific time periods
• 📱 Smart Responsive Tables - Automatically adapts to terminal width with compact mode
• 📄 JSON Export - Machine-readable output for integration with other tools
• 🌐 Offline Mode - Use pre-cached pricing data when network is unavailable
• 🎨 Beautiful Output - Colorful, well-formatted tables for easy reading
• ⚡ Fast Processing - Efficiently handles large telemetry files with streaming parsing

Installation

Quick Start (Recommended)

You can run gemistat directly without installation:

# Using bunx (recommended for speed)
bunx gemistat

# Using npx
npx gemistat@latest

# Using pnpm
pnpm dlx gemistat

💡 Tip: We recommend using bunx instead of npx for a massive speed improvement!

Prerequisites

• gemini-cli installed and configured with API key

Installing gemini-cli

# Install gemini-cli globally
npm install -g @google/generative-ai-cli

# Theen login with your Google account

For detailed setup instructions, see the gemini-cli documentation.

Usage

⚠️ Remember: gemistat acts as an alias for gemini commands with telemetry enabled. Always use bunx gemistat instead of gemini commands to ensure your usage data is captured and logged!

Basic Commands

# Wrapper mode (default) - acts as gemini alias with telemetry enabled
bunx gemistat [gemini-cli-options]
bunx gemistat chat
bunx gemistat --model gemini-2.0-flash-exp
bunx gemistat -p "hello how are you"

# Stats mode - view daily usage statistics (from saved telemetry data)
bunx gemistat daily

# Stats mode - view monthly usage statistics (from saved telemetry data)
bunx gemistat monthly

Command Replacement Guide

Replace all your regular gemini commands with bunx gemistat:

# Chat interactions
# instead of "gemini chat" ...
bunx gemistat chat
# instead of "gemini -p 'Tell me a joke'" ...
bunx gemistat -p "Tell me a joke"

# Model selection
# instead of "gemini --model gemini-2.0-flash-exp" ...
bunx gemistat --model gemini-2.0-flash-exp
# instead of "gemini chat --model gemini-1.5-pro" ...
bunx gemistat chat --model gemini-1.5-pro

# File operations
# instead of "gemini -f document.txt" ...
bunx gemistat -f document.txt
# instead of "gemini chat --file image.png" ...
bunx gemistat chat --file image.png

# All other gemini-cli options work exactly the same
# instead of "gemini [any-options]" ...
bunx gemistat [any-options]

Advanced Usage

# Stats mode - daily reports with filtering (from saved telemetry data)
bunx gemistat daily --since 2024-01-01 --until 2024-01-31
bunx gemistat daily --json                 # JSON output
bunx gemistat daily --compact              # Force compact tables
bunx gemistat daily --offline              # Use cached pricing

# Stats mode - monthly aggregations (from saved telemetry data)
bunx gemistat monthly --since 2024-01 --until 2024-03
bunx gemistat monthly --json

# Custom data directory for stats viewing
bunx gemistat daily --dir /path/to/telemetry/files

💡 More Options: Since gemistat shares similar options with gemistat, please refer to gemistat.com for detailed command-line options and advanced usage patterns.

Example Output

Daily Report

 ╭───────────────────────────────╮
 │                               │
 │  Gemini Usage Report - Daily  │
 │                               │
 ╰───────────────────────────────╯

┌──────────┬───────────────┬──────────┬──────────┬─────────────┬───────────┬─────────────┬───────────┐
│ Date     │ Models        │    Input │   Output │       Cache │     Cache │       Total │      Cost │
│          │               │          │          │      Create │      Read │      Tokens │     (USD) │
├──────────┼───────────────┼──────────┼──────────┼─────────────┼───────────┼─────────────┼───────────┤
│ 2025-08… │ -             │    6,319 │       10 │           0 │         0 │       6,329 │     $0.01 │
│          │ gemini-2.5-p… │          │          │             │           │             │           │
├──────────┼───────────────┼──────────┼──────────┼─────────────┼───────────┼─────────────┼───────────┤
│ Total    │               │    6,319 │       10 │           0 │         0 │       6,329 │     $0.01 │
└──────────┴───────────────┴──────────┴──────────┴─────────────┴───────────┴─────────────┴───────────┘

Configuration

Environment Variables

Customize telemetry file locations:

# Default configuration
~/.gemini/usage/{YYYY-MM-DD}/uuid.jsonl

# Custom directory
GEMISTAT_OUTPUT_DIR=/tmp/gemini-logs ./index.ts chat
# Results in: /tmp/gemini-logs/{YYYY-MM-DD}/uuid.jsonl

Note: Files are now organized by date directories with UUID-based filenames to prevent overwrites during multiple sessions on the same day.

Output Files

• {YYYY-MM-DD}/uuid.jsonl - Raw OpenTelemetry events (auto-generated, organized by date with unique UUID filenames)
• Files are saved to ~/.gemini/usage/ by default
• Each gemini-cli session creates a unique UUID-based file within the appropriate date directory

How It Works

gemistat works by leveraging gemini-cli's built-in OpenTelemetry support to capture detailed usage metrics.

Why You Must Use gemistat Instead of Regular gemini Commands

The Problem: Regular gemini commands don't save any usage data

• No token usage information is captured
• No cost tracking is possible
• No historical usage analysis
• Conversations are lost after the session ends

The Solution: bunx gemistat automatically enables telemetry

• Captures detailed token metrics for each API call
• Records input tokens, output tokens, cached tokens, and more
• Saves all data with timestamps for historical analysis
• Enables accurate cost calculation using live pricing data

Why OpenTelemetry?

Regular gemini-cli logs don't contain token usage information, making it impossible to track consumption or calculate costs. gemistat solves this by enabling OpenTelemetry, which captures detailed token metrics for each API call including input tokens, output tokens, cached tokens, and more.

These OpenTelemetry events are then combined with the latest token pricing data from LiteLLM to calculate accurate costs. This allows gemistat to provide comprehensive usage analytics and cost tracking that wouldn't be possible with standard gemini-cli logs alone.

The Process

1. Telemetry Capture

# gemistat automatically adds these flags to gemini-cli
gemini chat --telemetry --telemetry-target=local --telemetry-outfile=~/.gemini/usage/{YYYY-MM-DD}/uuid.jsonl

2. OpenTelemetry Event Processing

The telemetry file contains structured events like:

{
	"attributes": {
		"event.name": "gemini_cli.api_response",
		"event.timestamp": "2024-01-15T14:30:45.123Z",
		"model": "gemini-1.5-pro",
		"input_token_count": 2100,
		"output_token_count": 856,
		"cached_content_token_count": 450,
		"thoughts_token_count": 0,
		"tool_token_count": 25
	}
}

3. Data Aggregation & Cost Calculation

• Events are parsed and validated using Zod schemas
• Token usage is aggregated by date/month
• Costs are calculated using LiteLLM's live pricing database
• Cache tokens, thoughts tokens, and tool tokens are tracked separately

For detailed information about gemini-cli's telemetry system, see the official telemetry documentation.

Troubleshooting

Common Issues

No usage data found

# Ensure gemini-cli is working first
gemini --version

# Check if telemetry files exist
ls ~/.gemini/usage/

# Try running with explicit directory
bunx gemistat daily --dir ~/.gemini/usage

Sponsors

Star History

License

MIT © @ryoppippi

Related Projects

• ccusage.com - Claude usage analytics and tracking

Credits

• Built for gemini-cli by Google
• Pricing data from LiteLLM
• Inspired by gemistat
• OpenTelemetry integration based on gemini-cli telemetry docs