Skip to main content
The crush stats command generates and displays detailed usage statistics including token usage, costs, activity patterns, and tool usage analytics.

​
Usage

crush stats [flags]

​
Description

Generate and display comprehensive usage statistics in a beautiful HTML dashboard. The stats include:
  • Total statistics: Sessions, tokens, costs, messages
  • Daily usage: Token consumption and costs over time
  • Model usage: Which models you use most
  • Hourly patterns: When you’re most active
  • Day of week: Activity by day
  • Recent activity: Last 30 days of usage
  • Tool usage: Which tools are called most frequently
  • Heatmap: Hour-by-day activity visualization
  • Response times: Average AI response times

​
Global Flags

​
--data-dir
string
default:"~/.crush"
Custom Crush data directory. Specify which Crush database to analyze.
Other global flags are also available: --debug

​
Output

The command generates an HTML file with interactive charts and visualizations: 
Stats generated: ~/.crush/stats/index.html
The file is automatically opened in your default browser. If the browser fails to open, the path is displayed for manual opening.

​
Examples

# Generate and view statistics
crush stats

​
Statistics Breakdown

​
Total Stats

Overall usage metrics:
  • Total Sessions: Number of Crush sessions
  • Total Messages: Messages exchanged with AI
  • Total Tokens: Combined prompt and completion tokens
    • Prompt Tokens: Tokens sent to the AI
    • Completion Tokens: Tokens generated by the AI
  • Total Cost: Estimated cost in USD
  • Average Tokens per Session: Mean token usage per session
  • Average Messages per Session: Mean message count per session

​
Usage by Day

Daily breakdown showing:
  • Date
  • Prompt tokens
  • Completion tokens
  • Total tokens
  • Cost
  • Session count

​
Usage by Model

Model usage statistics:
  • Model name (e.g., claude-sonnet-4-20250514)
  • Provider (e.g., anthropic)
  • Message count
Helps identify your most-used models.

​
Usage by Hour

Activity distribution across 24 hours:
  • Hour (0-23)
  • Session count
Shows when you’re most productive with Crush.

​
Usage by Day of Week

Weekly activity patterns:
  • Day name (Sunday through Saturday)
  • Session count
  • Prompt tokens
  • Completion tokens
Identify your most productive days.

​
Recent Activity

Last 30 days of activity:
  • Date
  • Session count
  • Total tokens
  • Cost
Track recent trends in your usage.

​
Tool Usage

Frequency of tool calls:
  • Tool name (e.g., bash, edit, read)
  • Call count
See which tools the AI uses most in your sessions.

​
Hour-Day Heatmap

Visualize activity across hours and days:
  • X-axis: Hours (0-23)
  • Y-axis: Days of week
  • Color intensity: Session count
Identify your peak productivity patterns.

​
Average Response Time

Mean response time from the AI in milliseconds.

​
Generated HTML

The statistics page includes:
  • Interactive charts: Built with JavaScript charting library
  • Responsive design: Works on desktop and mobile
  • Embedded styling: Self-contained HTML file
  • Branding: Crush logo and styling
  • Metadata: Generation date, project name, username

​
File Structure

~/.crush/stats/
└── index.html    # Self-contained HTML dashboard
The HTML file is completely self-contained with embedded:
  • CSS styling
  • JavaScript code
  • SVG graphics
  • Statistics data (JSON)

​
Example Output

When you run the command: 
$ crush stats
Stats generated: /home/user/.crush/stats/index.html
The browser opens showing: 
╔══════════════════════════════════════╗
║        Crush Usage Statistics        ║
║                                      ║
║  Project: ~/dev/my-project          ║
║  User: alice                        ║
║  Generated: 2025-03-11              ║
╚══════════════════════════════════════╝

Total Statistics
├── Sessions: 42
├── Messages: 384
├── Tokens: 1,234,567
│   ├── Prompt: 823,456
│   └── Completion: 411,111
└── Cost: $4.56

[Interactive Charts Below]
- Daily Usage Chart
- Model Usage Pie Chart
- Hourly Activity Bar Chart
- Day of Week Distribution
- Recent Activity Timeline
- Tool Usage Bar Chart
- Hour-Day Heatmap

​
Error Messages

​
No Data Available

no data available: no sessions found in database
Cause: No Crush sessions have been recorded yet. Solution: Use Crush to create some sessions first: 
crush
# or
crush run "test prompt"

​
Failed to Initialize Config

failed to initialize config: <error>
Cause: Configuration file is invalid or data directory doesn’t exist. Solution: 
# Check if config exists
cat ~/.crush/crush.json

# If missing, run crush to create it
crush

​
Failed to Connect to Database

failed to connect to database: <error>
Cause: Database file is missing or corrupted. Solution: 
# Check if database exists
ls -lh ~/.crush/crush.db

# If corrupted, backup and recreate
mv ~/.crush/crush.db ~/.crush/crush.db.backup
crush  # This will recreate the database

​
Browser Doesn’t Open

Could not open browser: <error>
Please open the file manually.
Cause: System browser couldn’t be launched. Solution: Open the displayed file path manually: 
# macOS
open ~/.crush/stats/index.html

# Linux
xdg-open ~/.crush/stats/index.html

# Or specify a browser
firefox ~/.crush/stats/index.html

​
Data Source

Statistics are gathered from the SQLite database at: 
~/.crush/crush.db
The database contains:
  • Sessions table: Session metadata
  • Messages table: All messages with token counts
  • Tool calls: Records of tool invocations
  • Timestamps: For time-based analysis

​
Privacy & Analytics

The stats command:
  • Runs locally: No data is sent to external servers
  • Reads from local DB: Only accesses your local Crush database
  • Generates local HTML: Output is saved to your filesystem
  • No telemetry: Statistics generation doesn’t trigger any metrics

​
Use Cases

​
Cost Tracking

Monitor your AI API spending: 
# Generate stats monthly
crush stats
# Review total cost in the dashboard

​
Usage Optimization

Identify patterns to optimize your workflow:
  • Which models you use most
  • Peak productivity hours
  • Most-used tools
  • Average session length

​
Team Reporting

Share usage insights: 
# Generate stats
crush stats

# Share the HTML file
cp ~/.crush/stats/index.html ~/reports/crush-stats-march.html

​
Billing & Budgeting

Track costs for:
  • Personal budget management
  • Project cost allocation
  • Client billing
  • Team cost analysis

​
Telemetry

Running crush stats triggers an analytics event: 
event.StatsViewed()
This can be disabled with:
  • CRUSH_DISABLE_METRICS=true environment variable
  • DO_NOT_TRACK=true environment variable
  • "disable_metrics": true in crush.json

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us